Data Annotation

Step 2: 读取需求文档

读取并理解需求文档，提取关键信息。

docx 文件读取：

pip install python-docx
python3 -c "
from docx import Document
doc = Document('<需求文档路径>')
for p in doc.paragraphs: print(p.text)
for table in doc.tables:
    for row in table.rows:
        print(' | '.join(cell.text for cell in row.cells))
"
# 备选方案（python-docx 失败时）：
pandoc <需求文档路径> -t plain  # 需 apt install -y pandoc

提取并确认：

• 标注要求 — 需要标注哪些内容（类别、属性、字段）
• 输出格式 — JSONL schema 定义
• 标注规范 — 分类体系、评分标准、特殊规则
• 标签列表 — 需求文档附录中的标签表

向用户复述需求，特别是字段、输出结构、标签列表，确认无误后继续。

Step 3: 扫描数据 + 制定标注计划

扫描数据目录，统计文件数量和类型：

find <数据目录> -type f \( -name "*.jpg" -o -name "*.jpeg" -o -name "*.png" \
  -o -name "*.mp4" -o -name "*.avi" -o -name "*.txt" \) | wc -l

制定标注计划，保存为 <数据目录>/results/plan.json：

{
  "task_name": "任务描述",
  "created_at": "2026-03-19T14:00:00Z",
  "total_items": 10,
  "processed": 0,
  "failed": 0,
  "items": [
    { "id": 1, "source": "video1.mp4", "type": "video", "status": "pending", "result_file": null },
    { "id": 2, "source": "image_001.jpg", "type": "image", "status": "pending", "result_file": null }
  ]
}

对于视频数据，此阶段也执行抽帧（抽帧不计入逐条标注耗时）。

视频抽帧要求：

• 每秒至少 2 帧（ffmpeg -vf fps=2）
• 短视频（<10s）至少 15 帧
• 中视频（10-30s）至少 20 帧
• 长视频（>30s）至少 30 帧
• 抽帧保存到 <数据目录>/results/frames/<文件名不含扩展名>/

制定计划后向主 Agent 汇报：

• 数据总量
• 数据类型分布
• 计划处理顺序
• 预估耗时

Step 4: 逐条处理标注（核心步骤）

每次只处理 1 条数据！ 处理流程：

读取 plan.json → 取下一条 status=pending → 调用模型标注 → 保存结果 → 更新 plan.json → 汇报进度 → 取下一条

模型选择策略

查看 TOOLS.md 获取已配置的模型 API 信息。

模型 API 调用示例（VL 模型）

# 使用阿里百炼 qwen3.5-plus 分析图片
curl -s https://coding.dashscope.aliyuncs.com/v1/chat/completions \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.5-plus",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,<BASE64>"}},
        {"type": "text", "text": "请按照标注要求分析这张图片..."}
      ]
    }]
  }'

每条数据处理后立即：

1. 保存到 dataset.jsonl（追加写入，不要每次重写全量）
2. 更新 plan.json（标记 status=done，记录耗时）
3. 检查剩余时间：如果已用超过 60% 的总时间，暂停并汇报进度
4. 汇报当前进度：已处理 X/Y（Z%），本条耗时 N 秒

进度汇报格式

每处理完几条数据后，输出进度：

📊 进度：已处理 3/10（30%）
- ✅ video1.mp4 — 完成（耗时 12s）
- ✅ video2.mp4 — 完成（耗时 15s）
- ✅ image_001.jpg — 完成（耗时 3s）
- ⏳ image_002.jpg — 处理中...

Step 5: 保存标注结果

标注结果保存到 <数据目录>/results/ 目录：

<数据目录>/
├── data/                  # 原始数据
├── results/
│   ├── plan.json          # 标注计划（进度追踪）
│   ├── dataset.jsonl      # 标注结果（逐条追加）
│   ├── summary.json       # 统计摘要（全部完成后生成）
│   ├── viewer.html        # Web 查看编辑页面
│   ├── frames/            # 视频抽帧图片
│   │   ├── video1/
│   │   └── video2/
│   └── videos/            # 视频副本（供 Web 引用）
└── ...

