| # 开发日志 - Development Log |
|
|
| > 记录项目开发历程、重要决策和关键里程碑 |
|
|
| --- |
|
|
| ## 📅 时间线总览 |
|
|
| ``` |
| 2025-10 ━━ 项目初期探索 |
| 2025-11 ━━ 核心系统开发 |
| 2026-01 ━━ 文档完善和规模化准备 |
| ``` |
|
|
| --- |
|
|
| ## 2026 年 1 月 |
|
|
| ### 2026-01-20: 文档系统完善 |
|
|
| **完成工作**： |
| - ✅ 创建完整的代码指南（CODE_GUIDE.md） |
| - ✅ 创建项目状态快照（PROJECT_STATUS.md） |
| - ✅ 完善数据源说明（dataset_source.md） |
| - ✅ 创建开发日志（DEVELOPMENT_LOG.md） |
|
|
| **目标**： |
| - 为 AI Agent 提供完整的项目理解文档 |
| - 方便后续快速上手和协作 |
|
|
| --- |
|
|
| ## 2025 年 11 月 |
|
|
| ### 2025-11-11: Special Token v2 训练 |
|
|
| **训练配置**： |
| - 模型版本：Special Token v2 |
| - Checkpoint：checkpoint-70 |
| - 训练数据：~100 条样本 |
|
|
| **改进点**： |
| - 完整 merge 版本 |
| - 更好的 token 格式 |
|
|
| **输出**： |
| - 权重保存在：`weights_reward_sft_special_token/v2-20251110-235126/` |
|
|
| **决策**： |
| - 使用特殊 token 格式可以更好地结构化输出 |
| - 但需要更多训练数据才能看到明显效果 |
|
|
| --- |
|
|
| ### 2025-11-10: 改进版训练和 Special Token 实验 |
|
|
| #### Special Token v1 训练 |
|
|
| **训练配置**： |
| - 模型版本：Special Token v1 |
| - Checkpoint：checkpoint-70 |
| - 数据格式：使用特殊 token 标记（如 `<|stage|>`, `<|reward|>`） |
|
|
| **输出**： |
| - 权重：`weights_reward_sft_special_token/v1-20251110-234131/` |
|
|
| **观察**： |
| - Special token 格式有助于模型理解结构化输出 |
| - 但需要在推理时正确解析 token |
|
|
| --- |
|
|
| #### Special Token v0 训练 |
|
|
| **时间**：2025-11-10 23:21 |
|
|
| **训练配置**： |
| - 模型版本：Special Token v0 |
| - Checkpoint：checkpoint-7 |
|
|
| **输出**： |
| - 权重：`weights_reward_sft_special_token/v0-20251110-232149/` |
|
|
| --- |
|
|
| #### 改进版 SFT 训练（v1） |
|
|
| **时间**：2025-11-10 23:01 |
|
|
| **训练配置**： |
| - 模型版本：v1 |
| - Checkpoint：checkpoint-7 |
| - 数据：改进版标注数据（~100 条） |
|
|
| **改进点**： |
| - 使用滑动窗口标注的数据 |
| - 更准确的奖励组件对齐 |
|
|
| **输出**： |
| - 权重：`weights_reward_sft/v1-20251110-230134/` |
|
|
| **决策**： |
| - 确认滑动窗口标注模式的有效性 |
| - 决定在扩大数据规模时继续使用此模式 |
|
|
| --- |
|
|
| ### 2025-11-05: 基础版 SFT 训练（v0） |
|
|
| **时间**：2025-11-05 17:12 |
|
|
| **训练配置**： |
| - 模型版本：v0（基础版） |
| - Checkpoint：checkpoint-28 |
| - 数据：基础版标注数据（~100 条） |
|
|
| **输出**： |
| - 权重：`weights_reward_sft/v0-20251105-171242/` |
|
|
| **里程碑**： |
| - 🎉 **首次完成端到端训练** |
| - 验证了整个流程的可行性：数据提取 → 标注 → 训练 |
|
|
| **观察**： |
| - 小规模数据训练的模型性能有限 |
| - 需要扩大数据规模 |
|
|
| **决策**： |
| - 继续改进标注系统 |
| - 准备扩大数据规模 |
|
|
| --- |
|
|
| ## 2025 年 10 月 |
|
|
| ### 2025-10-xx: 改进版标注系统开发 |
|
|
| **关键改进**： |
|
|
| 1. **动态任务描述** |
| - 自动从 metadata JSON 提取任务描述 |
| - 动态插入到 GPT prompt |
| - 提高标注的任务相关性 |
|
|
| 2. **滑动窗口分析** |
| - 引入 WINDOW_SIZE 和 WINDOW_STRIDE 参数 |
| - 连续帧分析，捕捉时序动态 |
| - 上下文传递机制 |
|
|
| 3. **奖励指标对齐** |
| - 与仿真数据对齐：5 个奖励组件 |
| - 6 个操作阶段定义 |
| - 综合指标计算 |
|
|
| **输出脚本**： |
| - `api_batch_improved.py` |
| - `api_batch_improved_v2.py`（Claude 版本） |
|
|
| **决策依据**： |
| - 单次标注所有帧无法捕捉运动平滑度 |
| - 需要时序信息来判断进度和趋势 |
| - 仿真数据的奖励定义更精确，应该对齐 |
|
|
| --- |
|
|
| ### 2025-10-xx: 数据统计和分析 |
|
|
| **完成工作**： |
| - DROID 失败轨迹统计脚本（`count_failure_trajectories.py`） |
| - 视频帧率统计脚本（`check_video_framerate.py`） |
|
|
| **发现**： |
| - 总共 15,157 条 failure 轨迹 |
| - 主要数据源：AUTOLab (23.9%), PennPAL (16.5%) |
| - Top 任务类型：Move object into container (2,699 条) |
|
|
| **决策**： |
| - 使用 balanced 采样策略确保任务类型覆盖 |
| - 优先处理高频任务类型 |
|
|
| --- |
|
|
| ### 2025-10-xx: HuggingFace 数据集工具开发 |
|
|
| **开发工具**： |
| - `prepare_hf_dataset.py`：数据集准备和采样 |
| - `upload_to_huggingface.py`：上传到 HuggingFace Hub |
| - `quick_start.sh`：一键运行脚本 |
|
|
| **采样策略设计**： |
| 1. **balanced**：每个任务类别采样相同数量 |
| 2. **random**：完全随机采样 |
| 3. **proportional**：按原始分布比例采样 |
|
|
| **决策**： |
| - 推荐使用 balanced 策略保证任务多样性 |
| - 提供灵活的配置选项 |
|
|
| **文档**： |
| - `data_sta/README_HF_DATASET.md` |
| - `data_sta/UPLOAD_GUIDE.md` |
|
|
| --- |
|
|
| ### 2025-10-xx: 基础标注系统开发 |
|
|
| **开发脚本**： |
| - `api.py`：单视频标注（原型） |
| - `api_batch.py`：批量视频标注（基础版） |
|
|
| **功能**： |
| - 从视频提取帧 |
| - 调用 GPT-4o API 进行标注 |
| - 输出 JSONL 格式 |
|
|
| **问题**： |
| - 无法捕捉时序动态 |
| - 任务描述固定，不够灵活 |
| - 奖励指标定义不够清晰 |
|
|
| **决策**： |
| - 需要改进标注系统 → 引入滑动窗口 |
|
|
| --- |
|
|
| ### 2025-10-xx: 数据处理流水线开发 |
|
|
| **开发脚本**： |
| 1. `video_process.py`：从 TFDS 提取视频 |
| 2. `extract_frames_to_images.py`：提取帧图片 |
| 3. `convert_to_sft.py`：转换为 SFT 训练格式 |
|
|
| **设计决策**： |
|
|
| 1. **视频提取** |
| - 拼接 wrist_image_left + exterior_image_1_left |
| - 15fps，h264 编码 |
| - 保存元数据 JSON |
| |
| 2. **帧提取** |
| - 支持 mirror 和 flat_hash 两种存储模式 |
| - 生成索引文件方便追溯 |
|
|
| 3. **格式转换** |
| - 两阶段转换：中间格式 → 最终格式 |
| - 适配 ms-swift 训练框架 |
|
|
| --- |
|
|
| ### 2025-10-xx: 项目启动 |
|
|
| **初始目标**： |
| - 训练一个奖励模型用于机器人操作 |
| - 输入：视频帧 |
| - 输出：阶段、奖励、失败检测 |
|
|
| **技术选型**： |
| - 基座模型：Qwen-VL（开源 + 性能平衡） |
| - 标注工具：GPT-4o（高质量 ground truth） |
| - 训练框架：ms-swift（简单易用） |
| - 数据集：DROID（真机数据）+ 仿真数据 |
|
|
| **关键决策**： |
| 1. 使用 GPT-4o 生成标注而非人工标注 |
| - 原因：成本低、速度快、可扩展 |
| - 风险：质量需要验证 |
|
|
| 2. 采用 SFT 而非从头训练 |
| - 原因：数据量有限（数千条） |
| - 风险：基座模型的 bias |
|
|
| 3. 真机数据 + 仿真数据混合 |
| - 原因：仿真数据标注精确，真机数据真实 |
| - 风险：域迁移问题 |
|
|
| --- |
|
|
| ## 重要决策记录 |
|
|
| ### 决策 1: 使用滑动窗口标注模式 |
|
|
| **时间**：2025-11-05 |
|
|
| **背景**： |
| - 基础版一次性标注所有帧无法捕捉运动平滑度 |
| - 需要时序信息判断进度和趋势 |
|
|
| **决策**： |
| - 引入滑动窗口（WINDOW_SIZE=5, STRIDE=3） |
| - 上下文传递机制 |
| |
| **结果**： |
| - ✅ 标注质量明显提升 |
| - ✅ 能够捕捉运动的连续性 |
| - ⚠️ API 调用成本增加（但可接受） |
| |
| --- |
| |
| ### 决策 2: 对齐仿真奖励指标 |
| |
| **时间**：2025-10-xx |
| |
| **背景**： |
| - 仿真数据有精确的奖励组件定义 |
| - GPT 标注缺乏统一标准 |
| |
| **决策**： |
| - 定义 5 个奖励组件：reachout, grasp, collision, fall, smooth |
| - 定义 6 个操作阶段：reach, grasp, lift, move, place, retract |
| - 在 prompt 中明确指导 GPT 遵循此标准 |
| |
| **结果**： |
| - ✅ 标注更加结构化 |
| - ✅ 便于与仿真数据混合训练 |
| - ⚠️ 需要验证 GPT 理解是否准确 |
| |
| --- |
| |
| ### 决策 3: 采用 Special Token 格式 |
| |
| **时间**：2025-11-10 |
| |
| **背景**： |
| - JSON 格式输出有时不稳定 |
| - 需要更明确的结构化输出标记 |
| |
| **决策**： |
| - 引入特殊 token：`<|stage|>`, `<|reward|>` 等 |
| - 在训练数据中使用此格式 |
| |
| **结果**： |
| - ⚠️ 效果待验证（数据量太小） |
| - ✅ 理论上应该有帮助 |
| - ❌ 推理时需要额外的 token 解析 |
| |
| **后续行动**： |
| - 等待大规模训练后再评估效果 |
| |
| --- |
| |
| ### 决策 4: HuggingFace 数据集管理 |
| |
| **时间**：2025-10-xx |
| |
| **背景**： |
| - 数据分散在本地，不便管理 |
| - 希望公开数据集供社区使用 |
| |
| **决策**： |
| - 开发 HuggingFace 数据集准备工具 |
| - 采用 balanced 采样策略 |
| - 提供完整的上传流程 |
| |
| **结果**： |
| - ✅ 数据管理更加规范 |
| - ✅ 便于后续扩展 |
| - ⏳ 尚未正式上传到 HuggingFace（等待大规模标注） |
| |
| --- |
| |
| ## 技术栈演进 |
| |
| ### 标注工具 |
| |
| | 阶段 | 工具 | 原因 | |
| |------|------|------| |
| | 初期 | GPT-4o | 高质量、可扩展 | |
| | 中期 | + Claude | 备选方案 | |
| | 未来 | + 本地 Qwen-VL | 降低成本 | |
| |
| ### 训练框架 |
| |
| | 阶段 | 框架 | 原因 | |
| |------|------|------| |
| | 初期 | ms-swift | 简单易用，快速验证 | |
| | 未来 | 可能迁移到其他框架 | 根据需求调整 | |
| |
| --- |
| |
| ## 遇到的问题和解决方案 |
| |
| ### 问题 1: GPT 标注不一致 |
| |
| **现象**： |
| - 同一视频多次标注结果不同 |
| - stage 有时会跳跃或倒退 |
| |
| **分析**： |
| - GPT 理解有随机性 |
| - prompt 不够明确 |
| |
| **解决方案**： |
| - 降低 temperature（0.1） |
| - 在 prompt 中强调 stage 单调性 |
| - 使用滑动窗口 + 上下文传递 |
| |
| **状态**：⚠️ 部分改善，仍需人工质量评估 |
| |
| --- |
| |
| ### 问题 2: 数据量不足 |
| |
| **现象**： |
| - 当前只有 ~100 条训练数据 |
| - 模型性能有限 |
| |
| **分析**： |
| - 标注成本和时间限制 |
| |
| **解决方案**： |
| - 优先扩大标注规模（目标 2500+ 条） |
| - 采用 balanced 采样保证多样性 |
| |
| **状态**：⏳ 待执行 |
| |
| --- |
| |
| ### 问题 3: Success vs Failure 不平衡 |
| |
| **现象**： |
| - 当前主要是 failure 数据 |
| - Success 数据严重不足 |
| |
| **分析**： |
| - 项目初期聚焦于失败检测 |
| - DROID 数据集 failure 更容易识别 |
| |
| **解决方案**： |
| - 从 DROID success 目录采样 |
| - 目标比例：success:failure = 1:2 |
| |
| **状态**：📋 待执行 |
| |
| --- |
| |
| ## 经验教训 |
| |
| ### ✅ 做对的事 |
| |
| 1. **早期建立完整流水线** |
| - 从数据提取到训练的端到端流程 |
| - 便于快速迭代 |
| |
| 2. **使用 GPT 生成标注** |
| - 成本低、速度快 |
| - 质量可控（通过 prompt 工程） |
| |
| 3. **滑动窗口标注** |
| - 显著提升标注质量 |
| - 捕捉时序动态 |
| |
| 4. **完善的文档** |
| - 便于协作和知识传递 |
| - AI Agent 可快速上手 |
| |
| ### ⚠️ 可以改进的 |
| |
| 1. **应该更早进行质量评估** |
| - 应该在标注 100 条后就进行人工抽检 |
| - 避免大规模标注后发现质量问题 |
| |
| 2. **应该更早扩大数据规模** |
| - 100 条数据训练效果有限 |
| - 应该尽快扩展到 1000+ 条 |
| |
| 3. **应该更早整合仿真数据** |
| - 仿真数据标注精确，应该充分利用 |
| - 真机 + 仿真混合训练可能效果更好 |
| |
| --- |
| |
| ## 下一步计划 |
| |
| 详见：[NEXT_STEPS.md](./NEXT_STEPS.md) |
| |
| **优先级 P0**： |
| 1. ⏳ 扩大标注规模（100 → 2500+ 条） |
| 2. ⏳ 人工质量评估（Golden Set） |
| 3. ⏳ 大规模模型训练 |
| 4. ⏳ 建立评估体系 |
| |
| --- |
| |
| ## 参考资料 |
| |
| ### 相关论文 |
| |
| - DROID Dataset Paper |
| - Vision-Language Models for Robotics |
| - Reward Modeling for RL |
| |
| ### 相关项目 |
| |
| - OpenVLA |
| - RT-1, RT-2 |
| - ALOHA |
| |
| --- |
| |
| ## 附录 |
| |
| ### 命名约定 |
| |
| - `labels_*.jsonl`：标注文件 |
| - `sft_*.json`：SFT 训练数据 |
| - `v<N>-<YYYYMMDD>-<HHMMSS>`：模型版本命名 |
| - `checkpoint-<N>`：训练检查点 |
|
|
| ### 目录结构约定 |
|
|
| ``` |
| project_root/ |
| ├── api_*.py # API 调用脚本 |
| ├── video_*.py # 视频处理脚本 |
| ├── extract_*.py # 提取脚本 |
| ├── convert_*.py # 转换脚本 |
| ├── data/ # 本地数据 |
| ├── data_sta/ # 数据统计工具 |
| ├── output/ # 输出文件 |
| ├── weights_*/ # 模型权重 |
| ├── docs/ # 文档 |
| └── caption/ # 视频描述生成 |
| ``` |
|
|
| --- |
|
|
| 最后更新：2026-01-20 |
|
|
