Локальная разработка

Как установить и запустить Potato локально для разработки и тестирования: установка через pip, настройка конфигурации, запуск сервера и частые проблемы при старте.

Как запустить Potato на своей машине для разработки и тестирования.

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

Python 3.9 или новее
менеджер пакетов 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. 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

Режим разработки

Режим отладки

Режим отладки включает подробный журнал, отключает тайм-аут простоя сессии и открывает админ-страницы без ключа для запросов с вашей собственной машины. Страница входа остаётся, а --debug-phase (см. ниже) её пропускает:

bash

potato start config.yaml --debug

Никогда не включайте режим отладки на развёрнутом сервере. Туннель или обратный прокси на той же машине, который не добавляет заголовок пересылки, делает любого обратившегося локальным, а --debug-phase впускает каждого посетителя под одним и тем же debug_user. Potato с 2.8.2 по 2.11.0 отказывается запускаться в режиме отладки на адресе по умолчанию 0.0.0.0, поэтому в этих версиях добавьте --host 127.0.0.1.

Журнал отладки

Выберите, какая часть приложения пишет в журнал:

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

Для скриншотов нужно дополнение с headless-браузером, 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

Настройте конфигурацию запуска:

Add → Python
Скрипт: potato
Параметры: start config.yaml
Рабочий каталог: путь к вашему проекту

Что дальше

Основы конфигурации: все параметры конфигурации
Форматы данных: как устроены данные
Production-настройка: развёртывание для реальной работы