Skip to content
指南閱讀約需 5 分鐘

整合 LLM 實現智慧標註提示

把 OpenAI、Anthropic、Gemini 或本地模型接入 Potato，讓標註者獲得提示、關鍵詞高亮和標籤理由，同時保留最終決定權。

Potato Team

一個好的 LLM 接入方式能讓標註更快、更一致。本指南介紹如何接入 OpenAI、Anthropic、Gemini 和本地模型，讓標註者獲得有用的建議，同時把決定權留給打標籤的人。

助手能做什麼

開啟 ai_support 後，每個標註方案會帶上三個按鈕，標註者需要幫助時點選它們：

  • Hint 給出如何思考該條目的引導，有時會帶一個建議標籤
  • Keyword 標出與各標籤相關的詞語，以文字上方的方框繪製
  • Rationale 解釋每個可選標籤為何可能適用

標籤建議不是單獨的按鈕。當提示帶有建議標籤時，該標籤會用琥珀色邊框和一個閃爍圖示標出。

關於 AI 支援層的實現方式，見源文件。

基本 OpenAI 整合

yaml
annotation_task_name: "AI-Assisted Sentiment Analysis"
task_dir: "."
 
ai_support:
  enabled: true
  endpoint_type: openai
  ai_config:
    model: gpt-4o-mini
    api_key: ${OPENAI_API_KEY}
    temperature: 0.3
    max_tokens: 800
    include:
      all: true
 
data_files:
  - data/texts.json
 
item_properties:
  id_key: id
  text_key: content
 
annotation_schemes:
  - annotation_type: radio
    name: sentiment
    description: "What is the sentiment of this text?"
    labels: [Positive, Negative, Neutral]
 
output_annotation_dir: annotation_output/
export_annotation_format: jsonl

這段配置有兩點值得注意，因為兩者出錯時都不會報錯：

include.all 是總開關。 它預設關閉，不開啟就不會出現任何助手按鈕。頁面渲染出一個空的 AI 面板，校驗通過，也沒有任何警告。

模型設定放在 ai_config 裡面。 ai_support.model 會被忽略。potato validate --strict 會指出這個鍵，是最快的排查方式。

把 max_tokens 留在 800 或以上。Keyword 和 Rationale 助手會在一次回覆裡覆蓋所有標籤，預算更小會截斷響應，助手渲染為空且不報錯。

支援的提供商

OpenAI

yaml
ai_support:
  enabled: true
  endpoint_type: openai
  ai_config:
    model: gpt-4o-mini
    api_key: ${OPENAI_API_KEY}
    temperature: 0.3
    max_tokens: 800
    include:
      all: true

Anthropic

yaml
ai_support:
  enabled: true
  endpoint_type: anthropic
  ai_config:
    model: claude-sonnet-4-20250514
    api_key: ${ANTHROPIC_API_KEY}
    temperature: 0.3
    max_tokens: 800
    include:
      all: true

Google Gemini

端點名是 gemini：

yaml
ai_support:
  enabled: true
  endpoint_type: gemini
  ai_config:
    model: gemini-2.0-flash-exp
    api_key: ${GOOGLE_API_KEY}
    max_tokens: 800
    include:
      all: true

用 Ollama 跑本地模型

yaml
ai_support:
  enabled: true
  endpoint_type: ollama
  ai_config:
    model: llama3.2
    base_url: http://localhost:11434
    max_tokens: 800
    include:
      all: true

當語料不能離開本機，或者大規模研究中每條目的成本會吃掉大部分預算時，本地端點值得承受品質上的損失。vllm 和 huggingface 用同樣的寫法。

按方案開啟助手

include.all 會在所有位置啟用所有助手。另一種做法是 special_include，它把頁面序號對映到標註 id，再對映到該方案應該帶的助手：

yaml
ai_support:
  enabled: true
  endpoint_type: openai
  ai_config:
    model: gpt-4o-mini
    api_key: ${OPENAI_API_KEY}
    max_tokens: 800
    include:
      all: false
      special_include:
        "0":
          "0": ["hint", "keyword"]
        "1":
          "1": ["hint"]

