Skip to content

ICL 标注

在 Potato 中使用上下文学习让 LLM 预标注实例，并把其中一部分抽样交回人工验证，按方案分别追踪准确率。

ICL（上下文学习）标注把标注者已经达成一致的标注喂给 LLM，再让模型标注其余数据。Potato 为每个预测记录一个置信度分数，并抽取其中一部分交回人工，过程中不展示模型的答案，因此报告出来的准确率来自独立的标注，而不是模型自己的置信度。

概述

ICL 标注系统会：

  1. 收集高置信度示例：识别标注者达成一致的实例（例如 80%+ 一致率）
  2. 使用 LLM 标注：用这些示例提示 LLM 标注尚未标注的实例
  3. 追踪置信度：记录每个预测的 LLM 置信度分数
  4. 验证准确性：抽取一部分 LLM 标注过的实例交给人工做盲审验证
  5. 报告指标：根据验证结果计算并展示 LLM 准确率

功能

自动示例收集

Potato 会按固定间隔，从标注者已经达成一致的实例中重建示例池，因此提示词跟随的是标注者，而不是服务器启动时的一份快照：

  • 可配置的一致率阈值（默认：80%）
  • 最少标注者数量要求（默认：2）
  • 按可配置的间隔自动刷新
  • 按方案分别维护示例池

最容易导致示例池为空的设置是最少标注者数量。它默认为 2，因此一个以 num_annotators_per_item: 1 运行的研究永远产生不了示例，工作进程会一直报告零个方案下的零个示例。单标注者研究请设置 min_annotators_per_instance: 1，或者调高 num_annotators_per_item。

带限制的 LLM 标注

三个限制可以防止模型在任何人检查过它的标签质量之前就把整个数据集标完：

  • 最大总标签数：限制 LLM 预测的总数
  • 最大未标注比例：只标注剩余数据中的一定百分比
  • 准确率过低时暂停：当实测准确率低于阈值时自动暂停

盲审验证

验证是盲审的。标注者看到的实例就是一个普通任务，没有任何模型预测的痕迹，因此他们给出的标签是独立的第二意见，而不是对眼前已有答案的复核：

  • 可配置的采样率（默认：LLM 标签的 20%）
  • 多种选择策略：low_confidence、random、mixed
  • 验证任务混入常规分配之中

配置

ICL 标注复用 ai_support 下配置的端点，因此该块必须存在并处于启用状态：

yaml
# AI endpoint configuration (required)
ai_support:
  enabled: true
  endpoint_type: "openai"
  ai_config:
    model: "gpt-4o-mini"
    api_key: "${OPENAI_API_KEY}"
 
# ICL labeling configuration
icl_labeling:
  enabled: true
 
  # Example selection settings
  example_selection:
    min_agreement_threshold: 0.8      # 80% annotators must agree
    min_annotators_per_instance: 2    # Minimum annotations for consensus
    max_examples_per_schema: 10       # Max examples per schema in prompt
    refresh_interval_seconds: 300     # How often to refresh examples
 
  # LLM labeling settings
  llm_labeling:
    batch_size: 20
    trigger_threshold: 5              # Min examples before LLM labeling starts
    confidence_threshold: 0.7         # Min confidence to accept prediction
    batch_interval_seconds: 600
    max_total_labels: 100             # Max instances to label total
    max_unlabeled_ratio: 0.5          # Max portion of unlabeled to label
    pause_on_low_accuracy: true
    min_accuracy_threshold: 0.7
 
  # Human verification settings
  verification:
    enabled: true
    sample_rate: 0.2                  # 20% of LLM labels verified
    selection_strategy: "low_confidence"
    mix_with_regular_assignments: true
    assignment_mix_rate: 0.2

四个示例选择设置全部位于 example_selection 之下，八个标注设置全部位于 llm_labeling 之下，五个验证设置全部位于 verification 之下。直接写在 icl_labeling 下的扁平配置块会被报告为无法识别的键，而不是被接受后忽略。

