data-annotation

# Data Annotation Skill — 数据标注处理工具

完整的数据标注工作流：需求确认 → 制定计划 → 逐条处理 → 结果存储 → Web 查看/编辑 → 部署访问。

## ⚠️ 核心原则：计划驱动，逐条处理，永不超时

**绝对不要一次性批量处理所有数据！** 超时（通常 10 分钟）会导致任务中断、数据丢失。

正确做法：
1. **先制定标注计划**（JSON 格式），列出所有待处理数据
2. **每次只处理 1 条数据**，处理完立即保存
3. **更新计划进度**（标记已完成/失败）
4. **汇报当前进度**（已处理 X/Y，耗时 N 秒）

如果感觉快超时了，**立即保存当前进度并汇报**，下次从计划中未完成的位置继续。

---

## 工作流程

### Step 1: 确认需求

收到标注任务后，**必须先确认**以下信息：

1. **需求文档位置** — 问用户标注需求文档在哪里（路径或 URL）
2. **待标注数据位置** — 问用户原始数据存放在哪个目录
3. **数据类型** — 图像/视频/文本/混合
4. **输出格式** — 如果需求文档中没有说明，询问期望的输出格式

如果用户已提供以上信息，跳过确认直接进入下一步。

### Step 2: 读取需求文档

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

**docx 文件读取：**
```bash
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: 扫描数据 + 制定标注计划

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

```bash
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`：

```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 → 汇报进度 → 取下一条
```

#### 模型选择策略

| 数据类型 | 处理方式 | 推荐模型 |
|---------|---------|---------|
| **图像** | VL 模型分析图片内容 | `qwen3.5-plus`、`kimi-k2.5`、`doubao-seed-2.0-pro` |
| **视频** | 抽帧后逐帧用 VL 模型 | 同上 |
| **文本** | LLM 文本分析 | 任意文本模型 |
| **音频** | whisper 转写 + LLM | `whisper` + LLM |
| **混合** | 按类型分别处理 | 组合上述方法 |

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

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

```bash
# 使用阿里百炼 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`）：

```nginx
# 标注数据查看（^~ 优先级高于正则，确保 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 块，只追加。**

#### 数据目录软链接

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

#### 启动 API 服务

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

#### 验证

```bash
# 必须完全 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`