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 叢集或輪詢代理。
• 模型輔助標註指南討論來自你自己模型的預標籤何時幫助標註者，何時錨定標註者。
• 上游模型訓練參考有每個訓練器的參數列。