有两个值得专门设置的取值。max_total_labels 默认不限量，因此首次运行时应当给一个足够小的数字，让一个糟糕的提示词只花掉几十个预测而不是整个语料库。confidence_threshold 是一个预测能被存下来所必须达到的下限，因此调高它会丢弃模型最不确定的猜测，调低则会保留它们。

选择策略

  • low_confidence：优先验证 LLM 最不确定的预测
  • random：从所有预测中随机采样
  • mixed：50% 低置信度 + 50% 随机

管理员 API

状态端点

http
GET /admin/api/icl/status

返回 ICL 标注器的整体状态，包括每个方案的示例数、已做出的预测数、验证队列大小和准确率指标。

示例端点

http
GET /admin/api/icl/examples?schema=sentiment

返回高置信度示例，可按方案过滤。

预测端点

http
GET /admin/api/icl/predictions?schema=sentiment&status=pending

返回 LLM 预测，可按方案和验证状态过滤。

准确率端点

http
GET /admin/api/icl/accuracy?schema=sentiment

返回基于人工验证结果的准确率指标。

手动触发端点

http
POST /admin/api/icl/trigger
Content-Type: application/json
 
{"schema_name": "sentiment"}

无需等待间隔时间，直接为某一个方案触发一轮批量标注。

使用工作流

1. 配置项目

上限要低到你能逐条读完所有预测，验证率要高到能从这个上限中估算出准确率：

yaml
ai_support:
  enabled: true
  endpoint_type: "openai"
  ai_config:
    model: "gpt-4o-mini"
    api_key: "${OPENAI_API_KEY}"
 
icl_labeling:
  enabled: true
  example_selection:
    min_agreement_threshold: 0.8
  llm_labeling:
    max_total_labels: 50  # Start small
  verification:
    enabled: true
    sample_rate: 0.3  # Verify 30% initially

在 max_total_labels: 50 和 sample_rate: 0.3 的设置下，大约会有 15 个预测经过验证返回，这足以看出一个错得离谱的模型，但不足以区分 85% 和 90% 的准确率。

2. 收集人工标注

让标注者照常标注数据。达到一致率阈值的实例会在下一次刷新时成为可用的示例。

3. 监控进度

bash
curl http://localhost:8000/admin/api/icl/status

4. 检查准确率

bash
curl http://localhost:8000/admin/api/icl/accuracy

5. 迭代

根据准确率：

  • 如果准确率高（>80%），提高 max_total_labels
  • 如果准确率低，先补充更多人工示例再继续

最佳实践

  1. 从小规模开始：先用保守的限制（max_total_labels: 50），在扩大规模之前评估准确率

  2. 尽早验证：初期使用较高的 sample_rate（0.3-0.5），以得到可信的准确率估计

  3. 主动监控：通过管理员 API 定期检查准确率指标

  4. 调整阈值：如果 LLM 准确率偏低：

    • 提高 min_agreement_threshold，获得更干净的示例
    • 提高 trigger_threshold，让标注开始前积累更多示例
    • 提高 confidence_threshold，丢弃模型最不确定的预测

  5. 使用选择策略：

    • low_confidence：最适合找出有问题的类别
    • random：最适合得到无偏的准确率估计
    • mixed：折中方案

故障排除

LLM 没有在标注

  1. 检查 ai_support 是否配置正确
  2. 确认存在足够多的高置信度示例（/admin/api/icl/status）
  3. 检查标注是否因为限制或准确率过低而暂停

准确率低

  1. 提高 min_agreement_threshold，获得更干净的示例
  2. 补充更多标注指南和说明
  3. 检查正在使用的示例（/admin/api/icl/examples）

验证任务没有出现

  1. 确认 verification.enabled 为 true
  2. 检查 mix_with_regular_assignments 为 true
  3. 确认队列中确实有待验证项

延伸阅读

有关实现细节，请参阅源文档。