Как выложить исследование Potato в сеть

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

Развёртывание исследования означает перенос задачи Potato, которую вы создали, с вашего компьютера на сервер, то есть на компьютер, который всегда включён и подключён к интернету. Разметчики открывают задачу в веб-браузере откуда угодно, а Potato сохраняет каждый ответ на сервере по мере работы. Предпросмотр в Конструкторе исследований запускает Potato прямо в вашем браузере, и до этой копии никто другой добраться не может. Исследованию, созданному в Конструкторе, всё равно нужен один из маршрутов ниже.

Каждый маршрут начинается с одной и той же папки проекта. В Конструкторе исследований кнопка Скачать проект (.zip) сохраняет config.yaml (файл, который описывает вашу задачу), файл с примером данных и README. В файле с примером лежат три объекта-заглушки. Замените его своими объектами до развёртывания, в формате, который описывает страница Форматы данных.

Выбор маршрута

Маршруты различаются тем, кто выполняет техническую работу, сколько стоит сервер и как долго исследование может оставаться в сети. Стоимость ниже взята из прайс-листов хостов и собственных оценок Potato на 2026-11-04, а сроки ожидания приблизительные и не измерялись:

Если вы не уверены, начните с ИТ-отдела. Сервер внутри вашего учреждения держит данные на оборудовании, которым учреждение уже управляет, а ИТ-отдел может взять на себя обновления безопасности и резервные копии.

Обратитесь в ИТ-отдел или службу исследовательских вычислений

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

1. Скачайте проект из Конструктора исследований и замените файл с примером данных своими объектами.
2. Отправьте ИТ-отделу папку проекта и ссылку на страницу Требования Potato к серверу для вашего ИТ-отдела.
3. Сообщите команде, кто ваши разметчики, сколько их будет и как долго идёт исследование.
4. Скажите, как разметчики должны входить. Коллеги с учётными записями института могут использовать единый вход (SSO), то есть вход, который ваш институт уже поддерживает, а внешние разметчики могут входить по именам пользователей, которые вы перечислите.
5. Скажите, содержат ли объекты или ответы персональные или чувствительные сведения, и назовите одобрение этического комитета, по которому идёт исследование.
6. Попросите у команды веб-адрес исследования, ключ администратора, который открывает админ-панель Potato, и план резервного копирования и передачи вам данных, когда исследование закончится.

Когда адрес придёт, пройдите по разделу Перед приглашением разметчиков, прежде чем кому-либо его отправлять.

Нажмите кнопку развёртывания, которую подготовил коллега

Кнопка развёртывания это ссылка на странице репозитория с кодом, которая создаёт копию задачи Potato на серверах хостинговой компании целиком через формы в вашем браузере. Коллега, который работает с git и терминалом, делает кнопку один раз, из репозитория с папкой вашего проекта, командой potato deploy button. Этому коллеге стоит отправить страницу Запуск Potato локально или в облаке.

Кнопка работает с тремя хостами, и платят там по-разному:

• Render запускает исследование на бесплатном тарифе без платёжного метода. Бесплатная служба Render засыпает после 15 минут без посетителей и просыпается около минуты, когда приходит следующий разметчик.
• Heroku берёт $7 в месяц за сервер, который создаёт кнопка. Чтобы создать приложение, Heroku требует подтверждённую учётную запись, обычно через банковскую карту.
• AWS запускает сервер Lightsail за $12 в месяц. Кнопка AWS читает задачу из публичного репозитория, поэтому она подходит только для объектов, которые могут быть публичными.

Render и Heroku стирают диск сервера при каждом перезапуске сервера. Поэтому кнопка каждые пять минут копирует разметку в приватный датасет на Hugging Face, сайте для обмена данными и моделями, и копирует разметку обратно при каждом запуске сервера. Название этого датасета вы указываете при нажатии, и датасет принадлежит вашей учётной записи.

Перед нажатием подготовьте три вещи:

