Требования Potato к серверу для вашего ИТ-отдела

Potato это самостоятельно размещаемое веб-приложение для исследований с разметкой. Один процесс Potato обслуживает одно исследование, хранит всю разметку в файлах и базах данных SQLite внутри папки исследования, и перед процессом ему нужен обратный прокси для HTTPS. Установка по умолчанию ничего не отправляет внешним сервисам, а данные покидают сервер только через возможности, которые включает конфигурация исследования.

Эта страница написана для тех, кто администрирует серверы в университете, больнице или компании. Исследователь, которому нужно разместить исследование, может отправить страницу без изменений вместе с папкой проекта и ответами на вопросы из следующего раздела. Страница Как выложить исследование Potato в сеть описывает маршруты, которыми исследователь может воспользоваться без ИТ-отдела.

Сведения от исследовательской группы

Исследовательская группа присылает папку проекта, которую Конструктор исследований экспортирует кнопкой Скачать проект (.zip). В папке лежат config.yaml, конфигурация исследования, и файлы данных, которые эта конфигурация называет. Вместе с папкой группа отвечает на такие вопросы:

• Сколько разметчиков участвуют, и входят ли они через учётные записи института или по именам пользователей, которые перечисляет исследователь?
• Когда исследование начинается и заканчивается?
• Содержат ли объекты или ответы персональные или чувствительные сведения, и по какому одобрению этического комитета идёт исследование?
• Использует ли конфигурация функции ИИ, которые отправляют объекты провайдеру моделей? Такие функции обозначают блоки вроде ai_support, chat_support и solo_mode в config.yaml.

Программное обеспечение

Potato это веб-приложение на Python, построенное на Flask. Проще всего установить опубликованный Docker-образ ghcr.io/davidjurgens/potato, собранный для linux/amd64 и linux/arm64. Образ занимает около 900 MB, запускает Python 3.11 под gunicorn от непривилегированного пользователя potato (uid 1000) и слушает порт 7860. Папка проекта монтируется в /app:

docker run -d --name potato-study --restart unless-stopped \
  -p 127.0.0.1:8000:7860 \
  -v /srv/potato/my-study:/app \
  -e POTATO_SECRET_KEY="$(openssl rand -hex 32)" \
  ghcr.io/davidjurgens/potato:2.14.0

Команда публикует исследование только на порту 8000 интерфейса loopback хоста. Тогда единственный вход это обратный прокси. Тег latest следует за веткой разработки Potato, а исследованию нужно закрепить тег версии. Сгенерируйте POTATO_SECRET_KEY один раз и сохраните значение, потому что новый ключ при каждом запуске разлогинивает всех разметчиков при каждом перезапуске. Контейнер отказывается стартовать, если /app недоступна для записи uid 1000. Запускайте контейнер с --user "$(id -u):$(id -g)" или передайте папку uid 1000. Теги образа и его переменные окружения описаны на странице Запуск Potato в Docker.

Без Docker Potato устанавливается из PyPI на Python 3.9 или новее командой pip install potato-annotation. Добавьте дополнение hosting для резервных копий и единого входа, а дополнение saml для входа через SAML, которое собирается с системной libxmlsec1. potato start config.yaml запускает сервер для разработки, который закрывает соединение после каждого ответа. Для разметчиков, работающих через интернет, запускайте Potato под gunicorn, как показывает страница Production-настройка, или поставьте обратный прокси перед potato start.

Процесс и число рабочих процессов

Potato держит пул объектов, очередь назначения и состояние каждого разметчика в памяти одного процесса. Второй рабочий процесс gunicorn или вторая реплика хранит отдельную копию всех трёх, раздаёт объекты, которые первый процесс уже назначил, и перезаписывает сохранения первого процесса. Поэтому образ отказывается стартовать при GUNICORN_WORKERS больше 1. Для большей параллельности поднимайте GUNICORN_THREADS с значения по умолчанию 8. По собственной документации Potato по Docker, восемь потоков рассчитаны на десятки одновременных разметчиков, какие бывают в типичном исследовании. Несколько исследований запускайте несколькими контейнерами, и у каждого контейнера должны быть своя папка и свой порт.

Размер сервера

Память растёт вместе с числом объектов. По измерениям Potato, на каждый объект приходится от 0,9 до 1,4 KB памяти, а сервер на эталонном датасете Potato занимал около 365 MB. potato deploy, собственная облачная команда Potato, на большинстве хостов выбирает машину с 1 или 2 vCPU и 2 GB памяти, и это разумный начальный размер.

Диск должен быть постоянным и доступным для записи, и на нём должно хватать места для файлов данных, медиафайлов, которые входят в объекты, и разметки. Контейнер, диск которого стирается при перезапуске, теряет всю разметку, если не включено встроенное резервное копирование, описанное ниже.

Сетевой доступ и HTTPS

Публикуйте Potato через обратный прокси, например nginx, Apache или Caddy. Прокси хранит сертификат TLS и пересылает запросы на порт контейнера. В интернет должны быть открыты только порт 443 и порт 80 для перенаправлений и продления сертификата. Страница Обратный прокси показывает, как обслуживать Potato под путём URL вроде https://host.example.edu/my-study/, через POTATO_PROXY_FIX=1 с заголовком X-Forwarded-Prefix или через POTATO_URL_PREFIX. Просмотрщики живых агентов передают данные через server-sent events. Если исследование использует эти просмотрщики, отключите буферизацию прокси для пути /api/.

