---
name: model-labeling
description: 对已有数据集调用线上模型 generate 接口批量打标，支持 canonical records、训练 jsonl、评测 CSV 和同事流转表格的统一归一化。
when_to_use: 当用户已有一份数据，或刚通过 product-data / online-mining-v2 生成数据后，希望指定线上模型 URL 批量请求模型、得到预测标签、对比真实标签或产出标注结果时使用。
aliases: batch-labeling, model-annotation, online-model-labeling, 模型打标
allowed_tools: read_file, write_file, grep_search, glob_search, ask_user_question, python_exec
---

# Model Labeling

使用这个 skill 处理“已有数据 -> 统一样本格式 -> 调线上模型接口批量打标 -> 输出预测结果”的流程。

线上模型 URL 经常变化，**不要猜 URL**。如果用户没有明确提供 `http://.../generate` 或等价接口地址，必须先询问用户。

## 能力组织

```text
skills/model-labeling/
  SKILL.md
  knowledge/
    input_formats.md
  scripts/
    batch_label_model.py
```

`batch_label_model.py` 是 portable script，只依赖 Python 标准库。它会：

- 识别 canonical records JSON/JSONL。
- 识别 product-data 导出的训练 JSONL。
- 识别 eval/planning CSV，优先使用 `newPrompt`。
- 识别同事流转 CSV，使用 `query`、`prev_session`、`context`、`function`。
- 对未知格式返回结构化错误，要求用户提供字段映射，不要擅自转换。
- 调用用户提供的模型接口，默认请求体为：

```json
{
  "inputs": "<prompt>",
  "parameters": {
    "max_new_tokens": 64
  }
}
```

## 交互规则

开始执行前必须确认：

1. **输入数据路径**：用户给出的文件路径，或上一轮产物路径。
2. **模型接口 URL**：必须是用户明确提供的 URL；没有就问。
3. **输入格式是否可识别**：canonical records、训练 jsonl、eval CSV、同事流转表格可以直接处理。
4. **未知格式的字段映射**：如果脚本提示 unknown format，需要问用户：
   - 哪列是 query？
   - 哪列是 prompt？
   - 哪列是真实标签？
   - 是否有历史上下文、context？
5. **输出路径**：默认写到当前 session 的 `output/model_predictions.jsonl`。

不要在没有 URL 的情况下开始打标。不要把临时结果写到项目根目录。所有输出优先放当前 session 的 `output/`。

## 推荐流程

### 1. 找到输入文件

如果用户说“刚才生成的数据”“这份数据”，先用会话文件面板或 `glob_search` / `read_file` 找到实际路径。常见路径：

```text
output/records.jsonl
output/training.jsonl
output/eval_planning.csv
output/records.csv
```

### 2. 确认模型 URL

如果用户没有提供 URL，直接问：

```text
请提供这次要调用的线上模型 generate 接口 URL，例如 http://.../generate。
```

如果 `ask_user_question` 可用，优先使用；不可用就普通回复提问并停止。

### 3. 先 dry run 识别格式

先执行一次 `dry_run=true`，只识别格式和样例，不请求模型：

```json
{
  "script_path": "skills/model-labeling/scripts/batch_label_model.py",
  "stdin": {
    "input_path": "output/records.jsonl",
    "model_url": "http://example/generate",
    "dry_run": true,
    "max_records": 3
  },
  "timeout_seconds": 60,
  "max_output_chars": 20000
}
```

如果返回 `ok=false` 且 `needs_mapping=true`，必须把错误和已识别字段展示给用户，让用户说明映射。

### 4. 批量请求模型

确认格式后执行：

```json
{
  "script_path": "skills/model-labeling/scripts/batch_label_model.py",
  "stdin": {
    "input_path": "output/records.jsonl",
    "model_url": "http://example/generate",
    "output_path": "output/model_predictions.jsonl",
    "parameters": {
      "max_new_tokens": 64
    },
    "timeout_seconds": 60
  },
  "timeout_seconds": 600,
  "max_output_chars": 20000
}
```

`output_path` 使用相对 `output/...`，平台会路由到当前 session output 目录。

### 5. 展示结果

执行完成后，简短展示：

- 输入格式。
- 处理条数、成功数、失败数。
- 输出路径。
- 抽 3 条预测样例。

如果存在真实标签，说明输出里包含 `gold_label`，后续可以继续做准确率或错误分析。

## 输出格式

默认输出 JSONL，一行一条紧凑 JSON：

```json
{"index":0,"request_id":"...","query":"...","gold_label":"complex=false\nAgent(tag=\"地图导航\")","prediction":"...","ok":true,"latency_ms":123}
```

如果请求失败：

```json
{"index":0,"query":"...","gold_label":"...","prediction":"","ok":false,"error":"HTTP 500 ...","latency_ms":123}
```

默认不把完整 prompt 写入结果，避免文件过大。如确实需要排查，可传 `include_prompt=true`。

## 注意事项

- URL、鉴权 header、特殊请求体字段都以用户提供为准。
- 默认接口字段是 `inputs` 和 `parameters`；如果用户说明接口不同，需要在脚本输入里传 `request_template`。
- 大批量请求前先小样本 dry run。
- 打标脚本只负责请求模型和记录预测结果，不负责修改原始数据。
- 后续准确率统计、错误聚类、补数计划可以再交给其他 skill。