docs/README_improved_api.md

# 改进版视频标注 API 使用说明

## 主要改进

### 1. 动态任务描述（已实现 ✓）

- **自动读取 metadata JSON**：根据视频路径自动查找对应的 `metadata_*.json` 文件
- **提取任务描述**：从 JSON 中提取 `current_task` 字段
- **动态插入 prompt**：将任务描述动态插入到 GPT prompt 中

示例：
```
视频路径: PennPAL/failure/2023-10-01/Sun_Oct__1_16:56:53_2023/recordings/MP4/14436910.mp4
Metadata: PennPAL/failure/2023-10-01/Sun_Oct__1_16:56:53_2023/metadata_PennPAL+c5f808b7+2023-10-01-16h-56m-53s.json
任务: "Open or close hinged object (ex: hinged door, microwave, oven, book, dryer, toilet, box)"
```

### 2. 视频序列帧分析（已实现 ✓）

提供两种处理模式：

#### 模式 A：基础模式（USE_SLIDING_WINDOW = False）
- 一次性发送所有帧给 GPT
- 适合短视频（< 20 帧）
- 成本较低，处理速度快

#### 模式 B：滑动窗口模式（USE_SLIDING_WINDOW = True）⭐ **推荐**
- **连续帧分析**：每次发送 WINDOW_SIZE 个连续帧
- **捕捉动态关系**：GPT 可以看到连续的动作序列，判断：
  - 运动是否平滑还是抖动
  - 物体是否稳定还是摇晃
  - 进度是前进、停滞还是倒退
- **上下文传递**：前一个窗口的分析结果作为上下文传递给下一个窗口
- **参数配置**：
  - `WINDOW_SIZE = 5`：每个窗口包含 5 个连续帧
  - `WINDOW_STRIDE = 3`：窗口每次滑动 3 帧（允许重叠）

**滑动窗口示例**：
```
视频帧: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]

窗口 1: [0, 1, 2, 3, 4]    → 分析 + 上下文A
窗口 2: [3, 4, 5, 6, 7]    → 分析 + 上下文B（基于窗口1）
窗口 3: [6, 7, 8, 9, 10]   → 分析 + 上下文C（基于窗口2）
窗口 4: [9, 10, 11, 12]    → 分析 + 上下文D（基于窗口3）
```

### 3. 对齐仿真奖励指标（已实现 ✓）

#### 新增字段（与仿真数据对齐）

```json
{
  "stage": 0,                    // 阶段索引 (0-5)
  "stage_name": "reach",         // 阶段名称

  // 奖励组件（与仿真对齐）
  "reachout": 0.8,              // 接近物体的进度 (0.0-1.0)
  "grasp": 0.0,                 // 抓取质量 (0.0-1.0)
  "collision": 0.0,             // 碰撞惩罚 (0.0-1.0)
  "fall": 0.0,                  // 掉落惩罚 (0.0-1.0)
  "smooth": 0.9,                // 运动平滑度 (0.0-1.0)

  // 综合指标
  "reward": 0.85,               // 总奖励
  "delta": 0.05,                // 奖励变化
  "success_prob": 0.7,          // 成功概率
  "failure": 0,                 // 是否失败 (0/1)

  "explanation": "..."          // 解释
}
```

#### 阶段定义

```
0: reach    - 伸手接近物体
1: grasp    - 抓取物体
2: lift     - 抬起物体
3: move     - 移动物体
4: place    - 放置物体
5: retract  - 收回手臂
```

#### 奖励组件说明

1. **reachout**（接近）
   - 0.0: 机器人远离目标
   - 0.5: 正在接近
   - 1.0: 已接触或达到目标位置

2. **grasp**（抓取）
   - 0.0: 无接触
   - 0.5: 接触但不稳定
   - 1.0: 稳固抓取

3. **collision**（碰撞惩罚）
   - 0.0: 无碰撞
   - 0.5: 轻微碰撞
   - 1.0: 严重碰撞

4. **fall**（掉落惩罚）
   - 0.0: 物体稳定
   - 1.0: 物体掉落/滚落

5. **smooth**（平滑度）
   - 0.0-0.3: 抖动、突然运动
   - 0.8-1.0: 平滑、稳定运动

## 配置参数

