Texts Annotation

Streamlit-приложение для разметки текстов с учетом требований:

• Мульти-лейбл классификация с ответами yes/no по каждому кандидату (чекбокс).
• Разметка минимум двумя разметчиками (счетчик хранится в БД).
• Отбор topK классов по вероятностям без порогов.
• Сохранение в БД версии модели, которая сформировала кандидатов.
• Автодамп БД на диск и восстановление при перезапуске.
• Заглушка для обучения новой версии модели на накопленных данных.
• YAML-словарь интентов с описанием, сложностью и кластером (разбит по кластерам по файлам).

Запуск локально

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
streamlit run app.py

Запуск в Docker

docker build -t texts-annotation .
docker run --rm -p 8501:8501 -v $PWD/data:/app/data texts-annotation

Переменные окружения

• TEXTS_DB_PATH — путь до SQLite БД (по умолчанию data/db/app.db).
• TEXTS_DB_DUMP_PATH — путь до дампа (по умолчанию data/dumps/backup.sql).
• TEXTS_DB_DUMP_INTERVAL_SEC — интервал автодампа в секундах (по умолчанию 60).
• TEXTS_TOP_K — размер topK (по умолчанию 5).
• TEXTS_MARGIN_THRESHOLD — порог для margin_error_rate.
• TEXTS_MIN_ANNOTATORS — минимальное число разметчиков на текст (по умолчанию 2).
• TEXTS_INTENTS_PATH — путь к папке с YAML-словарями интентов (по умолчанию data/intents).
• TEXTS_ANNOTATORS_PATH — путь к YAML конфигу разметчиков (по умолчанию data/annotators.yaml).
• TEXTS_IMPORT_CSV_PATH — путь к CSV файлу с входящими текстами (по умолчанию data/requests.csv).
• TEXTS_ADMIN_PASSWORD — пароль для панели администратора (по умолчанию admin123).

Интерфейс разметчика

Основной интерфейс для разметки текстов (app.py).

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

• Авто-переход к следующему тексту — после сохранения разметки автоматически загружается следующий текст.
• Пропуск текстов — кнопка "Пропустить" позволяет отложить сложный текст на потом без сохранения разметки.
• Просмотр пропущенных — чекбокс "Показать пропущенные тексты" для возврата к отложенным текстам.
• Нумерация в списке текстов — в выпадающем списке показывается позиция текста (например, 3/12), чтобы легче ориентироваться.
• Переход по пропущенным — при разметке или повторном пропуске в режиме "Показать пропущенные" выделяется следующий доступный текст.
• Активный кластер — разметчик выбирает кластер из доступных ему, тексты и интенты показываются в рамках выбранного кластера.
• Примеры интентов — каждый пример отображается отдельной строкой в списке.
• Чекбоксы для разметки — каждый кандидат представлен чекбоксом (отмечен = yes, не отмечен = no). По умолчанию все не отмечены.
• Дополнительные метки вне topK — выбор в этом списке сбрасывается при переходе к другому тексту.

Вход разметчика и URL-параметры

• Параметр ?user=... больше не выполняет автоматический вход — он только подставляет имя разметчика в форму.
• Параметр ?cluster=... применяется только после успешного входа и только если кластер доступен выбранному разметчику.

Панель администратора

Доступна по адресу /admin (выбрать в боковом меню Streamlit). Требует ввода пароля администратора.

Обзор и прогресс

• Обзор — общая статистика: всего текстов, размечено, ожидают разметки.
• Прогресс по кластерам — процент выполнения разметки по каждому кластеру.

Статистика разметчиков

• Статистика разметчиков — количество аннотаций, распределение yes/no/unsure, первая и последняя аннотация.
• Активность по дням — график аннотаций по дням для каждого разметчика.
• Активность по часам — график аннотаций по часам за выбранный день, сводка по разметчикам (часы активности, начало/конец работы).

Качество модели по интентам

Метрики для понимания, какие интенты модель предсказывает хорошо, а какие — плохо:

• Top-1 Precision — когда интент на 1 месте, как часто разметчик ставит "yes".
• Missed Rate — когда интент на 2-N месте И top-1 отвергнут (no), как часто этот интент получает "yes" (высокий missed rate = модель недооценивает интент).

Выделены проблемные интенты:

• Низкий Top-1 Precision — модель уверена, но ошибается.
• Высокий Missed Rate — модель недооценивает этот интент.

Статистика по интентам (общая)

• Precision, unsure rate, частота появления в topK, средняя вероятность и ранг.
• Фильтрация по кластеру и минимальному количеству голосов.
• Сортировка по различным метрикам.

Прочее

• Дополнительные метки вне topK — интенты, которые разметчики добавляют вручную (модель не предложила).
• Разногласия — случаи, когда разметчики дали разные ответы на один и тот же текст+интент.
• Управление версиями модели — создание новой версии модели и версии данных (заглушка).
• Экспорт данных — выгрузка аннотаций и статистики интентов в CSV.

Структура БД

• texts — тексты, метаданные (язык, кластеры), версия данных.
• candidates — topK кандидаты + вероятность и версия модели.
• annotations — выборы разметчиков (включая метки вне topK).
• intents — справочник интентов и их кластеров.
• model_versions — версии моделей.
• settings — текущие версии и настройки.
• skipped_texts — пропущенные тексты (text_id, annotator, timestamp).

Формат CSV импорта

CSV должен содержать столбец request_text и столбцы с именами интентов, где значения — это скоры от 0 до 1 (или от 0 до 10, тогда они будут нормализованы до 0..1).

Пример заголовка:

request_text,intent_a,intent_b,intent_c

Формат YAML конфигурации разметчиков

annotators:
  - name: annotator_1
    password: demo123
    cluster: cash_withdrawal
  - name: annotator_2
    password: demo456
    clusters: [cash_withdrawal, card_delivery]