autowzry-agent

快速开始指南

本指南介绍如何使用QMobaAgent (autowzry-agent)进行数据收集、标记、训练和对战。

---

前置准备

1. 克隆项目

git clone https://github.com/yourusername/autowzry-agent.git
cd autowzry-agent

2. 安装包

# 安装项目包（开发模式）
pip install -e .

重要：这一步会自动安装所有依赖（torch、numpy、h5py、opencv-python等），并将qmoba_agent包安装到Python环境中。使用-e参数意味着代码修改会立即生效，非常适合开发和调试。

3. 配置文件说明

本项目使用两种配置文件：

• agent配置文件（config/agent.config.yaml）：本项目的训练配置（训练参数、buffer设置等）
• autowzry配置文件（config/config.device.yaml）：图像识别库的设备连接配置

在线模式需要配置autowzry配置文件，编辑 config/config.device.yaml：

LINK_dict:
  0: Android:///127.0.0.1:5555  # 修改为你的设备地址

离线模式不需要设备配置，可以直接使用视频文件进行训练。

详细配置说明见后文”配置文件”部分。

---

完整训练流程

步骤1：收集数据

方式1：从视频收集（离线模式，推荐）

python scripts/collect_from_video.py --video workspace/videos/1.mp4 --interval 1.0 --max-frames 400 --output workspace/episodes/data1.hdf5

参数说明：

• --video: 视频文件路径（必需）
• --interval: 采样间隔（秒），例如1.0表示每秒采样1帧（推荐）
• --frame-interval: 帧间隔，例如2表示每3帧采样1帧（与–interval二选一）
• --max-frames: 最大采集帧数（可选，默认读取整个视频）
• --output: 输出文件完整路径（可选，默认workspace/episodes/episode_YYYYMMDD_HHMMSS.hdf5）
• --config: agent配置文件（可选，默认使用Config.default()）

方式2：从设备收集（在线模式）

python scripts/collect_from_device.py --interval 1.0 --max-frames 50 --output workspace/episodes/data2.hdf5

参数说明：

• --config: agent配置文件路径（可选，默认使用Config.default()）
• --duration: 采集时长（秒）
• --max-frames: 最大采集帧数
• --interval: 采样间隔（秒），例如1.0表示每秒采样1帧
• --output: 输出文件完整路径（可选，默认workspace/episodes/episode_YYYYMMDD_HHMMSS.hdf5）

输出：生成HDF5文件，例如 workspace/episodes/data1.hdf5 或 workspace/episodes/data2.hdf5

---

步骤1.5：提取指定帧范围（可选）

如果收集的数据包含开头无效帧，可以提取指定帧范围：

python scripts/extract_data.py --file workspace/episodes/data1.hdf5 --frame-range 2 376

参数说明：

• --file: 输入HDF5文件路径（必需）
• --frame-range: 帧范围（开始帧 结束帧）（必需）
• --output: 输出文件路径（可选，默认自动生成）
• --config: 同collect_from_video.py

输出：自动生成新文件名 workspace/episodes/data1_F2_E376.hdf5

• 保持原始帧编号（frame_000002 到 frame_000376）
• 添加attrs记录：original_file, original_frame_count, extracted_range, extracted_at

特点：

• 自动边界修正：end_frame超过总帧数时自动调整为总帧数
• 单一职责：只负责提取，不标记、不训练

---

步骤2：标记数据

为收集的数据添加action和state标签：

python scripts/label_data.py --file workspace/episodes/data1_F2_E376.hdf5

参数说明：

• --file: 要标记的HDF5文件路径（必需）
• --overwrite: 覆盖已有字段（可选，默认跳过已存在的字段）
• --config: agent配置文件路径（可选）

输出：HDF5文件中添加 state_*, action_* 字段

注意：enabled_states 和 enabled_actions 从配置文件读取，默认为：

• enabled_states: [‘in_battle’, ‘dead’, ‘alive’, ‘kill’, ‘assist’]
• enabled_actions: [‘move’]

---

步骤3：训练模型

使用标记好的数据训练模型：

python scripts/train.py --files workspace/episodes/data1_F2_E376.hdf5 workspace/episodes/data2.hdf5

参数说明：

