Админ-панель

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

Доступ к панели

Аутентификация по ключу API

Доступ к панели закрыт общим ключом, который передаётся в заголовке X-API-Key, поэтому задайте его до того, как открывать сервер внешнему миру. Укажите ключ в YAML:

admin_api_key: "your-secure-api-key-here"

Potato берёт ключ из трёх мест в порядке приоритета: из ключа конфигурации admin_api_key, из переменной окружения POTATO_ADMIN_API_KEY и из автоматически сгенерированного ключа. Если вы ничего из этого не задали, Potato при запуске генерирует случайный ключ, выводит его в консоль и сохраняет в {task_dir}/admin_api_key.txt, чтобы он пережил перезапуск.

Панель открывается по адресу /admin; когда появится запрос, введите ключ API.

Способы аутентификации

1. Прямой переход. Откройте /admin и введите ключ API
2. Через заголовок. Передавайте в запросах заголовок X-API-Key
3. Режим отладки. При debug: true запросы с машины самого сервера открывают админ-страницы без ключа

Режим отладки открывает админ-страницы без ключа только для запросов с машины самого сервера, то есть с адреса loopback без заголовков X-Forwarded-For, X-Real-IP или Forwarded. Туннель или обратный прокси на той же машине, который не добавляет заголовок пересылки, делает любого клиента локальным, поэтому никогда не включайте отладку на развёрнутом сервере:

# Development only
debug: true  # Admin pages open without a key for requests from this machine

Вкладки панели

Вкладка Overview

Общие показатели задачи разметки:

• Total Users: число зарегистрированных разметчиков
• Active Users: разметчики, которые сейчас находятся в фазе разметки
• Total Annotations: общее число выполненных разметок
• Completion Percentage: доля объектов, у которых есть разметка
• Total Items: число объектов в наборе данных
• Working Time: общее время работы всех разметчиков
• Task Configuration: название задачи, лимиты назначения, стратегия и состояние режима отладки

Вкладка Annotators

Подробные сведения о каждом разметчике:

Вкладка показывает всю таблицу целиком и кнопку Refresh Data. Элементы сортировки и фильтрации находятся на вкладке Instances, а не здесь.

Вкладка Instances

Просмотр объектов разметки и управление ими:

Возможности:

• постраничный вывод (25, 50 или 100 на страницу);
• сортировка по числу разметок, проценту выполнения, разногласию, ID или среднему времени;
• сортировка по возрастанию или по убыванию;
• фильтр: все объекты, только завершённые или только незавершённые.

Помимо этих трёх, на панели есть вкладки Questions, Behavioral Analytics, Crowdsourcing, BWS Scoring, MACE, Embedding Visualization и Devices.

Вкладка Configuration

Меняйте настройки в реальном времени без перезапуска:

• Max Annotations per User: сколько объектов может разметить каждый пользователь (-1 означает без ограничений)
• Max Annotations per Item: ограничение числа разметок на объект (-1 означает без ограничений)
• Assignment Strategy: как объекты назначаются пользователям

Изменения сразу применяются к работающему серверу. Они хранятся в памяти и не записываются обратно в файл конфигурации, поэтому, если они должны пережить перезапуск, внесите их и в YAML.

Стратегии назначения

Вкладка Configuration предлагает шесть стратегий:

Ключ конфигурации называется assignment_strategy и находится на верхнем уровне. Всего Potato принимает двенадцать значений, среди них category_based, diversity_clustering, batch, priority, psychometric и model_review, которые задаются в YAML, а не с панели.

Аналитика времени

Панель собирает подробные данные о времени:

• Total Working Time: сумма всех сеансов разметки
• Average Time per Annotation: среднее время на объект
• Annotations per Hour: пропускная способность

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

Конфигурация

Базовая настройка

Панель включается одним ключом, потому что именно его проверяет форма входа:

# Enable admin dashboard
admin_api_key: "your-secure-api-key"

Полная конфигурация

Блока конфигурации admin в Potato нет. Настройки, влияющие на админ-часть, представляют собой ключи верхнего уровня, а три ключа назначения вкладка Configuration меняет во время работы:

admin_api_key: "your-secure-api-key"
 
# How long a session may sit idle before the server clears it.
# The clock restarts on every request, so it bounds inactivity,
# not the length of a shift. Default 480.
session_timeout_minutes: 480
 
# Editable from the Configuration tab while the server runs
assignment_strategy: least_annotated
max_annotations_per_user: 100
max_annotations_per_item: 3

У панели нет настроек интервала обновления, размера страницы или объёма экспорта. Размер страницы выбирается в выпадающем списке на вкладке Instances отдельно для каждого сеанса, а таблицы обновляются, когда вы нажимаете их кнопки Refresh.

Эндпоинты API

Админ-панель работает поверх эндпоинтов REST API. Каждый из них принимает заголовок X-API-Key. Обратите внимание на порядок в пути: /admin/api/..., а не /api/admin/....

Статистика

GET /admin/api/overview

Возвращает статистику пользователей, ход разметки и сводку конфигурации.

Разметчики

GET /admin/api/annotators
GET /admin/user_state/<user_id>

Список всех разметчиков с показателями времени и пропускной способности или подробное состояние одного пользователя.

Объекты

GET /admin/api/instances?page=1&page_size=25&sort_by=annotation_count&sort_order=desc&filter_completion=
GET /admin/item_state/<item_id>

