model/README.md

# Qwen3-VL 视频编辑定位规划器流水线（vLLM + 多帧采样 + 坐标解析 + 视频合成）

本项目提供：
1. 使用 vLLM 部署 Qwen3-VL-7B/32B（OpenAI 兼容 REST）。
2. 对视频执行**两种**帧采样：
   - `uniform_5`：均匀采样 5 帧（默认）。
   - `fps_1`：按 1 FPS 采样多帧。
3. 构造**系统/指令**消息，将多帧与编辑指令一并送入 Qwen3-VL。
4. **解析**模型固定格式的 Step5 单行输出，提取增强指令与逐帧 bbox。
5. 合成两个视频：
   - `inspection_videos/`：在**原视频**上，仅在**采样帧**处覆盖显著 bbox（彩色粗框）。
   - `mask_videos/`：生成**黑底视频**，在**采样帧**处用**白框+白填充**作为 mask 区域，其它帧保持黑底。
6. 批处理 CSV（列名自动适配；参见 `data/sample.csv` 示例）。

---

## 一、vLLM 启动（两种模型分别起一个服务）

```bash
# 7B 服务（端口 8007）
python -m vllm.entrypoints.openai.api_server   --model Qwen/Qwen2.5-VL-7B-Instruct   --dtype bfloat16   --max-model-len 8192   --port 8007

# 32B 服务（端口 8032）
python -m vllm.entrypoints.openai.api_server   --model Qwen/Qwen2.5-VL-32B-Instruct   --dtype bfloat16   --max-model-len 8192   --port 8032
```

> 如需 Qwen3-VL，请将 `--model` 改为对应权重名称；确保该权重支持多图输入。

服务启动后将提供 OpenAI 兼容的 `/v1/chat/completions` 接口。

---

## 二、安装依赖

```bash
pip install -r requirements.txt
```

---

## 三、CSV 格式（自动识别列名）
- video_path, edit_instruction（必需）
- sampling_mode（默认 uniform_5）, fps（用于 fps_1）, n_frames（用于 uniform_5）
- uid（可选，用于命名）

---

## 四、运行示例
```bash
python run.py --csv /path/to/your.csv --outdir /path/to/output_root   --api-base http://127.0.0.1:8007/v1   --results-csv /path/to/output_root/results.csv   --resume
```

---

## 输出结构
```
{outdir}/
  inspection_videos/   # 原视频 + 彩色框 (采样帧处)
  mask_videos/         # 黑底 + 白色mask (采样帧处)
  parsed_json/         # 解析结果与映射
  logs/                # checkpoint
  results.csv          # 结果汇总（每条一行，追加写）
```