Potato 中按任务分组的模型训练器

v2.14.0 新增

Potato 的模型训练有 38 个训练器，每个训练器针对一类标注方案的答案拟合一种模型。本页的表格按任务列出每个训练器，包括训练器所学习的方案、读取的条目、需要的安装、回写的预标签，以及每次运行报告的留出得分。本页面向在第一次运行之前选择训练器，或想确认某个方案能否训练的研究负责人。配置键、后端和回写规则见配置页。每个训练器的完整参数表在上游参考中该训练器的小节里，下文的每个训练器名都链接到对应小节。

每个方案可用的训练器

/admin/training 上的训练页面只为每个方案提供适合该方案的种类和条目模态的训练器，模态例如文本、图像或音频。项目无法运行的训练器会连同原因留在列表里，例如在项目有决策模型之前，decision-calibrate 显示“no decision model is configured”。缺少包的训练器列为“not installed”，并附上安装这些包的命令。在你选定训练器之前，凡是适用 sklearn-text 的地方，默认选中的都是 sklearn-text。为不存在的方案，或为训练器无法学习的方案启动的运行，会在构建任何内容之前以 HTTP 400 被拒绝。

每次运行只训练一个方案。训练页面只发送一个方案，训练 API 接受方案列表，但每个训练器只拟合列表中的第一个方案。要训练两个方案，请启动两次运行。

在下面的表格中，Pre-label 列说明方案列在 writeback.schemas 之后，运行会往条目上写什么。运行的 train 划分里的条目永远不会得到预标签，只有当标注者编辑了预标签或转到下一个条目时，预标签才会成为标注者的答案。Held-out score 列给出这次运行的主指标名称，它是在 val 和 test 条目上对照标注者合并后的标签算出的。有标签而没有预测的条目算作错误，因此训练器无法靠跳过难条目来抬高得分。上游参考中的留出得分定义了每个指标。

安装训练器

sklearn-text 只需要普通的 Potato 安装，因为 scikit-learn 是核心依赖。文本、图像、音频和 LLM 训练器需要 PyTorch 和 transformers。一个 extra 就能安装这四组的全部包：

pip install "potato-annotation[train]"

更窄的 extra [train-text]、[train-vision]、[train-audio] 和 [train-llm] 各安装一组，下表的 Install 列给出能覆盖每个训练器的最窄 extra，例如 pip install "potato-annotation[train-vision]"。这些训练 extra 都不在 potato-annotation[all] 之内，因为 PyTorch 的安装有好几个 GB。有些训练器需要 [train] 之外的包：

• ultralytics-detect 和 ultralytics-segment 需要 pip install ultralytics。
• cellpose 需要 pip install cellpose，Cellpose 3 或 Cellpose 4 都可以。
• laya-finetune 需要 [decision]，openjev-finetune 需要 pip install wev-ai。
• rdkit-property 需要 [chemistry]，volume-unet 需要 [volumes]，video-track 需要 opencv-python，WFDB 或 Parquet 信号需要 [signals]。全玻片图像需要用于 openslide 的 [wsi]。
• hf-text-classification 和 hf-image-classification 的 dp 选项需要 pip install opacus。

ultralytics-detect、ultralytics-segment 和 layoutlmv3 在第一次运行前会请你确认许可证。Ultralytics 是 AGPL-3.0，因此用任一 YOLO 训练器训练并分发的模型都适用 AGPL 的条款，Ultralytics 另售用于闭源场景的许可证。LayoutLMv3 的权重是 CC BY-NC-SA 4.0，不可商用。对这三个训练器，训练页面都会请求确认，API 运行需要 accept_licence: true，自动重新训练需要 auto_retrain.accept_licence: true。Cellpose 的代码是 BSD-3-Clause，Cellpose 的作者按各自的条款发布 Cellpose 的预训练权重。你在 model_name 里指定的检查点，许可证也各不相同。例如 Qwen2.5-VL-3B 适用 Qwen 研究许可证，而 Qwen2.5-VL-7B 是 Apache-2.0。

参数

一次运行的参数来自三处，后一处覆盖前一处：

1. 训练器的默认值，列在该训练器的上游小节里；
2. 配置里的 model_training.trainer_params.<trainer>；
3. 这次运行自己的 params，即训练页面上的 Parameters 字段、API 运行的 params，或 auto_retrain.params。

把 trainer_params 加到 model_training 块里，就能为你用到的每个训练器设置默认值：

model_training:
  enabled: true
  trainer_params:
    hf-text-classification:
      model_name: answerdotai/ModernBERT-base
      epochs: 4
    torchvision-detect:
      model_name: fasterrcnn_resnet50_fpn_v2
      score_threshold: 0.4

训练页面上的 Parameters 字段是 JSON，内容由所选训练器的 trainer_params 填入。训练器不接受的参数名是错误。写在 trainer_params 下的名字会让服务器在启动时停下，写在运行自己的 params 里的名字则会让运行在开始之前停下。两种错误都会列出该训练器接受的名字。例如，torchvision-detect 下拼错的 score_thresh 会连同列表里的 score_threshold 一起报告。Potato 还会按参数的类型和取值范围检查每个值。