Список объектов с постраничным выводом, сортировкой и фильтрацией или подробное состояние одного объекта. sort_by принимает annotation_count, completion_percentage, disagreement, id или average_time; filter_completion принимает completed, incomplete или пустое значение для всех объектов.

Конфигурация

GET /admin/api/config
POST /admin/api/config

Получение или изменение конфигурации задачи. Тело POST-запроса принимает max_annotations_per_user, max_annotations_per_item и assignment_strategy и отклоняет всё остальное.

Ход обучения

GET /admin/training/api/status
GET /admin/training/api/runs
GET /admin/training/api/runs/<run_id>

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

Активное обучение

GET /admin/active-learning/stats

Для каких схем есть обученная модель, на каком месте находится переключатель схем и записанные запуски обучения.

Функции мониторинга

Обнаружение подозрительной активности

Панель вычисляет для каждого разметчика оценку подозрительности по трём сигналам процесса:

• доля быстрых разметок, то есть выполненных быстрее чем за две секунды;
• доля объектов с минимальным взаимодействием;
• доля объектов, где первоначальный выбор так и не изменился.

Разметчики с оценкой выше 50% подсвечиваются. Оценка упорядочивает разметчиков для проверки и никого не классифицирует, потому что у быстрой работы бывают и невинные объяснения.

Метрики качества

Отслеживайте показатели качества разметки:

• согласованность разметчиков, через GET /admin/api/agreement;
• распределение времени на разметку;
• сбалансированность распределения меток, на вкладке Questions;
• долю принятых подсказок ИИ, если включена помощь ИИ.

Рекомендации по безопасности

Управление ключом API

Если держать ключ вне файла конфигурации, он не попадёт в систему контроля версий, а Potato подставляет ссылки ${VAR} в admin_api_key и secret_key:

# Use environment variables
admin_api_key: ${ADMIN_API_KEY}

export ADMIN_API_KEY="your-secure-key"

Potato также напрямую читает POTATO_ADMIN_API_KEY, так что экспорт этой переменной работает и без записи в конфигурации.

Контроль доступа

• Используйте надёжные уникальные ключи API
• Периодически меняйте ключи
• Не открывайте админ-эндпоинты публично
• В продакшене используйте HTTPS

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

Журнала аудита администрирования в Potato нет. Изменения конфигурации, экспорт и попытки доступа нигде надёжно не фиксируются, поэтому считайте ключ API единственным средством контроля доступа и ограничьте круг тех, у кого он есть. Единственная поверхность с аудитом представляет собой сервер MCP, который записывает каждый авторизованный вызов в файл, указанный в mcp.audit_log.

Пример конфигурации

annotation_task_name: "Sentiment Analysis"
task_dir: "."
port: 8000
 
# Admin dashboard
admin_api_key: ${ADMIN_API_KEY}
session_timeout_minutes: 480
 
# Data and annotation configuration
data_files:
  - "data/reviews.json"
 
item_properties:
  id_key: id
  text_key: text
 
annotation_schemes:
  - annotation_type: radio
    name: sentiment
    description: "How does this review read?"
    labels:
      - Positive
      - Negative
      - Neutral
 
# Assignment settings (editable from the Configuration tab)
assignment_strategy: least_annotated
max_annotations_per_user: 100
max_annotations_per_item: 3
 
output_annotation_dir: "output/"
export_annotation_format: jsonl
 
user_config:
  allow_all_users: true

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

Производительность

Большие наборы данных

Для наборов данных из тысяч объектов:

• пользуйтесь постраничным выводом на вкладке Instances, а не режимом по 100 объектов на страницу;
• загружайте объекты лениво с partial_loading вместо чтения всех файлов при запуске;
• рассмотрите базу данных в качестве хранилища для лучшей производительности.

Много разметчиков

Для задач с большим числом одновременных разметчиков:

• следите за ресурсами сервера;
• используйте базу данных в качестве хранилища для масштабируемости;
• ограничьте max_annotations_per_user, чтобы ни один разметчик не исчерпал очередь.

# For large-scale deployments
database:
  type: mysql
  host: localhost
  database: potato_db
  username: ${DB_USER}
  password: ${DB_PASSWORD}

Устранение неполадок

Не удаётся открыть панель

• Проверьте, что ключ API задан в конфигурации или в POTATO_ADMIN_API_KEY, либо прочитайте его из {task_dir}/admin_api_key.txt
• Проверьте, что адрес именно /admin
• Убедитесь, что ключ API совпадает в точности
• Поищите опечатки в конфигурации

Панель медленно загружается

• Уменьшите размер страницы на вкладке Instances
• Загружайте объекты лениво с partial_loading
• Рассмотрите базу данных в качестве хранилища
• Проверьте ресурсы сервера

Статистика не обновляется

Панель сама ничего не опрашивает, поэтому вы видите цифры на момент последней загрузки.

• Нажмите кнопку Refresh на вкладке, которую смотрите
• Перезагрузите страницу
• Проверьте консоль браузера на ошибки JavaScript

Дополнительные материалы

• Поведенческое отслеживание: подробное отслеживание взаимодействий
• Контроль качества: проверки внимательности и эталонные примеры
• Обзор API: эндпоинты админ-API

Подробности реализации см. в исходной документации.