Skip to content
Announcements2 min read

Potato 2.11：标注引擎与经过认证的机器标签

Potato 2.11 用模型为数据集打标签，在一份盲态人工样本上检验这些机器标签，并写出一份证书。闲置会话现在会在 8 小时后自动登出。

Potato Team

Potato 2.11 新增了标注引擎。它用模型为数据集打标签，再用一份盲态随机抽取的人工标签样本来衡量模型出错的频率。你声明最终标签必须满足的条件，例如被接受的机器标签中至多 10% 是错的，置信度为 90%。引擎接受统计检验所支持的机器标签，把其余条目交给人来标注，并写出一份证书，记录检验了什么、用了多少条人工标签。这个版本还把一致性报告扩展到 3D 物体、时间定位、分层标注和智能体轨迹，并修复了一个图像缺陷，它可能把没人动过的条目算作已作答。

bash
pip install --upgrade potato-annotation

升级说明

闲置会话现在会被登出，默认是 8 小时之后。 在 2.11 之前，session_timeout_minutes 对正在运行的应用不起作用，因为这项检查注册在一个会被 potato start 丢弃的应用对象上。现在，闲置时间超过这一设置的会话会被清除，它的下一个请求会转到登录页面。整夜保持登录的自助终端和实验室共用电脑会开始遇到登出，所以如果某项研究依赖于保持登录，请调高 session_timeout_minutes。已经保存的标注不受影响。

三个旧键会在启动时打印一条提示。 icl_labeling、judge_calibration 和 pre_annotation 的行为和以前完全一样，只是每个都会向 stderr 打印一行以 NOTE: 开头的文字，指出它在引擎中的对应项。这些提示仅供参考，所以 potato validate --strict 不会因此失败。这些键计划在 3.0 中移除，potato label migrate-config 会替你写出等价的 labeling_engine 配置块。

标注引擎

引擎适用于条目多到人标不完、而模型大多数时候都对的研究。它把模型当作来源，按你列出的顺序以级联方式逐个尝试，在最后一个来源之后把条目交给人。来源可以是 LLM、视觉语言模型、Laya 这样的决策模型、YOLO 检测器、LLM 评审、评审团、用本研究自身标签训练的模型，或者你已有的标签。

契约是引擎要检验的东西。最主要的一种是 selective_risk，它限定被接受的机器标签中出错的比例。引擎在盲态样本的一半上选定置信度阈值，在另一半上用单侧二项检验来检验它，采用固定序列的 Learn-then-Test。每一次新检验都使用更严格的水平，所以反复认证直到检验通过并不会抬高置信度。ppi 契约报告每个标签的流行率，并附上一个用预测驱动推断（prediction-powered inference）构造的区间，无论模型质量如何，这个区间都有效。no_worse_than_human 运行替代标注者检验，用于判断能否替换一个人或一个评审；distributional 则在主观条目上，把模型的标签分布与人们的意见分布作比较。

在一份普通研究的配置里加上两个键，就能在一个情感方案上认证一个 LLM：

yaml
assignment_strategy: engine
 
labeling_engine:
  enabled: true
  sources:
    - id: gemma
      kind: llm
      endpoint_type: vllm
      model: google/gemma-4-12B-it-qat-w4a16-ct
      base_url: http://localhost:8001/v1
      confidence: {method: logprob}
  contracts:
    - id: accuracy
      kind: selective_risk
      schema: sentiment
      error: 0.1
      confidence: 0.9
  budgets:
    human_labels: 400

confidence: {method: logprob} 根据模型的 token 概率读出置信度，每个条目只需一次调用，而且通常是引擎各种置信度方法中校准得最好的。这份契约允许被接受的标签中至多 10% 是错的，90% 的置信度是 Potato 的默认值。budgets.human_labels 限定引擎最多能发出多少个人工请求，400 是随附文本示例所用的上限。

Potato 随附的文本示例让 481 条评论经过一个 Laya 在前、Gemma 12B 在后的级联。在那次运行中，10% 的契约用 165 条人工标签得到满足，引擎接受了 316 条机器标签，全部来自 Gemma，因为 Laya 的阈值始终没有定下来。对照参考标签，这些标签实测的错误率为 7.6%。智能体轨迹示例有 288 条带参考结果的合成轨迹。评审在其中 80% 上判断正确，但它给每个判定的置信度都是 1.0，所以 selective_risk 没有可以设阈值的依据，一直处于不可行状态。用同一份数据算出的任务成功率 PPI 区间 [0.57, 0.76] 覆盖了 0.60 的参考比率，而评审单独给出的是 0.76。

已满足的契约有哪些局限