• учётную запись на хосте, Render или Heroku;
• бесплатную учётную запись Hugging Face с токеном доступа, у которого есть право записи, созданным на huggingface.co/settings/tokens; и
• доступ к репозиторию, если он приватный. Для приватного репозитория Heroku просит привязать вашу учётную запись GitHub.

Затем разверните:

1. Нажмите кнопку в README репозитория и войдите на хост.
2. Задайте приложению имя. Имя станет частью веб-адреса исследования.
3. В POTATO_BACKUP_HF_REPO введите название датасета из вашего имени пользователя на Hugging Face и названия исследования, например your-username/my-study-annotations. Если такого названия ещё нет, Potato создаёт датасет и делает его приватным.
4. Вставьте свой токен Hugging Face в HF_TOKEN. Все остальные поля оставьте с теми значениями, которые подставила кнопка.
5. Запустите развёртывание и дождитесь, пока хост сообщит, что приложение работает. Откройте веб-адрес, который показывает хост.
6. Найдите ключ администратора, пароль, который хост сгенерировал при развёртывании. В Heroku ключ это запись POTATO_ADMIN_API_KEY на вкладке Settings приложения, а в Render та же запись находится на странице Environment службы.
7. Откройте адрес исследования с /admin в конце и вставьте ключ администратора, чтобы открыть админ-панель.

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

Поделитесь ссылкой со своего компьютера

Ваш собственный компьютер может обслуживать пилот в течение вечера. Разметчики открывают временную веб-ссылку, разметка попадает в папку вашего проекта, а ссылка перестаёт работать, когда вы закрываете команду. Для этого маршрута нужен терминал, программа для ввода команд. На Mac это Terminal (в Программах, затем в Утилитах), а в Windows это PowerShell (найдите «PowerShell» в меню «Пуск»).

1. Установите Python 3.9 или новее с python.org/downloads. В Windows скачивается менеджер установки Python. На Mac скачивается установщик macOS.

2. Откройте терминал и установите Potato. На Mac введите:

   bashКопировать

   python3 -m pip install potato-annotation

   В Windows введите:

   powershellКопировать

   py -m pip install potato-annotation

3. Распакуйте проект, скачанный из Конструктора исследований. На Mac дважды щёлкните файл .zip. В Windows щёлкните файл правой кнопкой и выберите Извлечь все. Замените файл с примером данных своими объектами.

4. Перейдите в терминале в папку проекта и запустите Potato. Имя папки ниже приведено для примера, поэтому используйте имя своей папки. На Mac:

   bashКопировать

   cd ~/Downloads/my-task
   python3 -m potato start config.yaml

   В Windows:

   powershellКопировать

   cd $HOME\Downloads\my-task
   py -m potato start config.yaml

5. Откройте http://localhost:8000 в браузере. Только ваш компьютер может добраться до этого адреса. Чтобы остановить Potato, нажмите Ctrl-C в терминале.

6. Чтобы пустить других людей, установите cloudflared, бесплатную программу Cloudflare, которой не нужна учётная запись. На Mac с Homebrew выполните brew install cloudflared. В Windows скачайте установщик для Windows со страницы загрузок Cloudflare.

7. Запустите potato share вместо potato start:

   bashКопировать

   python3 -m potato share config.yaml

   В Windows введите py -m potato share config.yaml. Potato печатает, кто сможет войти, и спрашивает подтверждение, прежде чем что-либо публиковать. Введите y, и Potato напечатает ссылку https://, которую нужно отправить разметчикам.

Ссылка работает только пока выполняется команда. Закрытие терминала, переход компьютера в спящий режим или смена сети обрывают ссылку, а новый запуск печатает новую. Некоторые университетские сети блокируют ссылки trycloudflare.com, которые создаёт cloudflared. Если разметчик сообщает о заблокированной ссылке, potato share config.yaml --backend tailscale использует вместо этого Tailscale. Tailscale требует бесплатной учётной записи. Если potato share сообщает No tunnel backend found, Potato не нашёл cloudflared на вашем компьютере, а в сообщении перечислены команды установки.