• --files: 训练数据文件列表（必需，可以指定多个文件，用空格分隔）
• --config: agent配置文件（可选，默认使用Config.default()）
• --output: 输出模型路径（可选，默认workspace/checkpoints/model_{model_mode}.pth）

输出：模型保存到 workspace/checkpoints/model_mini.pth（mini模式）或 model_full.pth（full模式）

---

步骤4：模型测试与对战

方式1：离线测试（使用视频）

python scripts/battle.py --model workspace/checkpoints/model_mini.pth --video workspace/videos/1.mp4 --max-steps 50 --interval 1.0 --record-interval 1 --output workspace/episodes/battle_record.hdf5

方式2：在线对战（连接设备）

python scripts/battle.py --model workspace/checkpoints/model_mini.pth --max-steps 50

参数说明：

• --model: 模型文件路径（必需）
• --config: agent配置文件（可选，默认使用Config.default()）
• --video: 视频文件路径（离线测试模式）
• --interval: 动作执行间隔（秒，可选，默认0.1秒适合在线对战，离线测试推荐1.0秒）
• --max-steps: 最大步数（可选，默认无限制）
• --record-interval: 录制间隔（秒，可选，默认不录制）
• --output: 录制输出文件路径（HDF5格式，配合–record-interval使用，默认workspace/episodes/battle_YYYYMMDD_HHMMSS.hdf5）

按 Ctrl+C 停止

录制说明：

• 录制文件包含：画面（image）、时间戳（timestamp）、模型输出Q值（q_values）
• 使用流式写入，内存占用小，适合长时间录制
• 录制数据可用于分析模型决策过程

---

【Debug测试用】检查Buffer数据

用于验证TrainingBuffer是否正确加载数据，检测异常reward值。非必需步骤，仅在调试时使用。

python scripts/check_buffer.py --files workspace/episodes/data1_F2_E376.hdf5 workspace/episodes/data2.hdf5

参数说明：

• --files: 输入HDF5文件路径（可以指定多个）
• --output: 输出HDF5文件路径（可选，默认保存到 workspace/buffer_check/buffer_samples_YYYYMMDD_HHMMSS.hdf5）
• --threshold: 异常reward阈值（可选，默认0.1）
• --config: agent配置文件（可选，默认使用Config.default()）

功能：

• 加载数据到TrainingBuffer
• 检测绝对值大于等于threshold的异常reward
• 输出异常样本的详细信息到屏幕
• 保存所有buffer数据到HDF5供人工检查

---

开发者工具

端到端自动化测试

test_pipeline.py 用于自动化测试完整训练流程，适合开发调试使用。

python scripts/test_pipeline.py --video workspace/videos/1.mp4 --max-frames 100 --epochs 10

参数说明：

• --video: 视频文件路径（默认workspace/videos/1.mp4）
• --max-frames: 收集帧数（默认100）
• --interval: 采样间隔（秒，默认1.0）
• --extract-range: 提取帧范围（默认50-100）
• --epochs: 训练轮数（默认10）

功能：自动执行6个步骤

1. 从视频收集数据
2. 标记数据（动作+奖励）
3. 提取数据子集
4. 检查buffer数据
5. 训练模型
6. 测试模型（离线）

输出目录：workspace/test_pipeline/

注意：这是开发调试工具，普通用户不需要使用。

---

配置文件

本项目使用两种配置文件：

agent配置文件 (config/agent.config.yaml)

用途：本项目的训练配置，包含训练参数、buffer设置、模型配置等。

生成默认配置：

python config/config.py

配置文件包含：

• 训练参数（epochs、batch_size、learning_rate等）
• Buffer设置（容量、双帧模式等）
• 模型配置（模式选择：mini/full/high）
• 启用的状态和动作
• Checkpoint设置

详细配置说明见 config/agent.config.yaml 文件内的注释。

autowzry配置文件 (config/config.device.yaml)

用途：图像识别库的设备连接配置，仅在线模式需要。

配置示例：

LINK_dict:
  0: Android:///127.0.0.1:5555  # 设备连接地址

# 其他autowzry相关配置...

说明：

• 离线模式（使用视频）不需要配置此文件
• 在线模式需要配置设备连接信息
• agent配置文件通过autowzry_config字段引用此文件