Quick Start Guide for AI Agents
这份文档专门为 AI Agent 快速理解项目而设计
项目一句话描述
目标：训练一个视觉奖励模型，输入机器人操作视频帧，输出奖励信号（阶段、分数、是否失败）。
核心概念速查
输入
机器人操作视频（真机/仿真）
↓
抽帧为图片序列
输出
{
"stage": 0-5, // 操作阶段 (reach/grasp/lift/move/place/retract)
"reward": 0.0-1.0, // 综合奖励
"success_prob": 0.0-1.0, // 成功概率
"failure": 0/1 // 是否失败
}
6 个操作阶段
| 索引 | 名称 | 含义 |
|---|---|---|
| 0 | reach | 伸手接近 |
| 1 | grasp | 抓取 |
| 2 | lift | 抬起 |
| 3 | move | 移动 |
| 4 | place | 放置 |
| 5 | retract | 收回 |
5 个奖励组件
| 组件 | 含义 |
|---|---|
| reachout | 接近目标进度 |
| grasp | 抓取质量 |
| collision | 碰撞惩罚 |
| fall | 掉落惩罚 |
| smooth | 运动平滑度 |
项目结构速查
RewardModel/
├── api_batch_improved.py # 🔑 GPT 标注主脚本
├── api_batch_hf_dataset.py # 处理 HuggingFace 数据集
├── convert_to_sft.py # 转换为训练格式
├── extract_frames_to_images.py # 抽帧脚本
│
├── caption/ # Qwen VL 推理
│ └── infer_caption_batch.py
│
├── data_sta/ # 数据统计和上传
│ └── prepare_hf_dataset.py
│
├── data/ # 数据存储
│ ├── cokecan-50/ # 仿真数据
│ └── sft_*.json # 训练数据
│
├── output/ # 标注输出
│ └── labels_*.jsonl
│
├── weights_reward_sft*/ # 模型权重
│
└── docs/ # 文档 (你正在读的)
├── PROJECT_OVERVIEW.md
├── CURRENT_PROGRESS.md
└── NEXT_STEPS.md
常用命令
1. 运行 GPT 标注
cd /home/jqliu/projects/RewardModel
export OPENAI_API_KEY="your-key"
python api_batch_improved.py
配置项 (在文件顶部修改)：
MAX_VIDEOS = 10 # 处理多少条
START_INDEX = 0 # 从第几条开始
USE_SLIDING_WINDOW = True # 是否用滑动窗口
2. 运行 Qwen VL 标注
cd /home/jqliu/projects/RewardModel/caption
python infer_caption_batch.py
3. 抽帧
python extract_frames_to_images.py
4. 转换训练格式
python convert_to_sft.py
数据位置速查
| 数据类型 | 位置 |
|---|---|
| DROID 原始数据 | /playpen-ssd/dataset/droid_raw/1.0.1/ |
| fangyu 仿真 | /playpen-ssd/yufang/projects/reward/ |
| yangyue 失败 | /playpen-ssd/dataset/libero_failures/ |
| 本地仿真 | ./data/cokecan-50/ |
| 训练数据 | ./data/sft_*.json |
| 模型权重 | ./weights_reward_sft*/ |
当前状态一览
| 模块 | 状态 |
|---|---|
| 数据处理流水线 | ✅ 完成 |
| GPT 标注系统 | ✅ 完成 |
| Qwen VL 推理 | ✅ 完成 |
| SFT 训练 | ✅ 完成 (小规模) |
| 大规模标注 | ⏳ 待做 |
| 模型评估 | ⏳ 待做 |
下一步优先级
- 🔴 扩大标注规模：从 ~100 条扩展到 2500+ 条
- 🔴 人工质量评估：抽样 100 条人工检查
- 🟠 大规模训练：使用完整数据重新训练
- 🟠 评估体系：建立 stage/reward 评估指标
快速阅读指南
| 想了解... | 请阅读... |
|---|---|
| 项目整体架构 | docs/PROJECT_OVERVIEW.md |
| 当前完成了什么 | docs/CURRENT_PROGRESS.md |
| 下一步做什么 | docs/NEXT_STEPS.md |
| 每个脚本的详细说明 | docs/CODE_GUIDE.md ⭐ 新增 |
| 项目当前状态快照 | docs/PROJECT_STATUS.md ⭐ 新增 |
| 开发历程和决策 | docs/DEVELOPMENT_LOG.md ⭐ 新增 |
| 数据源位置和说明 | dataset_source.md |
| GPT 标注细节 | README_improved_api.md |
| 批量推理用法 | caption/README_batch.md |
| HuggingFace 上传 | data_sta/UPLOAD_GUIDE.md |
关键文件内容速览
data/system_prompt.txt - 推理时使用的 prompt
You are a robot manipulation evaluator...
Output format: <|stage|>{stage}<|reward|>{float}...
标注输出格式 (output/labels_*.jsonl)
{"video_id": "xxx", "t": 0, "stage": 0, "stage_name": "reach", "reward": 0.5, ...}
SFT 训练格式 (data/sft_*.json)
{"conversation": [{"from": "human", "value": "..."}, {"from": "assistant", "value": "..."}]}
常见问题
Q: 如何只处理特定范围的视频？
A: 修改 api_batch_improved.py 中的 START_INDEX 和 MAX_VIDEOS
Q: 标注结果保存在哪里？
A: ./output/ 目录下的 .jsonl 文件
Q: 如何切换标注模型？
A: 修改 MODEL_NAME 变量（如 gpt-4o, gpt-4o-mini）
Q: 训练好的模型在哪里？
A: ./weights_reward_sft*/ 或 ./weights_reward_sft_special_token*/ 目录
Q: 如何快速了解每个脚本的功能？
A: 查看 docs/CODE_GUIDE.md，包含所有脚本的详细说明
Q: 项目当前进展如何？
A: 查看 docs/PROJECT_STATUS.md，提供项目状态快照
🆕 新增文档（2026-01-20）
为了帮助 AI Agent 快速理解项目，新增了以下文档：
| 文档 | 用途 | 推荐阅读顺序 |
|---|---|---|
PROJECT_STATUS.md |
项目当前状态快照 | 1️⃣ 首先阅读 |
CODE_GUIDE.md |
所有脚本的详细说明 | 2️⃣ 深入了解 |
DEVELOPMENT_LOG.md |
开发历程和决策记录 | 3️⃣ 理解背景 |
建议阅读流程：
1. QUICK_START_FOR_AGENT.md (本文档) → 快速概览
2. PROJECT_STATUS.md → 了解当前状态和待办事项
3. CODE_GUIDE.md → 深入了解每个脚本功能
4. DEVELOPMENT_LOG.md → 理解重要决策和演进过程
5. 其他具体文档 → 根据需要查阅