Страница Установка описывает виртуальные окружения и необязательные возможности, а страница Запуск Potato локально или в облаке подробнее описывает potato share.

Арендуйте сервер одной командой

potato deploy up арендует сервер у облачной компании, получает сертификат HTTPS (замок в адресной строке браузера), загружает папку вашего проекта, запускает исследование и печатает веб-адрес. Команде нужна настройка терминала из шагов 1–3 выше, учётная запись у облачной компании и токен API, ключ вроде пароля, который позволяет программе действовать от имени вашей учётной записи. Руководство для каждого хоста описывает учётную запись и токен с самого начала:

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

potato deploy up config.yaml --provider aws --dry-run
potato deploy up config.yaml --provider aws

Собственная кнопка Hugging Face Duplicate this Space копирует Space в браузере, но копия Space с Potato сохраняет настройки резервного копирования прежнего владельца и теряет его секреты. Разворачивайте Space с Potato вместо этого командой potato deploy up --provider huggingface.

Перед приглашением разметчиков

Когда у исследования появился веб-адрес, пройдите по этому списку один раз, каким бы маршрутом вы ни шли:

• Решите, кто может входить. Самая простая закрытая схема это список имён пользователей. В Конструкторе исследований выключите Пускать всех пользователей и добавьте каждого разметчика в Допущенные пользователи. Каждый разметчик из списка выбирает пароль при регистрации при первом посещении, а Potato отказывает всем, кого в списке нет. Отправьте каждому разметчику его имя пользователя напрямую, потому что первый, кто зарегистрирует имя из списка, становится владельцем этой учётной записи. Об учётных записях института читайте в разделе SSO и OAuth, а о краудворкерах в разделе Интеграция с краудсорсингом. Если Пускать всех пользователей включён, учётную запись может создать любой, кто нашёл адрес. Оставляйте эту настройку для публичных демонстраций.
• Знайте, где лежит разметка. Potato сохраняет ответы каждого разметчика по мере его работы в файл user_state.json внутри отдельной папки на каждого разметчика. Эти папки лежат в выходной папке, которую называет конфигурация и которую Конструктор исследований называет output. На вашем компьютере эта папка находится внутри папки проекта. При развёртывании кнопкой копия, переживающая перезапуск, лежит в датасете Hugging Face. На арендованном сервере potato deploy pull скачивает эту папку. На сервере учреждения спросите ИТ-отдел, как делается резервное копирование.
• Проверьте во втором браузере. Откройте адрес исследования в приватном окне, это Incognito в Chrome, Private Window в Safari и Firefox и InPrivate в Edge. Добавьте в список имя пользователя вроде pilot-test, зарегистрируйтесь под этим именем и ответьте на три объекта. Закройте окно, войдите снова и убедитесь, что ответы на месте. Затем откройте админ-панель и убедитесь, что тестовый разметчик в ней виден. Если разметчики могут работать с телефонов, проверьте адрес и на телефоне.
• Держите ключ администратора в секрете. Ключ администратора открывает админ-панель по адресу /admin. Панель показывает ответы каждого разметчика. На вашем компьютере Potato сохраняет ключ в admin_api_key.txt в папке проекта при первом открытии /admin.
• Напишите приглашение. Отправьте каждому разметчику адрес, имя пользователя, сколько времени занимает задача и к кому обращаться, если что-то пойдёт не так.

Получение результатов

Админ-панель скачивает результаты на ваш компьютер без терминала. Откройте /admin, введите ключ администратора и выберите Publish Dataset. В поле Target выберите Local archive, в Data format укажите CSV для таблицы и нажмите Publish. Когда архив будет готов, нажмите Download archive.