文本和图像分类器

分类器从选择类方案 radio、select、likert 和 multiselect 中学习。radio、select 或 likert 的预标签选中一个答案，multiselect 的预标签勾选一组标签。sklearn-text 在 CPU 上运行，不需要额外安装，第一个模型教程演示了用 sklearn-text 做一次运行。在图像语料上，sklearn-text 把分类器拟合到 CLIP 图像嵌入上。setfit 为项目的最初几天而设计，每个标签有大约八个已标注条目就能工作。radio 和 multiselect、select 和 Likert 量表的方案页面介绍了标注一侧的内容。

hf-text-classification 微调一个 transformer，设置 lora: true 时还能微调 Qwen 或 Llama 这样的解码器 LLM。设置 soft_targets: true 时，hf-text-classification 朝着标注者的投票分布训练，而不是朝着一个合并后的标签训练。hf-text-classification 和 hf-image-classification 接受 acquisition 参数，它按 margin、熵、BALD 或 coreset 距离，为单标签方案排出接下来要标注的条目顺序，循环中的模型教程有演示。这两个训练器还接受 dp，通过 Opacus 用 DP-SGD 训练，差分隐私教程演示了一次 dp 运行。

跨度、关系和结构

这一组训练器学习带字符偏移的跨度、跨度之间的链接、对话树节点上的答案，以及逐行词素注解。hf-relation 训练一个编码器来标记跨度，并对跨度对分类。只有当跨度标记模型同时以正确的边界找到链接的两个跨度时，预测出的链接才算找到。当 span_link 方案的每个训练答案都是依存树时，hf-relation 解码出树，并在得分里加上 UAS 和 LAS。一次运行的步骤与第一个模型教程相同，只是选择的训练器和方案不同。

LLM 和奖励模型

LLM 训练器从自由文本答案、偏好、排序和修正过的智能体轨迹中学习。llm-sft 和 llm-dpo 默认训练 LoRA 适配器，lora: {quantize: 4bit} 以 QLoRA 的方式用 4 位加载基础模型。reward-model 从成对、排序和最好-最差答案训练一个标量奖励模型，每个预测都在方案的答案旁保留各选项的奖励。prm-reward 把智能体轨迹的每一步评为正确、中性或错误。超出 max_length（默认 1,024 个 token）的步骤既不参与训练，也不被评分。trajectory_edit 的预测会被打分和存储，但从不显示为预标签，并且服务器会拒绝启动 writeback.schemas 下带有 trajectory_edit 方案的配置。LLM 微调教程涵盖 SFT、DPO、奖励模型、过程奖励模型和 QLoRA。

图像检测与分割

检测器和分割器学习标注者在 image_annotation 方案里画出的形状，其中大多数还能读取显微图像、地图和频谱图方案。检测器按每个形状的外接框训练，因此多边形或掩码的研究仍然训练出框检测器。分割器在轮廓上训练，不使用框，并预测最多 64 个顶点的多边形，标注者可以逐点编辑。cellpose 的分割不带类别，因此每个预测出的细胞都得到 label 参数，label 未设置时则得到方案中最常见的标签。

sam-finetune 微调 Segment Anything 的掩码解码器，把框变成轮廓，同时图像编码器保持冻结。sam-finetune 运行为较早的检测运行回写的框预标签画出轮廓，因此通常的顺序是先做一次 writeback.include_unlabeled: true 的检测运行，再在同一方案上做一次 sam-finetune 运行。在 Mac 上，torchvision-detect 和 torchvision-segment 在 CPU 而不是 Metal 上训练。视觉模型教程演示检测、分割、玻片、显微图像、地图、Cellpose 和 SAM。

图像训练器读取任务目录或 media_directory 内的本地文件。远程的 http(s) 图像不会被下载，图像为远程或缺失的行会被排除在运行之外，也得不到预测。上游参考中的图像条目给出 Potato 读取图像路径所用的字段。

玻片、显微图像、地图和频谱图

检测和分割训练器把每幅图像缩放到几百像素。因此对于 image_annotation、microscopy 或 geo_annotation 方案，Potato 在构建运行的数据包时会把大图像切成图块。切块对 .svs 和 .ndpi 这类玻片格式默认开启，对较长边至少 4,096 像素的图像也默认开启。同一张玻片的图块总是落在同一个划分里，预测出的形状会映射回整幅图像，坐标采用深度缩放查看器存储的坐标。tiling 表列出每个键，视觉模型教程为一张玻片设置图块大小、重叠和分辨率。

microscopy 方案的 ROI 可以训练检测和分割训练器以及 cellpose。每个带 ROI 的 z 切片和时间点，都用方案的默认通道和对比度渲染，预测以 ROI 的形式返回，并带有每个 ROI 的 z 和 t。geo_annotation 方案在条目的栅格底图上训练，底图即 GeoTIFF 或带范围的图像，预测以 EPSG:4326 的 GeoJSON 返回，地图把它显示为建议。底图来自瓦片服务器的地图没有可供训练的栅格，运行会带警告把这些条目排除在外。spectrogram_annotation 方案用渲染成频谱图的每段录音训练 torchvision-detect 和 ultralytics-detect，框以秒和赫兹返回。上游参考中的显微图像和地图与频谱图给出渲染细节。