GET /health не требует аутентификации и возвращает {"status": "ok"}, когда сервер готов, и 503, пока сервер ещё загружает данные. Направьте на этот маршрут балансировщик нагрузки или проверку мониторинга.

По умолчанию Potato не нужен исходящий сетевой доступ. Скрипты, таблицы стилей и шрифты, которые загружают браузеры разметчиков, приходят с самого сервера, а страница Изолированное и автономное развёртывание перечисляет, как Potato держит установку по умолчанию автономной. Исходящий доступ нужен только возможностям, которые включает конфигурация:

• Функции ИИ обращаются к конечной точке модели, которую называет конфигурация, если эта точка не является локальным сервером моделей вроде Ollama.
• Резервные копии записываются в датасет Hugging Face или бакет S3, которые называет конфигурация.
• Единый вход обращается к провайдеру удостоверений.
• Удалённые источники данных читают из бакета или базы данных, которые называет конфигурация.
• Если объекты ссылаются на медиафайлы по URL, браузер разметчика загружает медиафайлы по этому URL.

Файлы, которые записывает Potato

Potato записывает всё в папку исследования:

Таким образом, одна папка содержит всё исследование. output_annotation_dir это параметр в config.yaml, а Конструктор исследований задаёт для него значение output.

Резервные копии

Ночная резервная копия папки проекта покрывает файлы разметки и список учётных записей. Два файла SQLite копируйте командой резервного копирования самой SQLite, а не как файлы, потому что файловая копия базы данных в режиме WAL может оказаться повреждённой или не содержать недавних записей:

sqlite3 /srv/potato/my-study/project.sqlite ".backup /backups/my-study/project.sqlite"

Встроенное резервное копирование Potato каждые пять минут копирует выходные файлы разметки и снимки баз данных в S3-совместимый бакет или в приватный датасет Hugging Face. При запуске оно восстанавливает данные из бакета, если диск пуст, и никогда не перезаписывает разметку, уже лежащую на диске. Блок ниже отправляет копию в объектное хранилище университета. Добавьте блок в config.yaml исследования и задайте POTATO_S3_ACCESS_KEY_ID и POTATO_S3_SECRET_ACCESS_KEY в окружении контейнера:

backup:
  schedule_minutes: 5
  restore_on_boot: true
  sinks:
    - type: s3
      bucket: research-backups
      prefix: potato/my-study
      endpoint_url: https://s3.example.edu

Опубликованный образ включает клиенты резервного копирования. Для установки через pip нужно дополнение hosting.

Способы входа

Potato поддерживает несколько способов входа для разметчиков, они задаются в config.yaml:

Пароли хешируются PBKDF2-SHA256 со 100 000 итераций и солью для каждого пользователя. Забытый пароль сбрасывается по одноразовой ссылке, которую Potato показывает на экране, а писем Potato не отправляет. За прокси, который завершает TLS, задайте sp_base_url для SAML равным публичному адресу, иначе ответ провайдера удостоверений не пройдёт проверку назначения в Potato. Конфигурацию каждого способа описывают страницы SSO и OAuth, Управление паролями и Интеграция с краудсорсингом.

Доступ администратора

Админ-панель по адресу /admin показывает прогресс, согласованность и ответы каждого разметчика, а также скачивает результаты. Панель открывается по ключу администратора. Задайте ключ через POTATO_ADMIN_API_KEY или позвольте Potato сгенерировать admin_api_key.txt в папке проекта при первом использовании, и передайте ключ исследователю по каналу, которому доверяет ваше учреждение. На любом сервере держите debug: false в config.yaml, потому что режим отладки открывает админ-страницы без ключа для запросов, которые выглядят локальными, а прокси на той же машине может сделать локальным каждый запрос.

Защита данных

Potato размещается самостоятельно, поэтому разметка, список учётных записей и объекты остаются на сервере, который вы запускаете. В Potato нет аналитики и отчётов об использовании, и установка по умолчанию не делает исходящих соединений. Данные покидают сервер только через возможности, перечисленные в разделе Сетевой доступ и HTTPS, и конфигурация исследования должна включить каждую из них и назвать место назначения.

Сверьте с одобрением этического комитета три момента:

• Файлы разметки называют каждого разметчика по имени пользователя, поэтому имена пользователей в виде адресов электронной почты помещают адреса в данные.
• Страницы анкет в исследовании могут собирать персональные сведения, и ответы лежат в тех же файлах каждого разметчика.
• Если конфигурация отправляет объекты провайдеру размещаемых моделей, объекты покидают сервер на условиях этого провайдера.

Когда исследование заканчивается, исследовательская группа скачивает результаты из админ-панели. Договоритесь с группой, как долго хранится копия на сервере, и после этой даты удалите папку проекта и бакет резервных копий.

Что почитать дальше

• Запуск Potato в Docker, о тегах образа, переменных окружения и владельце файлов
• Production-настройка, о gunicorn, nginx, Apache и Docker Compose
• Обратный прокси, о том, как обслуживать Potato под путём URL
• Изолированное и автономное развёртывание, для сетей без исходящего доступа
• Как выложить исследование Potato в сеть, сторона исследователя в том же процессе