Skip to content

로컬 개발

개발 및 테스트를 위해 Potato를 로컬에 설치하고 실행합니다. pip 설치, 구성 설정, 서버 시작, 시작 시 흔히 생기는 문제의 디버깅을 다룹니다.

개발 및 테스트를 위해 로컬 컴퓨터에서 Potato를 실행합니다.

사전 요구 사항

  • Python 3.7 이상
  • pip 패키지 관리자
  • Git (선택 사항, 예제를 복제하는 경우)

설치

pip 사용 (권장)

bash
pip install potato-annotation

소스에서 설치

bash
git clone https://github.com/davidjurgens/potato.git
cd potato
pip install -e .

선택적 의존성과 함께 설치

bash
# Local speech-to-text and diarization for transcript projects
pip install "potato-annotation[transcribe]"
 
# Hosted model providers for AI support and active learning
pip install "potato-annotation[ai]"
 
# Everything except the multi-gigabyte server-side vision stack
pip install "potato-annotation[all]"

셸이 대괄호를 glob으로 해석하지 않도록 extra를 따옴표로 감싸십시오. all에는 의도적으로 vision이 빠져 있습니다. 이 그룹은 torch를 끌어오는데, 기본 기능 중 어느 것도 이를 필요로 하지 않기 때문입니다.

빠른 시작

1. 구성 파일 생성

config.yaml을 생성합니다.

yaml
annotation_task_name: "My First Annotation Task"
task_dir: "."
port: 8000
 
data_files:
  - data.json
 
item_properties:
  id_key: id
  text_key: text
 
annotation_schemes:
  - annotation_type: radio
    name: sentiment
    description: "What is the sentiment?"
    labels:
      - Positive
      - Negative
      - Neutral
 
output_annotation_dir: "annotations/"

task_dir은 다른 모든 상대 경로를 해석하는 기준이 되는 루트이며, Potato는 그 바깥의 파일을 읽지 않습니다. .으로 설정하면 구성 파일, 데이터 파일, 출력 디렉터리가 한 폴더에 모이므로 나중에 프로젝트를 서버로 그대로 옮길 수 있습니다.

2. 샘플 데이터 준비

data.json을 생성합니다.

json
[
  {"id": "1", "text": "I love this product!"},
  {"id": "2", "text": "This is terrible."},
  {"id": "3", "text": "It's okay, nothing special."}
]

3. 서버 시작

bash
potato start config.yaml

4. 인터페이스 접속

브라우저에서 http://localhost:8000을 엽니다.

개발 모드

디버그 모드

로그인을 완전히 건너뛰고 관리자 인증을 비활성화하므로, 계정을 만들지 않고도 주석 페이지에 들어갈 수 있습니다.

bash
potato start config.yaml --debug

배포된 서버에서는 절대 디버그 모드를 켜면 안 됩니다. 관리자 경로를 보호하는 검사가 꺼지기 때문입니다.

디버그 로깅

애플리케이션의 어느 쪽이 로그를 출력할지 선택합니다.

bash
potato start config.yaml --debug-log server

허용되는 값은 all, ui, server, none입니다. 주석 페이지가 이상하게 동작하면 ui를, 항목이 로드되지 않으면 server를 사용하십시오.

자세한 출력

모든 서버 활동을 확인합니다.

bash
potato start config.yaml --verbose

특정 단계로 이동

--debug를 켜 두면, 재시작할 때마다 동의 화면과 안내 화면을 클릭해 넘기는 대신 작업 중인 단계로 바로 이동할 수 있습니다.

bash
potato start config.yaml --debug --debug-phase annotation

디렉터리 구조

권장 프로젝트 레이아웃입니다.

text
my-annotation-project/
├── config.yaml           # Main configuration, inside task_dir
├── data/
│   ├── training.json     # Practice items for the training phase
│   └── main.json         # Annotation data
├── annotations/          # output_annotation_dir
├── media/                # media_directory, served at /media/
└── templates/            # site_dir, if you override the default templates

필요한 것은 config.yaml과 데이터 파일뿐입니다. Potato에는 자체 템플릿이 포함되어 있으므로, site_dir을 설정하고 templates/ 폴더를 추가하는 것은 그 템플릿을 교체할 때만 하면 됩니다. 주석 페이지를 렌더링할 특정 파일은 site_file로 지정합니다.