已满足的契约是一项关于与标注样本的那些人之间一致程度的陈述。引擎不会检查这些人是否正确，所以用粗心的标注者检验的契约，认证的是与粗心标注者的一致。有三条规则保证这项陈述成立。校准请求是盲态的，所以当某人持有校准请求时，页面不显示任何预标注、评审判定或 AI 帮助。阈值在样本的一半上选定，在另一半上检验。只有人工标签能用于认证，对来源、提示词或方案的任何改动，都会把受影响的契约标为 stale，直到它们再次被检验。

引擎的接口

每个接口背后都是同一个 engine.sqlite 文件，所以你可以在一个接口里开始研究，在另一个接口里认证：

  • 命令行上的 potato label run|status|certify|certificate|export|calls|distill|optimize|migrate-config；
  • 位于 /api/engine/v1 下的 REST API；
  • MCP 服务器中的五个 engine_* 工具；
  • Python 中的 potato.labeling_engine.sdk.Study；以及
  • 位于 /admin/labeling-engine 的管理页面，显示契约状态、错误率随覆盖率变化的曲线、每个来源的可靠性图和模型调用日志。

potato label export 会写出带来源信息的标签、JSON、Markdown 和 HTML 三种格式的证书、一份数据集卡片和调用日志。标注引擎一页带你走完第一项研究，标注引擎契约说明每种契约检验什么、在什么情况下不成立。

Solo Mode

Solo Mode 现在可以隐藏它的建议。solo_mode.suggestions 会在所有条目上，或在一份随机样本上，扣下 LLM 给出的标签。屏幕上的建议会把答案往它那边拉，所以交接时读取的是盲态条目上的一致性。决策模型（laya 以及任何提供 /v1/systemone 的服务器）可以充当快速的第一层，Solo Mode 也会在标注开始前和每一批之前检查项目的 ai_budget.cap_usd。黄金集、标注评审团和课程式排序也是新增的。开启引擎时，Solo Mode 会把它的预测写进引擎的存储，这样引擎就能校准并认证这些预测。配置见 Solo Mode。

一致性

/admin/iaa 现在会报告 spatial_annotation、temporal_grounding、tiered_annotation 以及五种智能体轨迹方案上的一致性，以前它会把这些方案当作不受支持而跳过。3D 物体和时间片段得到的是平均匹配集一致性，它没有做机会校正；智能体轨迹的步骤则以每条轨迹的每一步为单位，得到 Krippendorff's alpha 和 Cohen's kappa。/admin/api/agreement 不再报告结构化方案，而是改为指向 /admin/iaa，因为这些方案被简化为标签名后，任意两位标注者之间都显示为完全一致。两个相同的零长度片段现在算作一致。Publishing 和 Paper Mode 会把机器评分者排除在黄金标签和一致性数字之外。

影响 2.10 研究的修复

有三项修复可能会改变你已经收集或报告的数字：

  • 图像页面会自行保存预填的答案。 在带有 pre_annotation 的 image_annotation 方案上，画布在加载后重新布局时，会把预填的形状保存为标注者的答案，于是一个没人动过的条目被算作已作答。在一项带预标注的 2.10 图像研究中，保存的形状与预标注完全一致的条目可能从未被人动过，所以除非你的计时数据表明并非如此，请把这些条目当作未审核处理。
  • Paper Mode 用自己的代码计算 kappa。 Paper Mode 和一致性模块现在与 /admin/iaa 通过同一个函数计算 Cohen's kappa，所以对同一份数据，2.11 之前从 Paper Mode 报告的 kappa 可能与 /admin/iaa 显示的不同。
  • 仲裁和 Prolific 自动扩容把机器评分者也算了进去。 机器标注者可能把条目送去仲裁，min_human_annotations 被忽略，Prolific 自动扩容还把机器标注计入了每个条目的上限。

其余修复改变的是研究能做什么。来自不发送 CORS 头的主机（例如 cocodataset.org）的图像现在可以加载了。在这类图像上，泛洪填充、SAM 和文本提示分割现在会说明为什么无法读取它。没有 color 的预标注形状会采用其标签的颜色，而不是被丢弃。Solo Mode 的 "Generate prompt" 现在会让修订模型来写第一版提示词。通过 potato mcp connect 发出的拒绝现在以工具错误的形式返回，而不是被当作成功。边缘案例发现现在可以在 vLLM 上运行，此前 vLLM 不返回边缘案例字段，直到这些字段被加入响应 schema。

安装 2.11

用 pip install --upgrade potato-annotation 升级，或者拉取 ghcr.io/davidjurgens/potato:2.11.0。进程内运行的 Laya 决策模型需要新的 decision 附加依赖，即 pip install 'potato-annotation[decision]'；由于它会引入 torch，它不包含在 all 中。发布说明列出了每一项改动，新功能汇总了每个 2.x 版本的内容。