ML Service

Назначение

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

• Кластеризация текстов (выделение тем: кредитные карты, вклады, мобильное приложение и т.д.).
• Мультилейбл классификация по темам.
• Определение тональности (положительно / нейтрально / отрицательно).

Запуск API

uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

HealthCheck

curl http://localhost:8000/health

API

• POST /predict

  {"data":[{"id":1,"text":"Карта понравилась, но приложение лагает"}]}

Отправка теста

curl -s -X POST http://localhost:8000/predict \
  -H "Content-Type: application/json" \
  -d '{"data":[{"id":1,"text":"Отличное обслуживание, но ужасное мобильное приложение."}]}'

Документация пайплайна: тематическая кластеризация и мультилейбл-классификация

Ниже — расширенная документация по обучающему и инференс-пайплайнам (BERTopic + zero-shot классификация на эмбеддингах), а также управлению артефактами через MLflow.

1. Цель и общая схема

Цель — выделять темы в отзывах клиентов банка и присваивать отзывам бизнес-классы (мультилейбл).

• Этап обучения (train):
  • очистка и нормализация текстов (лемматизация RU, унификация англицизмов);
  • вычисление эмбеддингов с учётом длинных отзывов (чанкинг + пуллинг);
  • кластеризация BERTopic (KMeans/HDBSCAN) по эмбеддингам; улучшение названий тем (MMR);
  • zero-shot маппинг тем → бизнес-классы через косинус к прототипам классов;
  • zero-shot top‑k классов на уровне документа;
  • экспорт артефактов (модель, эмбеддер, векторы классов, отчёты) и логирование в MLflow.
• Этап инференса (predict):
  • быстрый zero-shot top‑k классификатор для новых отзывов (эмбеддер + косинус к векторам классов).

2. Структура проекта

banking-topics-mlflow/
  MLproject
  conda.yaml
  src/
    final_classes.py        # словарь бизнес‑классов (multi‑prototype)
    utils_text.py           # нормализация/лемматизация, softmax_cos
    encode.py               # чанкинг + пуллинг эмбеддингов
    train_bertopic_and_export.py
    predict.py

Актуальные артефакты сохраняются в artifacts/latest/.

3. Формат входных данных

Вход: JSON со списком отзывов. Поддерживается корневой ключ reviews. Минимальные поля: id, title, text.

{
  "reviews": [
    {"id": 123, "title": "Заголовок", "text": "...", "rating": "5", "city": ""},
    {"id": 124, "title": "UnionPay", "text": "..."}
  ]
}

4. Предобработка

В src/utils_text.py выполняются:

• normalize_anglicisms: унификация терминов (кэшбэк, UnionPay, push, Ozon Premium и т.д.);
• normalize_ru (если доступен pymorphy2): лемматизация, удаление предлогов/союзов/частиц, стоп-слов и чисел; латиница и бренды сохраняются;
• prepare_text(title, text): сборка и очистка текста для витрины названий тем.

Используются два представления текста:

• docs_ctx — «сырые» (title + text),
• docs_clean — очищенные (леммы) для именования тем.

5. Эмбеддинги и чанкинг длинных отзывов

В src/encode.py:

1. Разбиение строки на куски длиной до max_chars (по умолчанию 1000 символов).
2. Кодирование каждого кусочка моделью SentenceTransformer (по умолчанию BAAI/bge-m3).
3. Агрегация кусочков (pooling): max (по умолчанию), mean или attn_len (взвешивание по длине).
4. L2‑нормализация итогового вектора.

6. Тематическая модель (BERTopic)

• Vectorizer (для витрины названий тем):
  • CountVectorizer(ngram_range=(1,3), min_df=3, max_df=0.4, token_pattern=...)
  • доменные стоп‑слова (банк, карта, приложение и пр.) для удаления «воды».
• Кластеризация:
  • по умолчанию KMeans через аргумент hdbscan_model=KMeans(...) (особенность API BERTopic 0.17.x);
  • альтернатива: HDBSCAN; опционально reduce_outliers для перераспределения класса -1.
• Улучшение представлений тем:
  • update_topics(..., representation_model=MaximalMarginalRelevance(diversity=0.6)) снижает дубли/однокоренные повторы в названиях.

Результаты: topic_info (список тем), doc_info (тема для документа).

7. Маппинг тем → бизнес‑классы (zero‑shot)

В src/final_classes.py задан расширенный словарь: для каждого класса — набор фраз‑прототипов.

