英语 | 中文
DataLabel
Serverless Human-in-the-Loop Annotation Framework with LLM Pre-Labeling and Inter-Annotator Agreement Analysis
零服务器人机协同标注框架 — LLM 预标注 · 多标注者一致性分析 · 离线 HTML 界面
Zero-dependency annotation tool with LLM-assisted pre-labeling, multi-annotator agreement metrics, and offline HTML interface
 ](https://pypi.org/project/knowlyr-datalabel/)  
     
摘要 · 问题陈述 · 形式框架 · 建筑 · 关键创新 · 快速开始 · 注解类型 · LLM辅助注释 · MCP服务器 · 生态系统 · 参考文献
______________________________________________________________________
摘要
高质量标注数据是监督学习和 RLHF 的基础，但现有标注工具面临两个矛盾：重量级平台（Label Studio / Prodigy）部署运维成本高，轻量工具则缺少质量保证机制。DataLabel 提出零服务器标注范式 (serverless annotation paradigm)——生成独立 HTML 文件，浏览器直接打开即可标注，无需服务器、无需网络。
系统实现「Schema 定义 → LLM 预标注 → 人工校准 → 质量分析 → 一致性评估 → 冲突裁决」的完整标注管线。通过 LLM 预标注 (pre-labeling) 加速标注启动，通过标注者间一致性分析 (Inter-Annotator Agreement, IAA) 量化标注质量，通过多策略合并与冲突裁决 (adjudication) 产出高质量最终标签。
恢复 实现了一个无服务器注释框架，该框架生成用于离线标签的自包含HTML文件。该系统提供LLM辅助的预标记（Kimi/OpenAI/Anthropic）、5种注释类型（评分、单选/多选、文本、排名）、3种策略的多注释器结果合并以及严格的IAA指标（Cohen的$\\kappa$、Fleiss的$\\kappa$、Krippendorff的$\\alpha$）。公开了12个MCP工具、6个资源和3个用于AI IDE集成的提示模板。
______________________________________________________________________
问题陈述
数据标注领域面临三个结构性问题：
| 根本性问题 | 形式化定义 | 现有工具局限 | DataLabel 的方法 |
|---|---|---|---|
| 部署壁垒 | |||
| Deployment Barrier | 标注平台需要服务器、数据库、网络环境，部署成本 $\\gg$ 标注本身 | Label Studio 需 Docker + PostgreSQL；Prodigy 需 Python 运行时 | 零服务器：生成独立 HTML，浏览器直接打开，离线可用 |
| 冷启动延迟 | |||
| Cold Start Latency | 标注员从零开始标注，前期效率低，标注指南编写耗时 | 无预标注能力，标注指南靠人工编写 | LLM 预标注 + 自动指南生成，人工从"校准"而非"从零标注"开始 |
| 质量黑箱 | |||
| Quality Opacity | 标注质量缺少量化指标，分歧处理凭经验 $\\implies$ 一致性 $\\kappa$ 未知 | 基础工具不提供 IAA，或仅支持两人比较 | 多指标一致性分析（Cohen's / Fleiss' $\\kappa$ / Krippendorff's $\\alpha$）+ LLM 分歧分析 + 可视化仪表盘 |
DataLabel 不是另一个标注平台。它是标注数据的生产工具——从 Schema 定义到最终标签的完整管线，零运维成本，质量可量化。
______________________________________________________________________
形式框架
注释模型
标注任务形式化为四元组 $\\mathcal{L} = \\langle X, Y, A, \\phi \\rangle$：
| 符号 | 定义 | 说明 |
|---|---|---|
| $X = {x_1, \\ldots, x_n}$ | 待标注样本集 | 由 Schema 定义字段结构 |
| $Y$ | 标签空间 | $Y \\in {\\mathbb{R}, C, 2^C, \\Sigma^\*, S_k}$，对应 5 种标注类型 |
| $A = {a_1, \\ldots, a_m}$ | 标注者集合 | 人工标注者 + LLM 预标注者 |
| $\\phi: X \\times A \\to Y$ | 标注函数 | $\\phi(x, a)$ 为标注者 $a$ 对样本 $x$ 的标签 |
五种标签空间对应五种标注类型：评分 ($\\mathbb{R}$)、单选 ($C$)、多选 ($2^C$)、文本 ($\\Sigma^\*$)、排序 ($S_k$，$k$ 元素的全排列)。
互注释者协议（IAA）
科恩卡帕（两标注者）：
$$\\kappa=\\frac{p_o-pue}{1-pue}$$
其中 $p_o$ 为观测一致率，$p_e$ 为随机一致率。$\\kappa > 0.8$ 表示高度一致，$\\kappa \ P["LLM Pre-Label (Optional)"] P --> G["HTML Generator Self-Contained"] G --> B["Browser Offline Annotation"] B --> R["Results JSON/JSONL/CSV"] R --> Q["Quality LLM Analysis"] R --> M["Merge 3 Strategies"] M --> IAA["IAA Metrics κ / α"] M --> D["Dashboard HTML Report"]
style G fill:#0969da,color:#fff,stroke:#0969da style M fill:#8b5cf6,color:#fff,stroke:#8b5cf6 style IAA fill:#2da44e,color:#fff,stroke:#2da44e style D fill:#e5534b,color:#fff,stroke:#e5534b style S fill:#1a1a2e,color:#e0e0e0,stroke:#444 style P fill:#1a1a2e,color:#e0e0e0,stroke:#444 style B fill:#1a1a2e,color:#e0e0e0,stroke:#444 style R fill:#1a1a2e,color:#e0e0e0,stroke:#444 style Q fill:#1a1a2e,color:#e0e0e0,stroke:#444
### 注释管道
| 步骤 | 命令 | 产出 |
|:---|:---|:---|
| 1. 生成指南 | `knowlyr-datalabel gen-guidelines schema.json` | `guide.md` (可选) |
| 2. LLM 预标注 | `knowlyr-datalabel prelabel schema.json tasks.json` | `pre.json` (可选) |
| 3. 生成界面 | `knowlyr-datalabel create schema.json tasks.json` | `annotator.html` |
| 4. 分发标注 | 发送 HTML 给标注员 | 浏览器中完成标注 |
| 5. 收集结果 | 标注员导出 JSON/JSONL/CSV | `results_*.json` |
| 6. 质量分析 | `knowlyr-datalabel quality schema.json results_*.json` | `report.json` (可选) |
| 7. 合并分析 | `knowlyr-datalabel merge results_*.json` | `merged.json` +IAA|
| 8. 进度仪表盘 | `knowlyr-datalabel dashboard results_*.json` | `dashboard.html` |
______________________________________________________________________
## 关键创新
### 1.无服务器注释架构
生成的 HTML 包含所有样式、逻辑和数据——无需服务器、无需网络、无需安装。标注数据保存在 `localStorage`，支持断点续标。
- **零依赖部署**：发送 HTML 文件即完成分发
- **离线可用**：飞机模式、内网环境均可使用
- **暗黑模式**：一键切换，跟随系统偏好
- **快捷键**：`←` `→` 导航、数字键评分/选择、`Ctrl+Z` 撤销
- **大数据集**：任务侧边栏 + 分页 (25/50/100/200) + 搜索过滤，支持 1000+ 任务
### 2.LLM辅助预标签和质量分析
LLM 介入标注管线的三个环节，从"人工从零标注"转变为"人工校准 LLM 预标"：
| 环节 | 功能 | 效果 |
|:---|:---|:---|
| **预标注** | LLM 批量生成初始标签 | 标注员从"校准"开始，效率提升 |
| **质量分析** | 检测可疑标注、分析分歧原因 | 量化质量问题，指导修订 |
| **指南生成** | 根据 Schema 和样例生成标注指南 | 消除指南编写的冷启动 |
支持三个 LLM Provider：
| Provider | 环境变量 | 默认模型 |
|:---|:---|:---|
|登月计划（基米）| `MOONSHOT_API_KEY` |moonshot-v1-8k|
|OpenAI| `OPENAI_API_KEY` |gpt-4o-mini|
|人类学| `ANTHROPIC_API_KEY` |claude-sonnet-4-20250514|
### 3.多指标注释者间协议
三种 IAA 指标覆盖不同场景：
| 指标 | 适用场景 | 范围 |
|:---|:---|:---|
| Cohen's $\\kappa$ | 两标注者 | $\[-1, 1\]$ |
| Fleiss' $\\kappa$ | 多标注者、名义变量 | $\[-1, 1\]$ |
| Krippendorff's $\\alpha$ | 多标注者、支持缺失数据 | $\[-1, 1\]$ |
输出两两一致矩阵 + 总体一致性 + 分歧任务列表。一致率 \
可选依赖
pip install knowlyr-datalabel[mcp] # MCP 服务器 pip install knowlyr-datalabel[llm] # LLM 分析 (Kimi/OpenAI) pip install knowlyr-datalabel[llm-all] # LLM 分析 (含 Anthropic) pip install knowlyr-datalabel[all] # 全部功能
1. 创建标注界面
knowlyr-datalabel create schema.json tasks.json -o annotator.html
2. LLM 预标注（可选）
knowlyr-datalabel prelabel schema.json tasks.json -o pre.json -p moonshot
3. 浏览器打开 annotator.html，完成标注，导出结果
4. 合并多标注员结果 + IAA 分析
knowlyr-datalabel merge ann1.json ann2.json ann3.json -o merged.json
5. 生成进度仪表盘
knowlyr-datalabel dashboard ann1.json ann2.json -o dashboard.html
Schema 格式示例
{ "project_name": "我的标注项目", "fields": [ {"name": "instruction", "display_name": "指令", "type": "text"}, {"name": "response", "display_name": "回复", "type": "text"} ], "scoring_rubric": [ {"score": 1, "label": "优秀", "description": "回答完整准确"}, {"score": 0.5, "label": "一般", "description": "回答基本正确"}, {"score": 0, "label": "差", "description": "回答错误或离题"} ] }
Python SDK
from datalabel import AnnotatorGenerator, ResultMerger
生成标注界面
gen = AnnotatorGenerator() gen.generate(schema=schema, tasks=tasks, output_path="annotator.html")
合并标注结果
merger = ResultMerger() result = merger.merge(["ann1.json", "ann2.json"], output_path="merged.json", strategy="majority") print(f"一致率: {result.agreement_rate:.1%}")
计算 IAA
metrics = merger.calculate_iaa(["ann1.json", "ann2.json", "ann3.json"]) print(f"Fleiss' κ: {metrics['fleiss_kappa']:.3f}") print(f"Krippendorff's α: {metrics['krippendorff_alpha']:.3f}")
______________________________________________________________________
## 注解类型
5 种标注类型配置详情
### 1. Scoring (默认)
{ "scoring_rubric": [ {"score": 1, "description": "优秀"}, {"score": 0.5, "description": "一般"}, {"score": 0, "description": "差"} ] }
### 2.单选
{ "annotation_config": { "type": "single_choice", "options": [ {"value": "positive", "label": "正面"}, {"value": "negative", "label": "负面"}, {"value": "neutral", "label": "中性"} ] } }
### 3.多选
{ "annotation_config": { "type": "multi_choice", "options": [ {"value": "informative", "label": "信息丰富"}, {"value": "accurate", "label": "准确"}, {"value": "fluent", "label": "流畅"} ] } }
### 4.文本
{ "annotation_config": { "type": "text", "placeholder": "请输入翻译...", "max_length": 500 } }
### 5.排名
{ "annotation_config": { "type": "ranking", "options": [ {"value": "a", "label": "结果A"}, {"value": "b", "label": "结果B"}, {"value": "c", "label": "结果C"} ] } }
______________________________________________________________________
## LLM辅助注释
### 预贴标签
Kimi 预标注
knowlyr-datalabel prelabel schema.json tasks.json -o pre.json -p moonshot
OpenAI 预标注
knowlyr-datalabel prelabel schema.json tasks.json -o pre.json -p openai
指定模型和批大小
knowlyr-datalabel prelabel schema.json tasks.json -o pre.json -p moonshot -m kimi-k2 --batch-size 10
### 质量分析
单标注员质量检查
knowlyr-datalabel quality schema.json results.json -o report.json -p moonshot
多标注员分歧分析
knowlyr-datalabel quality schema.json ann1.json ann2.json -o report.json
### 指南生成
knowlyr-datalabel gen-guidelines schema.json -t tasks.json -o guidelines.md -l zh
______________________________________________________________________
## MCP服务器
{ "mcpServers": { "knowlyr-datalabel": { "command": "uv", "args": ["--directory", "/path/to/data-label", "run", "python", "-m", "datalabel.mcp_server"] } } }
### 工具（12）
|工具|说明|
|:---|:---|
| `generate_annotator` | 从 DataRecipe 分析结果生成标注界面 |
| `create_annotator` | 从 Schema 和任务创建标注界面 |
| `merge_annotations` | 合并多个标注结果 |
| `calculate_iaa` | 计算标注员间一致性 |
| `validate_schema` | 验证 Schema 和任务数据格式 |
| `export_results` | 导出为 JSON/JSONL/CSV |
| `import_tasks` | 导入任务数据 |
| `generate_dashboard` | 生成进度仪表盘 HTML |
| `llm_prelabel` | LLM 自动预标注 |
| `llm_quality_analysis` | LLM 标注质量分析 |
| `llm_gen_guidelines` | LLM 标注指南生成 |
| `adjudicate` | 冲突裁决 |
### 资源（6）·提示（3）
|资源|提示|
|:---|:---|
| `datalabel://schemas/{type}` — 5 种 Schema 模板 | `create-annotation-schema` — 引导生成 Schema |
| `datalabel://reference/annotation-types` — 标注类型说明 | `review-annotations` — 分析标注质量 |
| | `annotation-workflow` — 完整工作流引导 |
______________________________________________________________________
## CLI参考
完整命令列表
| 命令 | 功能 |
|:---|:---|
| `knowlyr-datalabel create -o ` | 创建标注界面 |
| `knowlyr-datalabel create ... --page-size 100` | 自定义分页 |
| `knowlyr-datalabel create ... -g guidelines.md` | 附带标注指南 |
| `knowlyr-datalabel generate ` | 从 DataRecipe 结果生成 |
| `knowlyr-datalabel merge -o ` | 合并标注结果 |
| `knowlyr-datalabel merge ... -s majority\|average\|strict` | 指定合并策略 |
| `knowlyr-datalabel iaa ` | 计算标注一致性 |
| `knowlyr-datalabel dashboard -o ` | 生成仪表盘 |
| `knowlyr-datalabel validate [-t tasks]` | 验证格式 |
| `knowlyr-datalabel export -o -f json\|jsonl\|csv` | 导出转换 |
| `knowlyr-datalabel import-tasks -o ` | 导入任务 |
| `knowlyr-datalabel prelabel -o ` | LLM 预标注 |
| `knowlyr-datalabel quality ` | LLM 质量分析 |
| `knowlyr-datalabel gen-guidelines -o ` | LLM 指南生成 |
______________________________________________________________________
## 码头工人
docker build -t knowlyr-datalabel .
创建标注界面
docker run --rm -v $(pwd):/data knowlyr-datalabel \ create schema.json tasks.json -o annotator.html
合并标注结果
docker run --rm -v $(pwd):/data knowlyr-datalabel \ merge ann1.json ann2.json -o merged.json
______________________________________________________________________
## 生态系统
Architecture Diagram
graph LR Radar["Radar Discovery"] --> Recipe["Recipe Analysis"] Recipe --> Synth["Synth Generation"] Recipe --> Label["Label Annotation"] Synth --> Check["Check Quality"] Label --> Check Check --> Audit["Audit Model Audit"] Crew["Crew Deliberation Engine"] Agent["Agent RL Framework"] ID["ID Identity Runtime"] Crew -.->|能力定义| ID ID -.->|身份 + 记忆| Crew Crew -.->|轨迹 + 奖励| Agent Agent -.->|优化策略| Crew
style Label fill:#0969da,color:#fff,stroke:#0969da style Crew fill:#2da44e,color:#fff,stroke:#2da44e style Agent fill:#8b5cf6,color:#fff,stroke:#8b5cf6 style ID fill:#e5534b,color:#fff,stroke:#e5534b style Radar fill:#1a1a2e,color:#e0e0e0,stroke:#444 style Recipe fill:#1a1a2e,color:#e0e0e0,stroke:#444 style Synth fill:#1a1a2e,color:#e0e0e0,stroke:#444 style Check fill:#1a1a2e,color:#e0e0e0,stroke:#444 style Audit fill:#1a1a2e,color:#e0e0e0,stroke:#444
|图层|项目|描述|回购|
|:---|:---|:---|:---|
|发现| **AI数据集雷达** | 数据集竞争情报、趋势分析 | |
|分析| **DataRecipe** | 逆向分析、Schema 提取、成本估算 | |
|生产| **DataSynth** | LLM 批量合成 | |
|生产| **恢复** | 零服务器标注 · LLM 预标注 · IAA 分析 | You are here |
|质量| **数据检查** | 规则验证、重复检测、分布分析 | |
|审计| **模型审计** | 蒸馏检测、模型指纹 | |
|身份| **knowlyr id** | 身份系统 + AI 员工运行时 | |
|审议情况| **船员** | 对抗式多智能体协商 · 持久记忆进化 · MCP 原生 | |
|代理商培训| **knowlyr健身房** | Gymnasium 风格 RL 框架 · 过程奖励模型 · SFT/DPO/GRPO | |
______________________________________________________________________
## 发展
git clone https://github.com/liuxiaotong/data-label.git cd data-label pip install -e ".[all,dev]" pytest # 296 test cases
**持续集成**: GitHub Actions，Python 3.10+，Codecov 覆盖率。Tag push 自动发布 PyPI + GitHub Release。
______________________________________________________________________
## 参考文献
- **互注释者协议** --Artstein，R.和Poesio，M.，2008年。 *计算语言学程序员间协议。* Computational Linguistics — IAA 指标的系统性综述
- **科恩卡帕** --科恩，J.，1960年。 *名义规模的一致系数。* Educational and Psychological Measurement — 两标注者一致性度量
- **弗莱斯·卡帕** --Fleiss，J.L.，1971年。 *衡量许多评级机构之间的名义规模一致性。* Psychological Bulletin — 多标注者一致性推广
- **克里彭多夫阿尔法** --克里彭多夫，K.，2011。 *计算克里彭多夫的阿尔法可靠性。* — 支持缺失数据的通用一致性度量
- **主动学习** --塞特尔斯，B.，2009年。 *主动学习文献调查。* CS Technical Report, University of Wisconsin-Madison — 主动学习选择策略
- **RLHF** --克里斯蒂安诺，P.等人，2017。 *人类偏好的深度RL。* [arXiv:1706.03741](https://arxiv.org/abs/1706.03741) — 人类偏好标注驱动的强化学习
______________________________________________________________________
## 许可证
[麻省理工学院](LICENSE)
______________________________________________________________________
knowlyr — serverless annotation framework with LLM pre-labeling and inter-annotator agreement analysis