Skip to content

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

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

С этим руководством вы пройдёте путь от свежей установки до разметки данных меньше чем за 5 минут. На этой странице показано, как написать задачу самостоятельно. Другой способ начать состоит в том, чтобы описать исследование агенту для программирования и поручить potato-skill спроектировать и собрать его. Этот путь описан на странице Быстрый старт с агентом для программирования.

Potato за пять шагов: установка, конфигурация, запуск сервера, разметка в браузере и экспортPotato за пять шагов

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

  • Python 3.9 или выше
  • Менеджер пакетов 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.11.1. Начиная с версии 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. Укажите файл с соответствующим расширением, и Potato выберет по нему способ чтения.

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/"
 
# Also write a periodic flat export, because the per-user state files are
# awkward to analyze. No exporter is named "json", so use "jsonl".
export_annotation_format: "jsonl"
 
# 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 занят, выберите другой с помощью -p 8001. Чтобы остановить сервер, нажмите Ctrl+C в терминале.

Быстрее для первого раза: добавьте --debug --debug-phase=annotation, чтобы пропустить страницы входа и согласия, пока вы экспериментируете: potato start config.yaml --debug --debug-phase=annotation. Тогда каждый посетитель входит под одним общим пользователем debug_user, поэтому запускайте так только на своём компьютере.

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 хранит полное состояние разметки этого пользователя. Чтобы получить сводный плоский файл по всем разметчикам, запустите CLI экспорта Potato, описанный в документации по экспорту. Команда python -m potato.export --list-formats выводит все зарегистрированные в нём форматы.

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

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

Частые вопросы

Вопросы ниже касаются установки Potato, запуска в Docker и проверки конфигурации до того, как её увидят разметчики.

Как установить Potato?

Установите Potato из PyPI командой pip install potato-annotation, на Python 3.9 или выше. Установка в виртуальное окружение отделяет зависимости Potato от системного Python, а potato --version подтверждает установку, выводя номер версии.

Можно ли запустить Potato в Docker?

Да. Potato публикует готовый образ ghcr.io/davidjurgens/potato в GitHub Container Registry. Папка проекта монтируется в контейнер в /app, а сервер внутри контейнера слушает порт 7860, поэтому один образ подходит для любой задачи. Задайте POTATO_SECRET_KEY, чтобы сессии разметчиков сохранялись после перезапуска. Полная команда docker run приведена в статье Развёртывание Potato на сервере.

Как проверить конфигурацию Potato до того, как её увидят разметчики?

Запустите potato validate config.yaml --strict. Эта команда проверяет конфигурацию так же, как сервер при запуске, и превращает предупреждения, например о нераспознанном ключе, в ошибки. Затем potato preview config.yaml показывает, что объявлено в конфигурации, и отображает интерфейс в браузере, так что вы видите задачу так, как её увидит разметчик, ещё до того, как кто-либо войдёт в систему.

Что дальше?

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

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