docs/DEVELOPMENT_LOG.md

# 开发日志 - 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