Skip to content

Быстрый старт

Запустите Potato меньше чем за 5 минут: установка через pip, конфигурация в YAML, запуск сервера и разметка первого датасета — без единой строки кода.

Запустите Potato всего за несколько шагов. С этим руководством вы начнёте размечать данные меньше чем за 5 минут.

На этой странице показано, как написать задачу самостоятельно. Другой способ начать — описать исследование агенту для программирования и поручить potato-skill спроектировать и собрать его: см. Быстрый старт с агентом для программирования.

Potato in five steps: install, configure, run the server, annotate in the browser, and exportPotato in five steps

Что понадобится

  • 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.9.0. Начиная с версии 2.9, её выводит и potato --version.

Создайте первый проект

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."}
]

Для data_files Potato также принимает .jsonl (по одному объекту JSON на строку), .csv и .tsv — просто укажите файл с соответствующим расширением.

3. Создайте конфигурацию

Создайте в каталоге проекта файл config.yaml:

Песочница путей: все относительные пути в конфигурации (например, data_files или output_annotation_dir) разрешаются относительно task_dir и должны оставаться внутри него. Пути, ведущие за пределы task_dir, отклоняются, чтобы исключить выход из каталога.

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. Вы увидите экран входа с единственным полем имя пользователя — введите что угодно (например, 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 хранит полное состояние разметки этого пользователя. Чтобы получить сводный плоский файл по всем разметчикам, используйте CLI экспорта Potato — подробности в документации по экспорту.

Частые проблемы при первом запуске

  • 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 либо смотрите закешированную вкладку. Перезапустите сервер и обновите страницу с очисткой кеша.

Что дальше?

Инструменты и утилиты

Когда освоитесь с основами, посмотрите эти полезные инструменты: