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 支持。