文档和视觉语言模型

layoutlmv3 根据页面上的词及其位置学习文档版面，vlm-sft 在关于图像的回答上微调视觉语言模型。Potato 不做 OCR，所以每个 layoutlmv3 条目都需要一个带有每个词的文本和框的 words 字段。regions 模式下的 PAGE XML 导入会填充 words，PDF 文本层或其他 OCR 工具产生的词也同样可用。vlm-sft 默认训练 LoRA 适配器，真实的检查点需要 GPU。region_caption 的运行会被打分但不发布，因为一段说明所描述的区域是标注者的答案。视觉模型教程涵盖这两个训练器，VLM 定位涵盖 grounding_eval 方案。

音频和语音

音频训练器从 soundfile 能打开的本地文件读取录音，例如 WAV 或 FLAC，音频是 URL 的条目会被排除。hf-audio-tagger 在 audio_annotation 方案里为带标签的时间段打标。whisper-asr 在标注者修正过的转录轮次上微调 Whisper，默认还会写出模型的 CTranslate2 副本，供 potato transcripts --transcribe 和 faster-whisper 使用。diarization 微调一个语音编码器（默认 WavLM），找出谁在何时说话。说话人名称只在每段录音内部有效。频谱图框训练的是图像检测与分割里的检测器。音频模型教程演示 Whisper、说话人分离、频谱图检测和音频打标。

体数据、点云和视频

3D 和视频训练器从绘制的体数据、点云长方体和视频轨迹中学习。volume-unet 在纯 PyTorch 中，用标注者在 CT 和 MR 体数据上绘制的掩码训练 3D U-Net，全尺寸的 CT 实际上需要 GPU。external-3d 通过 train_command 和 predict_command 参数运行你自己的 3D 检测器，并读回长方体。OpenPCDet 和 MMDetection3D 都适用，两者都需要在 GPU 主机上编译 CUDA 算子。video-track 在从已标注轨迹采样的帧上微调 Faster R-CNN，并把各帧之间的检测连成轨迹。体数据、点云和视频教程演示这三个训练器。

科学

科学类训练器从化学、光谱学、生理信号和机器人回合中学习。rdkit-property 根据分子的 Morgan 指纹和 RDKit 描述符回答关于分子的问题，选择题用 scikit-learn 分类器，滑块用回归器。peak-cnn 预测光谱上的峰位置，不预测峰的标签或归属。signal-cnn 对 EEG、ECG 和其他信号划分固定时期的阶段，或找出带标签的区间。episode-model 根据机器人回合的关节和传感器序列预测阶段、结果和奖励曲线，不读取回合的视频。峰、区间和回合答案以建议的形式出现，由标注者审核，而不是直接作为答案。科学模型教程演示这四个训练器，化学结构、光谱、时间序列和机器人回合的方案页面介绍标注一侧的内容。

决策模型

决策模型为一个问题的每个选项返回一个概率，Potato 把决策模型用作标注引擎的来源，或用作 Solo Mode 里的标注模型。决策模型训练器在研究的标签上，对 radio、select、likert 和 slider 方案拟合决策模型，并按标注引擎提问的方式提出每个问题。slider 被当作评分来问，每个位置一个选项，最多 21 个位置。decision-calibrate 不训练任何东西，它对 Jev、OpenJev、laya-serve 或 Laya 给出的概率拟合一个校准，并把校准写入 calibration.json，供引擎来源应用。decision-calibrate 只在 local 后端上运行。laya-finetune 微调 Laya，openjev-finetune 用 wev 的 LoRA 训练微调 80 亿参数的 OpenJev 模型。OpenJev 的模型卡指出，OpenJev 的部分训练数据仅限研究使用。商用之前请核对这些条款。

推理桥

推理桥使用已在别处运行的模型，自己不训练任何东西。一次桥运行把留出条目发送给该服务，再读回答案。带 writeback.include_unlabeled: true 时，运行也会发送未标注的条目。这些答案随后得到对照你的标注者的留出得分、回写和审核，与训练出的模型的答案相同。桥从不在配置里接受 API 密钥，而是由一个参数给出服务器上存放密钥的环境变量名。label-studio-ml 调用 Label Studio ML 后端的 /predict，不会向该后端的 /webhook 发送标注事件。hf-inference 和 roboflow 只在 local 后端上运行。openai-vlm-boxes 的框没有置信度，因为视觉语言模型不返回分数。自带模型教程设置每一座桥。

延伸阅读

• 模型训练概览说明从标注到预标签的循环和训练页面。
• 配置页记录每个 model_training 键、后端、回写和路由。
• 第一个模型教程在没有 GPU 的情况下端到端运行 sklearn-text。
• 远程训练教程把运行发送到 ssh GPU 服务器、SLURM 集群或轮询代理。
• 模型辅助标注指南讨论来自你自己模型的预标签何时帮助标注者，何时锚定标注者。
• 上游模型训练参考有每个训练器的参数表。