마이그레이션 CLI

Potato 구성 파일을 v1 형식에서 v2 형식으로 자동으로 마이그레이션합니다. 변경 사항을 디스크에 기록하기 전에 모두 미리 볼 수 있는 드라이런 모드를 포함합니다.

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에서 업그레이드하는 경우
서버를 시작할 때 지원 중단 경고가 표시되는 경우
구성 옵션이 예상대로 작동하지 않는 경우
구성이 현재 모범 사례를 따르도록 보장하려는 경우

문제 해결

"Configuration file is empty"

YAML 파일을 구문 분석할 수 없거나 비어 있습니다. 다음을 확인하십시오.

파일이 존재하고 읽을 수 있는지
YAML 구문이 유효한지
파일에 구성 콘텐츠가 포함되어 있는지

"Invalid YAML in configuration file"

YAML에 구문 오류가 있습니다. 일반적인 문제는 다음과 같습니다.

잘못된 들여쓰기
키 뒤에 콜론 누락
따옴표로 묶이지 않은 특수 문자

마이그레이션이 필요 없음

"No migrations needed - config is already up to date"가 표시되면 구성이 이미 현재 v2 형식을 사용하고 있는 것입니다.

더 읽어보기

v2의 새로운 기능 - v2 변경 사항 개요
구성 기초 - 현재 구성 형식

구현 세부 사항은 원본 문서를 참조하십시오.