autowzry-agent

配置管理改进与流式HDF5写入

日期: 2025-11-24 类型: 架构改进

---

改动概述

本次开发完成两个核心改进：配置管理统一化和流式HDF5写入机制，解决内存爆炸问题并提升代码一致性。

---

1. 配置管理改进

1.1 新增 use_autowzry_lite 参数

修改文件: config/config.py, config/agent.config.yaml

改动内容：

• 添加 use_autowzry_lite: bool = True 配置参数
• 设置autowzry_lite为默认库（True使用本地autowzry_lite，False使用已安装的autowzry）
• 更新from_yaml()和save_yaml()方法支持新参数

原因：明确控制autowzry库来源，便于开发和部署环境切换。

1.2 动态导入autowzry

修改文件: environment/compatibility.py

改动内容：

• 移除全局autowzry导入
• 在CompatibilityLayer.init()中根据config.use_autowzry_lite动态导入
• 统一初始化逻辑：所有情况都使用wzry_task(connect=False)，延迟连接
• 简化代码，移除冗余的source检查

原因：避免在配置加载前导入，确保根据配置选择正确的库。

1.3 统一脚本参数行为

修改文件: scripts/train.py, scripts/battle.py, scripts/collect_from_device.py

改动内容：

• 所有脚本的–config参数默认值从固定路径改为None
• 当–config为None时，使用Config.default()
• 确保Config.default()与agent.config.yaml一致

原因：解决训练和对战时action space不匹配的问题，保持配置一致性。

---

2. 流式HDF5写入机制

2.1 问题分析

原有实现问题：

• collect_from_video.py、collect_from_device.py、battle.py都在内存中积累所有帧
• 长时间采集导致内存占用GB级（15分钟@1fps = 900帧 × 2MB ≈ 1.8GB）
• 最后一次性保存时可能卡顿

2.2 StreamingRecorder类

新增文件内容: data/data_manager.py

新增类：

class StreamingRecorder:
    """流式HDF5记录器 - 边记录边写入磁盘，避免内存爆炸"""

    def __init__(filepath):
        # 初始化HDF5文件，设置recording_mode='streaming'

    def append_frame(frame_data: Dict[str, Any]):
        # 立即写入一帧到HDF5（支持任意字段）
        # 内存占用仅为单帧大小

    def finalize() -> str:
        # 完成记录，添加finished_at时间戳

    def get_frame_count() -> int:
        # 获取已记录的帧数

特点：

• 每次append_frame()立即写入磁盘（gzip压缩）
• 内存占用从GB级降至MB级（单帧大小）
• 支持任意字段（image, timestamp, q_values等）
• 即使程序崩溃，已写入数据不丢失

2.3 统一采集流程

修改文件: data/data_manager.py

改动内容：

• 添加create_streaming_recorder()工厂方法
• 重构collect()方法，使用StreamingRecorder替代内存列表
• 标记save()方法为deprecated（保留用于向后兼容）

效果：

• collect_from_video.py和collect_from_device.py无需修改，自动享受流式写入
• 所有采集场景统一使用同一套流式写入逻辑

2.4 battle.py录制功能

修改文件: scripts/battle.py

新增参数：

• --record-interval: 录制间隔（秒），例如1.0表示每秒录制一帧
• --output: 输出HDF5文件路径

改动内容：

• 使用create_streaming_recorder()创建流式记录器
• 在主循环中按间隔调用append_frame()
• 记录三个字段：image（原始画面）、timestamp（时间戳）、q_values（模型输出）
• 战斗结束或中断时调用finalize()完成记录

用途：

• 记录模型在线/离线对战过程
• q_values可用于分析模型决策过程
• 数据可用于后续训练或调试

示例：

# 离线测试并录制
python scripts/battle.py --model checkpoints/model.pth --video moive/1.mp4 --interval 1.0 --record-interval 1.0 --output battle_test.hdf5

# 在线对战并录制
python scripts/battle.py --model checkpoints/model.pth --interval 1.0 --record-interval 1.0 --output battle_online.hdf5

---

3. 其他修复

3.1 AMP弃用警告修复

修改文件: core/trainer.py

改动内容：

• 将torch.cuda.amp.GradScaler()改为torch.amp.GradScaler('cuda')
• 适配PyTorch新版本API

3.2 execute_move()稳定性修复

修改文件: environment/compatibility.py

改动内容：

• 将list.index(max(move))改为np.argmax(move_array)
• 添加阈值检查：当max_value < 1e-6时跳过移动
• 避免重复最大值导致的不稳定行为

---

4. 配置文件更新

修改文件: config/agent.config.yaml

更新内容：

• 添加 use_autowzry_lite: true
• 添加 enabled_states: [in_battle, dead, alive, kill, assist]
• 更新 enabled_actions: ['move']（默认只启用move）
• 调整训练参数：num_epochs=160, batch_size=4

---

5. 影响范围

5.1 用户可见变化

1. 内存占用大幅降低：长时间采集不再有内存爆炸风险
2. battle.py新增录制功能：可记录模型输出用于分析
3. 配置更明确：use_autowzry_lite参数清晰控制库来源

5.2 开发者变化

1. 新API：data_manager.create_streaming_recorder()
2. 废弃API：data_manager.save()（改用collect()或StreamingRecorder）
3. HDF5新格式：battle.py录制的文件包含q_values字段

---

6. 测试建议

1. 测试长时间采集（>1000帧），观察内存占用
2. 测试battle.py录制功能，检查q_values字段完整性
3. 测试中断场景，确认数据正确保存
4. 测试use_autowzry_lite=false时能否正常导入已安装的autowzry

---

总结

本次改进从根本上解决了内存爆炸问题，将所有采集场景统一为流式写入，显著提升系统稳定性。同时完善了配置管理，修复了脚本参数不一致导致的action space错误。battle.py新增的录制功能为模型分析和调试提供了强大工具。