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. 確認佇列中確實有待驗證項

延伸閱讀

有關實現細節，請參閱源文件。