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。

延伸阅读

有关实现细节，请参阅源代码文档。