В архиве лежат ответы каждого разметчика, объекты и метки, объединённые голосованием большинства. README в архиве сообщает число меток и согласованность между разметчиками. Имена разметчиков заменяются на A1, A2 и так далее, если вы не снимете флажок Anonymize annotators. Ответы анкет в архив не попадают, пока вы не отметите Include survey / phase responses, потому что ответы анкет могут содержать персональные сведения.

Из терминала python -m potato.export записывает ту же разметку в папку в любом из форматов экспорта Potato:

python -m potato.export --config config.yaml --format csv --output results

На сервере, созданном командой potato deploy up, potato deploy pull config.yaml скачивает всё, что сервер собрал, включая базы данных.

Завершение исследования, чтобы сервер перестал стоить денег

Скачайте результаты, прежде чем что-либо удалять, и откройте скачанное, чтобы проверить, что ответы последнего разметчика на месте. Затем выключите сервер так, как требует ваш маршрут:

• Ваш компьютер. Нажмите Ctrl-C в терминале. Ничего не списывалось.
• ИТ-отдел. Сообщите команде, что исследование закончилось, попросите копию выходной папки и спросите, как долго копия на сервере будет храниться.
• Кнопка развёртывания. В Heroku удалите приложение на вкладке Settings приложения, в Render удалите службу на странице Settings службы. В датасете Hugging Face лежит полная копия разметки. Когда резервная копия больше не нужна, удалите датасет на странице его настроек.
• Арендованный сервер. Выполните potato deploy pull config.yaml, проверьте скачанную папку, а затем выполните potato deploy destroy config.yaml. Potato отказывается уничтожать сервер, данные которого ни разу не скачивались.

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

Как создать сервер Potato для моего исследования?

Сервер Potato создаётся запуском вашей задачи на компьютере, до которого разметчики добираются по веб-адресу. Задачу может запустить ИТ-отдел вашего учреждения, коллега может подготовить кнопку развёртывания, которую вы нажмёте, potato share может обслужить пилот с вашего ноутбука, а potato deploy up может арендовать для вас сервер. Таблица в разделе Выбор маршрута сравнивает маршруты по стоимости и по объёму работы в терминале.

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

Установите Python 3.9 или новее с python.org, затем введите py -m pip install potato-annotation в PowerShell в Windows или python3 -m pip install potato-annotation в Terminal на Mac. После установки py -m potato start config.yaml в Windows или python3 -m potato start config.yaml на Mac запускает задачу. Страница Установка описывает необязательные возможности.

Термины на этой странице

• Сервер. Сервер это компьютер, который всегда включён и подключён к интернету, чтобы другие люди могли пользоваться программой на нём через веб-браузер.
• URL, или веб-адрес. URL это адрес, который разметчики вводят или по которому переходят, например https://my-study.example.edu. Домен это именная часть адреса, здесь my-study.example.edu.
• HTTPS. HTTPS шифрует всё между браузером разметчика и сервером, включая пароли и ответы. Для адреса HTTPS браузеры показывают замок.
• Порт. Порт это пронумерованная точка входа на компьютере. Potato слушает порт 8000, если конфигурация не называет другой порт, и локальный адрес http://localhost:8000 заканчивается этим номером.
• Терминал. Терминал это программа для ввода команд, на Mac она называется Terminal, а в Windows PowerShell.
• Ключ администратора. Ключ администратора это длинный пароль, который открывает админ-панель Potato.
• Токен API. Токен API это ключ вроде пароля, который позволяет программе, например команде развёртывания Potato, действовать от имени вашей учётной записи у хостинговой компании.

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

• Требования Potato к серверу для вашего ИТ-отдела, страница, которую нужно отправить ИТ-отделу
• Запуск Potato локально или в облаке, о каждом хосте, кнопках развёртывания и резервных копиях
• Развёртывание сервера разметки, как выбрать хост для длинного исследования
• Запуск Potato в Docker, для серверов, которые запускают контейнеры
• Админ-панель, чтобы следить за ходом, пока идёт исследование