```python
# 基础配置
ROOT = Path("/playpen-ssd/dataset/droid_raw/1.0.1/AUTOLab/failure")
TARGET_NAME = "22008760.mp4"
OUTPUT_FILE = "./output/labels_batch_improved.jsonl"
FPS_SAMPLE = 2
MODEL_NAME = "gpt-4o"  # 推荐使用 gpt-4o
MAX_VIDEOS = 10
START_INDEX = 0

# 滑动窗口配置
USE_SLIDING_WINDOW = True  # 推荐设为 True
WINDOW_SIZE = 5            # 每个窗口的帧数
WINDOW_STRIDE = 3          # 窗口滑动步长
```

## 输出格式

输出 JSONL 文件，每行一个时间步的标注：

```json
{
  "video_path": "/playpen-ssd/dataset/.../22008760.mp4",
  "video_id": "22008760",
  "task": "Move object into or out of container",
  "t": 0,
  "frame_index": 0,
  "total_frames": 229,
  "native_fps": 60.0,
  "window_idx": 0,
  "stage": 0,
  "stage_name": "reach",
  "reachout": 0.3,
  "grasp": 0.0,
  "collision": 0.0,
  "fall": 0.0,
  "smooth": 0.8,
  "reward": 0.55,
  "delta": 0.0,
  "success_prob": 0.5,
  "failure": 0,
  "explanation": "Robot arm is reaching toward the container..."
}
```

## 使用方法

### 1. 安装依赖

```bash
pip install openai decord pillow python-dotenv tqdm
```

### 2. 设置 API Key

创建 `.env` 文件：
```
OPENAI_API_KEY=your_api_key_here
```

### 3. 运行脚本

```bash
cd /home/jqliu/projects/RewardModel
python api_batch_improved.py
```

### 4. 查看结果

```bash
# 查看输出文件
cat output/labels_batch_improved.jsonl | jq .

# 统计不同阶段的分布
cat output/labels_batch_improved.jsonl | jq -r '.stage_name' | sort | uniq -c

# 查看失败案例
cat output/labels_batch_improved.jsonl | jq 'select(.failure == 1)'
```

## 成本估算

使用 GPT-4o 的成本（2024年价格）：
- 输入: $2.50 / 1M tokens
- 输出: $10.00 / 1M tokens

示例视频（2秒，60fps，采样2fps）：
- 帧数: ~4 帧
- 每帧图片 token: ~1000 tokens
- 每视频成本: ~$0.01-0.02

## 对比原版本的改进

| 特性 | 原版本 | 改进版本 |
|-----|--------|---------|
| 任务描述 | 固定 | ✓ 从 metadata 动态提取 |
| 帧分析方式 | 单次所有帧 | ✓ 滑动窗口 + 上下文传递 |
| 动态关系分析 | 有限 | ✓ 连续帧序列，捕捉运动平滑度 |
| 奖励指标 | 基础 | ✓ 对齐仿真（reachout, grasp, collision, fall, smooth）|
| 阶段定义 | 字符串 | ✓ 数值索引 + 名称（与仿真对齐）|
| 上下文传递 | 无 | ✓ 前一窗口结果作为上下文 |

## 建议

1. **首次测试**：先设置 `MAX_VIDEOS = 1` 测试单个视频
2. **模型选择**：推荐使用 `gpt-4o`，性能最佳且成本较低
3. **窗口大小**：
   - 短视频（<3秒）：WINDOW_SIZE = 3-5
   - 长视频（>5秒）：WINDOW_SIZE = 5-7
4. **质量检查**：定期检查输出，确保标注质量
5. **批处理**：可以使用多进程并行处理多个视频

## 故障排除

### 问题1：找不到 metadata 文件
- 检查视频路径结构是否正确
- 确认 metadata JSON 文件存在于轨迹根目录

### 问题2：API 超时
- 减小 WINDOW_SIZE
- 增加重试机制
- 检查网络连接

### 问题3：输出格式错误
- 检查 GPT 返回的 JSON 是否有效
- 可能需要调整 prompt 或增加输出格式验证

## 后续扩展

可以进一步添加：
1. 多视角融合（同时分析多个摄像头）
2. 失败检测器（专门识别失败模式）
3. 质量评分（评估标注的可信度）
4. 人工审核界面（可视化标注结果）