Skip to content

マイグレーションCLI

古い形式の設定ファイルを現在のv2形式にアップグレードする。

マイグレーションCLI

Potatoには、古い形式の設定ファイルを現在のv2形式にアップグレードするためのマイグレーションツールが含まれています。このツールは必要な変更を自動的に検出・適用しながら、既存の設定を保持します。

使用方法

bash
# Basic migration (prints migrated config to stdout)
potato migrate config.yaml --to-v2
 
# Save to a new file
potato migrate config.yaml --to-v2 --output new_config.yaml
 
# Modify the original file in place
potato migrate config.yaml --to-v2 --in-place
 
# Preview changes without applying them
potato migrate config.yaml --to-v2 --dry-run

コマンドオプション

オプション短縮形説明
--to-v2必須。 v2形式に移行
--output FILE-o移行した設定を指定ファイルに書き込む
--in-place-i元の設定ファイルを直接変更する
--dry-run変更を適用せずに何が変更されるかを表示
--quiet-q情報出力を抑制

注意： --in-placeと--outputは同時に使用できません。

マイグレーションルール

マイグレーションツールは以下の変換を適用します：

1. textareaからmultilineへ

テキストスキーマの古いtextarea形式を新しいmultiline形式に変換します。

変更前：

yaml
annotation_schemes:
  - annotation_type: "text"
    name: "feedback"
    textarea:
      on: true
      rows: 4
      cols: 50

変更後：

yaml
annotation_schemes:
  - annotation_type: "text"
    name: "feedback"
    multiline: true
    rows: 4
    cols: 50

2. レガシーユーザー設定

古いuser_config形式を検出し、明示的なlogin設定の追加を提案します。

変更前：

yaml
user_config:
  allow_all_users: true

変更後：

yaml
user_config:
  allow_all_users: true
login:
  type: open

3. ラベル要件の形式

ブール値のlabel_requirementを辞書形式に変換します。

変更前：

yaml
annotation_schemes:
  - annotation_type: "multirate"
    name: "ratings"
    label_requirement: true

変更後：

yaml
annotation_schemes:
  - annotation_type: "multirate"
    name: "ratings"
    label_requirement:
      required: true

4. 出力形式の提案

古い出力形式を使用している場合に推奨事項を提供します。output_annotation_formatがcsvまたはtsvに設定されている場合、よりリッチなアノテーションデータサポート（スパン、メタデータ）のためにjsonの使用を提案します。

例

変更のプレビュー（ドライラン）

bash
$ potato migrate old_config.yaml --to-v2 --dry-run
 
Migration changes:
 
[textarea_to_multiline] Convert textarea.on to multiline format:
  - 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)
 
Dry run - no changes written.

移行して新しいファイルに保存

bash
$ potato migrate old_config.yaml --to-v2 --output migrated_config.yaml
 
Migration changes:
...
 
Wrote migrated config to migrated_config.yaml

クワイエットモード

bash
# Just output the migrated YAML, no status messages
$ potato migrate old_config.yaml --to-v2 --quiet > new_config.yaml

マイグレーションを使用するタイミング

以下の場合にマイグレーションツールの使用を検討してください：

  • 古いバージョンのPotatoからアップグレードする場合
  • サーバー起動時に非推奨の警告が表示される場合
  • 設定オプションが期待通りに動作しない場合
  • 設定が現在のベストプラクティスに従っていることを確認したい場合

トラブルシューティング

「設定ファイルが空です」

YAMLファイルが解析できないか空です。以下を確認してください：

  • ファイルが存在し読み取り可能である
  • YAML構文が有効である
  • ファイルに設定内容が含まれている

「設定ファイルのYAMLが無効です」

YAMLに構文エラーがあります。一般的な問題：

  • 不正なインデント
  • キーの後のコロンの欠落
  • 引用符で囲まれていない特殊文字

マイグレーション不要

「マイグレーション不要 - 設定は既に最新です」と表示された場合、設定は既に現在のv2形式を使用しています。

関連情報

実装の詳細については、ソースドキュメントを参照してください。