Skip to content

빠른 시작

5분 안에 Potato를 실행하세요. pip로 설치하고, YAML 설정을 작성하고, 서버를 시작한 다음 첫 데이터셋을 주석 처리합니다 — 코딩이 필요 없습니다.

몇 단계만으로 Potato를 실행하세요. 이 가이드를 따르면 5분 안에 데이터 주석 작업을 시작할 수 있습니다.

사전 준비

  • Python 3.7 이상
  • pip 패키지 관리자
  • 터미널

설치

Potato가 시스템 Python과 충돌하지 않도록 가상 환경에 설치하는 것을 권장합니다.

bash
python -m venv potato-env
source potato-env/bin/activate   # Windows: potato-env\Scripts\activate
pip install potato-annotation

설치를 확인합니다.

bash
python -c "import potato; print(potato.__version__)"

2.4.4와 같은 버전이 출력되어야 합니다. Potato에는 potato --version 플래그가 없으므로, 이 Python 한 줄 명령이 표준 확인 방법입니다.

첫 프로젝트 만들기

1. 프로젝트 디렉터리 만들기

bash
mkdir my-annotation-task
cd my-annotation-task

2. 데이터 파일 만들기

data 폴더를 만들고 그 안에 data.json이라는 파일을 만듭니다.

bash
mkdir data
json
[
  {"id": "1", "text": "I love this product! It's amazing."},
  {"id": "2", "text": "This is the worst experience ever."},
  {"id": "3", "text": "It's okay, nothing special."}
]

Potato는 data_files에 .jsonl(한 줄에 JSON 객체 하나), .csv, .tsv도 지원합니다 — 해당 확장자를 가진 파일을 지정하기만 하면 됩니다.

3. 설정 만들기

프로젝트 디렉터리에 config.yaml이라는 파일을 만듭니다.

경로 샌드박스: 설정 안의 상대 경로(data_files나 output_annotation_dir 등)는 task_dir을 기준으로 해석되며 그 안에 있어야 합니다. task_dir 바깥으로 해석되는 경로는 경로 탐색(path traversal)을 방지하기 위해 거부됩니다.

yaml
annotation_task_name: "Sentiment Analysis"
 
# All relative paths below are resolved against task_dir.
task_dir: "."
 
# Data configuration
data_files:
  - "data/data.json"
 
# Tell Potato which fields in each record to use.
# id_key = unique identifier; text_key = the text shown to annotators.
item_properties:
  id_key: id
  text_key: text
 
# Where per-user annotation state is stored (relative to task_dir).
output_annotation_dir: "annotation_output/"
export_annotation_format: "json"
 
# Annotation scheme
annotation_schemes:
  - annotation_type: radio
    name: sentiment
    description: "What is the sentiment of this text?"   # required for radio schemes
    labels:
      - Positive
      - Negative
      - Neutral
 
# Skip password authentication so anyone can log in with just a username.
require_password: false

팁: 전체 서버를 시작하지 않고도 Preview CLI를 사용해 설정을 검증할 수 있습니다. 주석 작업을 시작하기 전에 오타를 잡아내는 가장 빠른 방법입니다.

4. 서버 시작하기

bash
potato start config.yaml -p 8000

동등한 전체 형식:

bash
python -m potato start config.yaml -p 8000

포트 8000이 이미 사용 중이면 다른 포트를 선택하세요: potato start config.yaml -p 8001.

서버를 중지하려면 터미널에서 Ctrl+C를 누릅니다.

더 빠른 첫 실행: 실험하는 동안 로그인 화면을 완전히 건너뛰려면 --debug를 추가하세요: potato start config.yaml --debug.

5. 브라우저 열기

http://localhost:8000으로 이동합니다. username 필드 하나만 있는 로그인 화면이 나타납니다 — 아무 값(예: alice)이나 입력하고 Continue를 클릭하세요. 이제 주석 작업을 시작합니다.

라벨을 선택하고 Next를 클릭할 때마다 주석이 자동으로 저장됩니다. 별도의 "저장" 버튼은 없습니다.

주석이 저장되는 위치

Potato는 주석을 다는 동안 사용자별 상태를 기록합니다.

text
my-annotation-task/
├── config.yaml
├── data/
│   └── data.json
└── annotation_output/              # created automatically
    └── alice/
        └── user_state.json         # one folder per username

user_state.json에는 해당 사용자의 전체 주석 상태가 담겨 있습니다. 모든 주석자의 결과를 하나로 합친 평탄한 파일을 만들려면 Potato의 export CLI를 사용하세요 — 자세한 내용은 export 문서를 참고하세요.

첫 실행 시 흔한 문제

  • Address already in use — 포트 8000이 사용 중입니다. -p 8001(또는 비어 있는 포트)을 사용하세요.
  • KeyError: 'description' — radio(또는 유사한) 스킴에 필수 description 필드가 없습니다. 모든 스킴에는 하나가 필요합니다.
  • Path ... is outside the task directory — data_files나 output_annotation_dir 경로가 task_dir을 벗어납니다. 모든 것을 프로젝트 폴더 안에 두거나, 해당 경로들을 포함하는 절대 경로로 task_dir을 설정하세요.
  • 로그인 페이지에 비밀번호 필드가 표시됨 — require_password: false를 빠뜨렸거나, 캐시된 브라우저 탭을 보고 있는 것입니다. 서버를 재시작하고 강력 새로고침을 하세요.

다음 단계

도구 및 유틸리티

기본기에 익숙해지면 다음의 유용한 도구들을 확인해 보세요.