구성 테스트하기

구성 검증

시작에 시간을 쓰기 전에, 서버가 부팅 시 검사하는 것과 같은 방식으로 구성을 검사합니다.

bash
potato validate config.yaml

--strict를 추가하면 인식되지 않는 키 같은 경고가 출력만 되고 통과하는 대신 실행이 실패합니다.

미리보기 모드

구성이 선언하는 내용을 보여 주고, 전체 서버를 시작하지 않고 브라우저에서 렌더링합니다.

bash
potato preview config.yaml

스크린샷을 찍으려면 헤드리스 브라우저 extra인 pip install "potato-annotation[preview]"가 필요합니다.

bash
potato preview config.yaml --screenshot preview.png

일반적인 문제

포트가 이미 사용 중

bash
# Use a different port
potato start config.yaml -p 8080

또는 config.yaml에서 설정할 수 있으며, 이 값은 -p 플래그로 덮어씁니다.

yaml
port: 8080

데이터 파일을 찾을 수 없음

경로가 구성 파일 위치를 기준으로 한 상대 경로인지 확인하십시오.

yaml
# If data is in a subdirectory
data_files:
  - data/main.json

경로는 task_dir을 기준으로 해석되며 Potato는 그 바깥의 파일을 로드하지 않습니다. 따라서 컴퓨터의 다른 위치를 절대 경로로 가리키지 말고 데이터를 작업 디렉터리 아래로 옮기십시오.

권한 거부됨

파일 권한을 확인합니다.

bash
chmod 755 annotations/
chmod 644 data/*.json

로컬에서 여러 사용자

다중 사용자 시나리오를 테스트하려면 다음과 같이 합니다.

yaml
user_config:
  allow_all_users: true
 
login:
  type: url_direct
  url_argument: user_id

url_direct는 URL에서 사용자 이름을 바로 읽고 비밀번호를 묻지 않습니다. 따라서 브라우저 프로필 두 개를 열어 계정을 등록하지 않고도 두 사람으로 주석을 달 수 있습니다.

  • http://localhost:8000/?user_id=annotator1
  • http://localhost:8000/?user_id=annotator2

주석 초기화

Potato는 output_annotation_dir 아래에 주석자마다 디렉터리를 하나씩 만들고, 각 디렉터리에 그 사람의 user_state.json을 저장합니다.

bash
# Remove one annotator's work
rm -rf annotations/annotator1
 
# Or clear every annotator
rm -rf annotations/*
 
# Restart server
potato start config.yaml

사용자의 디렉터리를 삭제하면 답변과 함께 할당도 삭제되므로, 새로 실행할 때 항목이 처음부터 다시 할당됩니다.

환경 변수

환경 변수로 구성합니다.

bash
# Keeps sessions valid across restarts; required for OAuth
export POTATO_SECRET_KEY="$(python3 -c 'import secrets; print(secrets.token_hex(32))')"
 
# Fixes the shared admin key instead of letting Potato generate one per task
export POTATO_ADMIN_API_KEY="your-admin-key"
 
potato start config.yaml

POTATO_SECRET_KEY가 없으면 Potato는 시작할 때마다 무작위 서명 키를 생성하므로, 재시작할 때마다 모든 사용자가 로그아웃됩니다.

가상 환경과 함께 사용하기

venv

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

Conda

bash
conda create -n potato python=3.10
conda activate potato
pip install potato-annotation

IDE 통합

VS Code

구성 파일 지원을 위해 YAML 확장을 설치합니다.

json
// settings.json
{
  "yaml.schemas": {
    "https://potatoannotator.readthedocs.io/en/latest/schemas/potato-config.schema.json": "config.yaml"
  }
}

플레이그라운드에서 다운로드한 구성에는 # yaml-language-server: 줄에 이 스키마가 이미 지정되어 있으므로, 이 설정 없이도 편집기에서 검증됩니다.

PyCharm

실행 구성을 설정합니다.

  1. Add → Python
  2. 스크립트: potato
  3. 매개변수: start config.yaml
  4. 작업 디렉터리: 프로젝트 경로

다음 단계