1. Для каждого класса считаются вектора прототипов (эмбеддер) и усредняются ⇒ вектор класса.
2. Для каждой темы кодируются top‑слова темы ⇒ вектор темы.
3. Считаются косинусы «тема ↔ класс», берутся top‑k классов для темы.
4. Для удобства вероятности аппроксимируются softmax_cos по косинусам (температура τ = 0.07).

8. Документ‑уровень: zero‑shot мультилейбл

Для каждого документа берутся его эмбеддинги и косинусы к векторам классов ⇒ top‑k классов на документ. Это быстрый и простой классификатор, используемый на проде.

9. Артефакты обучения

Скрипт src/train_bertopic_and_export.py сохраняет в artifacts/latest:

• bertopic_model/ — обученная модель BERTopic;
• embedder/ — сохранённый SentenceTransformer;
• class_vecs.npy + class_names.json — матрица векторов классов и имена;
• bertopic_outputs.xlsx — отчёт с листами:
  • topics_summary — перечень тем BERTopic;
  • topics_top3_classes — маппинг тем в бизнес‑классы (top‑3);
  • documents_topk — top‑k классов по документу + тема BERTopic;
  • suspect_topics — темы с низким сходством к top‑1 классу (ниже порога);
  • dist_docs, dist_topics — распределения.

Все артефакты логируются в MLflow.

10. Запуск обучения (MLflow)

mlflow run . -e train -P data_path="merged_reviews_filtered.json"

Ключевые параметры (см. MLproject):

• embedder_model — модель эмбеддингов (напр., BAAI/bge-m3);
• pooling ∈ {max, mean, attn_len};
• max_chars — размер чанка для длинных отзывов;
• use_kmeans, n_clusters, min_topic_size — настройка кластеризации;
• topk_classes — число классов на документ;
• suspect_topic_sim — порог отбора «сомнительных» тем.

11. Запуск инференса (MLflow)

mlflow run . -e predict \
  -P model_dir="artifacts/latest" \
  -P input_path="new_reviews.json" \
  -P output_path="predictions.xlsx" \
  -P topk=3 \
  -P pooling=max \
  -P max_chars=1000

Выход: Excel/CSV с колонками id, top1_class/top1_sim, top2_class/top2_sim, top3_class/top3_sim.

12. Обновление бизнес‑классов

Для изменения доменной таксономии:

1. Отредактировать src/final_classes.py (добавить/изменить фразы‑прототипы).
2. Перезапустить обучение (train) — пересчитаются векторы классов и отчёты.

13. Производительность и качество

• Скорость инференса: вычисление эмбеддинга + косинус к ~10–20 классам (миллисекунды на CPU).
• Длинные тексты: увеличение max_chars уменьшает число чанков (быстрее, но грубее).
• Ускорение: конверсия эмбеддера в ONNX (onnxruntime) и/или квантование.
• Качество: расширять final_classes.py (синонимы, негативные формулировки), подбирать pooling и температуру τ в softmax_cos.
• Пороговая мультилейбл‑селекция: вместо top‑k можно отбирать классы по порогу косинуса.

14. Воспроизводимость

• conda.yaml фиксирует версии Python/пакетов (например, bertopic==0.17.3).
• Фиксированные сиды (например, random_state=42 для KMeans).
• MLflow логирует параметры и артефакты.

15. Типичные вопросы/ошибки

• Передача KMeans: в BERTopic 0.17.x кластеризатор передаётся как hdbscan_model=KMeans(...).
• Предупреждение TOKENIZERS_PARALLELISM: нормально; можно отключить через os.environ["TOKENIZERS_PARALLELISM"] = "false".
• Малоинформативные названия тем: повышайте min_df, дополняйте стоп‑слова, используйте MMR (diversity≈0.6).
• Много -1 при HDBSCAN: используйте KMeans или reduce_outliers.
• Обновление классов на проде: после правок final_classes.py перезапустить train для обновления class_vecs.npy.

16. Где смотреть результаты

Основной отчёт: artifacts/latest/bertopic_outputs.xlsx. Полезные листы:

• topics_top3_classes — соответствие тем бизнес‑классам;
• documents_topk — top‑k классов на документ (для ручной валидации);
• suspect_topics — кандидаты на ревизию стоп‑слов/лейблов.

Итог: обучение даёт интерпретируемые темы и артефакты, а прод‑инференс работает быстро за счёт zero‑shot мультилейбл‑классификации на эмбеддингах.