內層的鍵是標註 id，也就是該方案在 annotation_schemes 中從零開始的位置。方案較多時這一點很重要：在所有位置開啟全部三個助手，頁面上會出現九個按鈕。

高亮可能的標籤

如果問題出在選項列表太長而不是文本太長，option_highlighting 會標出最可能的選項並把其餘選項調暗。所有選項仍然可以點選：

yaml
ai_support:
  enabled: true
  endpoint_type: openai
  ai_config:
    model: gpt-4o-mini
    api_key: ${OPENAI_API_KEY}
    max_tokens: 800
 
  option_highlighting:
    enabled: true
    top_k: 3
    dim_opacity: 0.4

它對 radio、multiselect、likert 和 select 有效，對 span、自由文本和滑塊無效。見選項高亮。

快取與預取

一次 LLM 呼叫會給頁面載入增加幾秒鐘，而等待中的標註者會不再點那個按鈕：

yaml
ai_support:
  enabled: true
  endpoint_type: openai
  ai_config:
    model: gpt-4o-mini
    api_key: ${OPENAI_API_KEY}
    max_tokens: 800
    include:
      all: true
 
  cache_config:
    disk_cache:
      enabled: true
      path: annotation_output/ai_cache.json
    prefetch:
      warm_up_page_count: 20
      on_next: 10
      on_prev: 3

快取在重啟後依然存在，所以標註者重新訪問某個條目時第二次不再產生開銷。

完整配置

yaml
annotation_task_name: "AI-Assisted NER Annotation"
task_dir: "."
 
ai_support:
  enabled: true
  endpoint_type: openai
  ai_config:
    model: gpt-4o-mini
    api_key: ${OPENAI_API_KEY}
    temperature: 0.2
    max_tokens: 800
    include:
      all: true
 
  cache_config:
    disk_cache:
      enabled: true
      path: annotation_output/ai_cache.json
    prefetch:
      warm_up_page_count: 20
      on_next: 5
      on_prev: 2
 
data_files:
  - data/texts.json
 
item_properties:
  id_key: id
  text_key: content
 
annotation_schemes:
  - annotation_type: span
    name: entities
    description: "Label the named entities in this text"
    labels:
      - name: PERSON
        color: "#FF6B6B"
      - name: ORG
        color: "#4ECDC4"
      - name: LOC
        color: "#45B7D1"
      - name: DATE
        color: "#96CEB4"
 
output_annotation_dir: annotation_output/
export_annotation_format: jsonl

自定義提示詞

提示詞是 potato/ai/prompt/ 下的 JSON 檔案，每種標註類型一個：

標註類型提示詞檔案
Radioradio.json
Likertlikert.json
Multiselectmultiselect.json
Spanspan.json
Sliderslider.json
Selectselect.json
Numbernumber.json
Free texttextbox.json

每個檔案為每個助手儲存一個模板，包含 name、prompt 和 output_format。可用變數是 ${text}、${description}、${labels}、${min_label}、${max_label}、${size}、${min_value} 和 ${max_value}。

使用 AI 建議

儲存下來的標註始終屬於標註者，所以人工稽核在結構上就得到了保證。但這保證不了獨立性：不加核對就接受建議的標註者，產出的標籤之所以彼此一致，是因為它們來自同一個模型，在這些標籤上計算的一致性衡量的是模型而不是任務。

因此要關注接受率。接近 100% 的接受率通常意味著建議只是被確認，而沒有被核對。

技巧

一開始保守一些，在模型於你的資料上贏得信任之前逐條稽核建議。接受率低通常說明要改的是提示詞，而不是標註者。根據實際出現的錯誤而不是預想的錯誤來調整提示詞。並且長期跟蹤 AI 標籤與人工標籤的對比，因為只有這個對比能說明輔助究竟有多準。

下一步

完整 AI 文件見 AI 支援。