Skip to content

遷移 CLI

用 potato migrate 把 Potato 配置從 v1 遷移到 v2：它應用的五條規則，以及在寫入任何內容之前展示每項改動的 dry run。

potato migrate 把 v1 配置升級為 v2 格式，應用它能識別的每條規則，並報告改動了什麼。請先帶 --dry-run 執行一次，因為即使你本來就打算應用這些改動，這份報告也是有用的部分。

用法

bash
# Print the migrated config to stdout
potato migrate config.yaml --to-v2
 
# Write it to a new file
potato migrate config.yaml --to-v2 --output new_config.yaml
 
# Rewrite the original in place
potato migrate config.yaml --to-v2 --in-place
 
# Show what would change, without writing
potato migrate config.yaml --to-v2 --dry-run

命令選項

選項簡寫描述
--to-v2必需。 遷移到 v2 格式
--output FILE-o把遷移後的配置寫入此檔案，而不是輸出到 stdout
--in-place-i直接改寫原配置檔案
--dry-run報告改動但不寫入任何內容
--quiet-q抑制資訊性輸出

--in-place 和 --output 不能同時使用。

遷移規則

該工具應用五條規則，每條都會在輸出中按名稱報告。

1. highlight 改為 span

span 標註類型在 v1 中叫 highlight。在 v2 中它是 span，而 highlight 會在啟動時被拒絕，報 "Unknown annotation type: highlight"。這是 v1 到 v2 最常見的破壞性變更，跳過它的配置即使遷移之後也仍然起不來。

之前：

yaml
annotation_schemes:
  - annotation_type: highlight
    name: entities
    description: "Mark the named entities"
    labels: [PERSON, ORG]

之後：

yaml
annotation_schemes:
  - annotation_type: span
    name: entities
    description: "Mark the named entities"
    labels: [PERSON, ORG]

2. textarea 改為 multiline

v1 的 text scheme 在 textarea 塊裡配置多行行為。在 v2 中這些設定直接寫在 scheme 上，textarea 塊被移除。

之前：

yaml
annotation_schemes:
  - annotation_type: text
    name: feedback
    description: "Explain your reasoning"
    textarea:
      on: true
      rows: 4
      cols: 60

之後：

yaml
annotation_schemes:
  - annotation_type: text
    name: feedback
    description: "Explain your reasoning"
    multiline: true
    rows: 4
    cols: 60

如果舊塊裡設定了 rows 和 cols，它們會被一併帶過來。

3. 舊版使用者配置

有 user_config 但沒有 login 塊的配置會被補上一個。user_config 塊本身在 v2 中仍然有效，會予以保留。

之前：

yaml
user_config:
  allow_all_users: true

之後：

yaml
user_config:
  allow_all_users: true
login:
  type: open

如果用的是 users 列表而不是 allow_all_users，補上的塊會是 type: password。

在依賴補上的這個塊之前先檢查一下。遷移工具寫的是 type: open，而 Potato 路由識別的登入類型是 standard、url_direct 和 prolific，所以開放訪問的任務通常還是交給 user_config.allow_all_users: true 來處理更合適。

4. 舊版標籤要求

label_requirement 在 v1 中接受布林值，在 v2 中接受一個對映，因此這條規則負責轉換它。

之前：

yaml
annotation_schemes:
  - annotation_type: radio
    name: sentiment
    description: "What is the sentiment?"
    labels: [Positive, Negative]
    label_requirement: true

之後：

yaml
annotation_schemes:
  - annotation_type: radio
    name: sentiment
    description: "What is the sentiment?"
    labels: [Positive, Negative]
    label_requirement:
      required: true

5. 輸出格式

自 v2 儲存層重寫以來，output_annotation_format 就沒有被讀取過：無論它寫的是什麼，標註都會寫到 <output_annotation_dir>/<user>/user_state.json。這條規則把它摺疊到 export_annotation_format 上，後者會按該格式定期匯出。

之前：

yaml
output_annotation_dir: "output/"
output_annotation_format: "json"

之後：

yaml
output_annotation_dir: "output/"
export_annotation_format: jsonl

示例：一次 dry run

bash
$ potato migrate old_config.yaml --to-v2 --dry-run
 
Migration changes:
 
[highlight_to_span] Rename the legacy highlight annotation type to span:
  - Renamed annotation_type: highlight -> span in scheme 'entities'
 
[textarea_to_multiline] Convert textarea.on to multiline format in textbox schemas:
  - Converted textarea.on to multiline in schema 'feedback'
 
[legacy_user_config] Migrate legacy user_config to login format:
  - Added login.type: open (from allow_all_users: true)
  - Note: user_config is still valid, login section added for clarity
 
Dry run - no changes written.

遷移之後

啟動伺服器之前先執行校驗器，因為遷移工具修的是它認識的那些形態，其餘的由校驗器發現：

bash
potato validate new_config.yaml --strict

--strict 會把警告（例如一個無法識別的鍵）變成失敗，而不是打印出來然後放行。

什麼時候用它

  • 升級一個為更早版本 Potato 編寫的項目
  • 啟動時出現棄用警告
  • 某個配置項被忽略，而你不確定原因

故障排除

"Configuration file is empty"

檔案無法解析，或者裡面什麼都沒有。請檢查它是否存在、是否可讀、是否包含 YAML。

"Invalid YAML in configuration file"

語法錯誤。常見原因是縮排不一致、缺少冒號，或者未加引號的值裡含有冒號。

"No migrations needed"

五條規則一條也沒有命中，說明配置在這些規則覆蓋的範圍內已經是 v2 的形態。這和配置有效並不是一回事，所以還要再跑一次 potato validate --strict。

延伸閱讀

有關實現細節，請參閱原始碼文件。