输出格式要求：

• 每条标注一个 JSON 对象，一行一条（JSONL）
• 必须包含 source_file 和 annotation_time
• 字段结构严格遵循需求文档 schema

Step 6: 生成 Web 查看/编辑页面

参考 templates/annotation-viewer.html 模板，根据实际数据生成定制页面。

页面关键要求（实战经验）：

1. 三栏布局：左侧文件列表 | 中间数据展示 | 右侧标注结果
2. apiBase 必须用 nginx 反代路径（/annotation-api/），不要硬编码 127.0.0.1:8888
3. 所有文本字段 contentEditable，点击即可编辑
4. 标签支持增删（添加按钮 + × 删除按钮）
5. 保存按钮在右上角，调用 POST /annotation-api/ 保存
6. 未保存修改时离开页面要有警告（beforeunload 事件）
7. 标注区块可折叠/展开
8. 保存成功要有 Toast 提示

视频文件处理：Web 页面引用视频时使用相对路径（../video.mp4），通过 nginx 静态服务直接访问，不要走 API。

Step 7: Nginx 部署

⚠️ 实战经验教训

1. 不要创建独立 server 块监听 80 — 会和已有站点冲突。改为在已有站点配置中添加 location 块
2. 使用 ^~ 前缀匹配 — 避免 nginx 正则 location（如静态文件缓存）优先匹配导致 404
3. 不要在静态缓存规则中包含 mp4 — 大文件不适合强缓存
4. nginx reload 可能不够，必要时 restart
5. /root 目录权限必须 755 — 否则 nginx worker 无法访问（root 下默认 700）

正确配置方式

在已有的 nginx 站点配置中添加（如 /etc/nginx/sites-enabled/default）：

# 标注数据查看（^~ 优先级高于正则，确保 mp4/jpg 不被其他规则劫持）
location ^~ /annotation/ {
    alias /root/annotation-data/;
    autoindex on;
    index viewer.html index.html;
    charset utf-8;
    add_header Access-Control-Allow-Origin *;
    add_header Access-Control-Allow-Methods "GET, POST, OPTIONS";
    add_header Access-Control-Allow-Headers "Content-Type";
}

# 标注 API 反代
location ^~ /annotation-api/ {
    proxy_pass http://127.0.0.1:8888/;
}

不要删除已有的其他 location 块，只追加。

数据目录软链接

mkdir -p /root/annotation-data/
ln -sf <实际数据目录> /root/annotation-data/<项目名>
chmod 755 /root  # 关键！否则 nginx 无法访问

启动 API 服务

fuser -k 8888/tcp 2>/dev/null
nohup python3 <skill路径>/scripts/annotation-api.py --port 8888 --data-dir <数据目录> > <数据目录>/results/api.log 2>&1 &

验证

# 必须完全 restart 而不是 reload
systemctl restart nginx
# 验证 HTML、图片、视频、API 都能正常访问
curl -s -o /dev/null -w "%{http_code}" http://localhost/annotation/<项目名>/results/viewer.html  # 期望 200
curl -s -o /dev/null -w "%{http_code}" http://localhost/annotation/<项目名>/<视频文件>.mp4      # 期望 200
curl -s "http://localhost/annotation-api/" | python3 -c "import sys,json;print(len(json.load(sys.stdin).get('files',[])))"  # 文件数>0

完成后汇报

每次完成或暂停时，向主 Agent/用户汇报：

1. 进度统计 — 已处理 X/Y（Z%），失败 N 条
2. 本批次耗时
3. 结果文件位置
4. Web 访问地址
5. 失败数据原因（如有）
6. 下次续做位置 — 如果未全部完成，说明 plan.json 中从哪个 ID 继续
7. 改进建议

引用文件

• Web 页面模板：templates/annotation-viewer.html
• API 服务脚本：scripts/annotation-api.py
• 标注格式参考：references/output-formats.md