Кастомный пайплайн BERTopic: как кластеризовать тексты и получить интерпретируемые темы с помощью LLM

Меня зовут Антон и я занимаюсь задачами NLP в компании Ростелеком Информационные технологии.

Если вам приходилось разбирать большие массивы текстов: отзывов, обращений в поддержку или комментариев, то вы знаете, насколько это трудоемкий процесс.

В статье я покажу, как автоматизировать этот процесс с помощью пайплайна BERTopic: от эмбеддингов и кластеризации до интерпретации тем. Особое внимание ^[1] уделим тому, как встроить локальную LLM в пайплайн и получить человекочитаемые названия тем.

Навигация

• Кластеризация текстов: задача и архитектура решения ^[2]

• Выбор и настройка среды ^[3]

• Выбор и подготовка датасета ^[4]

• Интеграция в пайплайн эмбеддинг-модели ^[5]

• Уменьшение размерности ^[6]

• Кластеризация с помощью HDBSCAN ^[7]

• Интерпретация кластеров: c-TF-IDF, LLM и KeyBERTInspired ^[8]

  • Токенизация (Vectorizer) ^[9]

  • Выделение ключевых слов с помощью c-TF-IDF ^[10]

  • Интерпретация тем (Representation Models) ^[11]

• Сборка пайплайна BERTopic ^[12]

• Визуализация результатов кластеризации ^[13]

• Оценка качества кластеризации ^[14]

  • Покрытие кластеризации ^[15]

  • Согласованность тем Topic Coherence ^[16]

  • Разнообразие тем Topic Diversity ^[17]

  • Устойчивость Stability (ARI) ^[18]

• Анализ тем для определенного отзыва ^[19]

• Оптимизация структуры тем: объединение и работа с шумом ^[20]

• Заключение ^[21]

Кластеризация текстов: задача и архитектура решения

Кластеризация текстов — это задача группировки текстов таким образом, чтобы тексты внутри одного кластера были семантически близки, а тексты из разных кластеров — существенно различались. В отличие от задачи классификации, количество тем заранее неизвестно, и их разметка отсутствует.

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

После очистки и векторизации текстов недостаточно сразу запустить алгоритм кластеризации. Возникает несколько ключевых проблем.

Во-первых, эмбеддинги, получаемые современными моделями векторизации, имеют высокую размерность (512, 784 и более), что приводит к проблемам с расстояниями в многомерном пространстве и усложняет работу алгоритмов кластеризации.

Во-вторых, в реальных данных количество кластеров заранее неизвестно, а распределение текстов по ним может быть неравномерным.

И, наконец, сформировав кластеры, необходимо сделать их интерпретируемыми для человека.

Чтобы решить эти проблемы я предлагаю построить следующий пайплайн кластеризации:

1. Подготовка и очистка исходных данных.

2. Создание контекстных эмбеддингов моделью FRIDA.

3. Снижение размерности векторов методом UMAP.

4. Иерархическая плотностная кластеризация алгоритмом HDBSCAN.

5. Интерпретация тем с помощью c-TF-IDF и LLM.

Для реализации этого пайплайна я использовал библиотеку BERTopic, которая объединяет в едином интерфейсе процесс векторизации текстов, снижения размерности, кластеризацию и инструменты для интерпретации полученных тем. BERTopic не является «черным ящиком»: все шаги можно конфигурировать, что позволяет гибко адаптировать пайплайн под конкретную задачу.

Выбор и настройка среды

Весь код, представленный в статье, я запускал в среде выполнения ноутбуков на платформе Kaggle.

Kaggle предоставляет пользователям доступ к GPU с лимитом до 30 часов в неделю.

В качестве GPU я использовал Tesla P100 с 16 GB VRAM. Как альтернативу можно использовать 2 GPU T4.

Конфигурация «железа» платформе была следующая: 32 GB RAM; CPU Intel(R) Xeon(R) 2.00GHz, 2 ядра, 4 потока; 60 GB HDD. В среде использовался Python 3.12.12.

На платформе Kaggle бо́льшая часть фреймворков и библиотек для машинного обучения ^[22] уже установлена, тем не менее дополнительно потребуются следующие зависимости:

pip install -q torch==2.9.0+cu126 torchvision==0.24.0+cu126 torchaudio==2.9.0+cu126 --extra-index-url https://download.pytorch.org/whl/cu126
pip install -q bertopic hdbscan umap-learn pymorphy3 stop-words gensim
pip install -q --upgrade transformers

Итоговые версии ключевых библиотек и фреймворков у меня получились следующими:

bertopic                                 0.17.4
gensim                                   4.4.0
hdbscan                                  0.8.41
numpy                                    2.0.2
pandas                                   2.3.3
pymorphy3                                2.0.6
pymorphy3-dicts-ru                       2.4.417150.4580142
scipy                                    1.16.3
sentence-transformers                    5.2.3
stop-words                               2025.11.4
torch                                    2.9.0+cu126
transformers                             5.3.0
umap-learn                               0.5.11

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

import os
import random
import torch
import transformers
import pandas as pd
import numpy as np
import re
import string
import warnings
import matplotlib.pyplot as plt

from sentence_transformers import SentenceTransformer
from tqdm import tqdm
from bertopic import BERTopic
from sklearn.feature_extraction.text import CountVectorizer
from hdbscan import HDBSCAN
from umap import UMAP
from sklearn.decomposition import PCA
from pymorphy3 import MorphAnalyzer
from scipy.cluster import hierarchy as sch
from transformers import AutoTokenizer, AutoModelForCausalLM, pipeline
from stop_words import get_stop_words
from bertopic.representation import TextGeneration, KeyBERTInspired
from bertopic.backend import BaseEmbedder
from bertopic.vectorizers import ClassTfidfTransformer
from matplotlib.axes import Axes
from typing import List, Optional, Iterable, Tuple
from collections import Counter
from sklearn.metrics.pairwise import cosine_similarity
from sklearn.metrics import adjusted_rand_score
from gensim.models.coherencemodel import CoherenceModel
from gensim.corpora import Dictionary

Зафиксируем seed и настройки отображения графиков и датафреймов:

SEED = 42

transformers.set_seed(SEED)
random.seed(SEED)
os.environ["PYTHONHASHSEED"] = str(SEED)
np.random.seed(SEED)
torch.manual_seed(SEED)
torch.cuda.manual_seed(SEED)
torch.backends.cudnn.deterministic = True
torch.backends.cudnn.benchmark = True

warnings.filterwarnings('ignore')

tqdm.pandas()

pd.set_option('display.max_rows', 1000)
pd.set_option('display.max_columns', 1000)
pd.set_option('display.width', 1000)
pd.set_option('display.expand_frame_repr', False)
pd.set_option('max_colwidth', 1000)

plt.style.use('ggplot')

Выбор и подготовка датасета

В качестве исходных данных для кластеризации я использовал датасет Reviews Dataset — корпус текстов на русском и казахском языках, распространяемый по лицензии MIT license.

Корпус содержит отзывы на 17 видов пользовательских товаров: смартфонов, парфюмерии, часов и т.д. Разметки по темам внутри товаров нет, что делает этот датасет подходящим для демонстрации пайплайна кластеризации.

Я заранее скачал csv-файл из репозитория и загрузил его в датасет в своем профиле на Kaggle. После создания собственного датасета, файл с отзывами будет доступен в ноутбуке по пути:

/kaggle/input/datasets/[Ваш_ник]/[Имя_датасета]/kaspi_reviews.csv

Содержимое датасета и его размер:

df = pd.read_csv(data_path) 
.fillna("") 
.drop(["Unnamed: 0"], axis=1)

print("Размер исходного датасета:", df.shape)

Размер исходного датасета: (119048, 6)

Пользователи пишут отзывы в основном на русском и казахском языках

Больше всего отзывов в датасете представлено в категории «Смартфоны».

Для демонстрации работы пайплайна я выбрал 6 000 случайных отрицательных отзывов (столбец «minus») в категории «Смартфоны», провел их очистку, удалил дубликаты и очень короткие отзывы (короче 30 символов):

def clean_text(text: str) -> str:
    """Очистка текста от HTML-тегов, ссылок, смайлов,
    хэштегов, эмодзи, лишних пробелов.
    
    @param text: исходный текст
    @return: очищенный текст
    """
    if not isinstance(text, str):
        return ""
    text = re.sub(r'httpS+|www.S+', ' ', text)
    text = re.sub(r'<.*?>', ' ', text)
    emoji_pattern = re.compile(
        "["
        "U0001F600-U0001F64F"
        "U0001F300-U0001F5FF"
        "U0001F680-U0001F6FF"
        "U0001F700-U0001F77F"
        "U0001F780-U0001F7FF"
        "U0001F800-U0001F8FF"
        "U0001F900-U0001F9FF"
        "U0001FA00-U0001FA6F"
        "U0001FA70-U0001FAFF"
        "U00002702-U000027B0"
        "U000024C2-U0001F251"
        "]+",
        flags=re.UNICODE
    )
    text = emoji_pattern.sub(r'', text)
    text = re.sub(r'#S+', ' ', text)
    text = re.sub(r'[:;=8][-~]?[)D(Pp]', ' ', text)
    text = re.sub(r's+', ' ', text).strip()
    return text

def create_sample_dataset(
    df: pd.DataFrame,
    n: int = 6_000,
    min_len: int = 30
) -> pd.DataFrame:
    """Формирование датасета для кластеризации.
    
    @param df: исходный датасет
    @param n: размер подвыборки
    @param min_len: минимальная длина отзыва
    @return: сформированный датасет
    """
    df = df[
        (df["category"] == "smartphones") 
        & (df["language"] == "russian") 
        & (df["minus"] != "")
    ]

    df_sample = df 
    .sample(n=6_000, random_state=SEED) 
    .reset_index(drop=True)

    df_sample["clean_minus"] = df_sample["minus"].apply(clean_text)
    
    df_sample = df_sample 
    .drop_duplicates(subset=["clean_minus"]) 
    .reset_index(drop=True)[["minus", "clean_minus"]]

    return df_sample[df_sample["clean_minus"].str.len() > min_len]

df_sample = create_sample_dataset(df=df)

В результате получилось 3 168 уникальных текстов.

Интеграция в пайплайн эмбеддинг-модели

В качестве эмбеддинг-модели для создания контекстных эмбеддингов я выбрал FRIDA от AI Forever. Модель построена на энкодерной части FRED-T5, предобучена на русском и английском языках и хорошо подходит для задач семантического поиска и кластеризации.

На момент написания статьи FRIDA входит в топ-5 моделей бенчмарка MTEB для русского языка и занимает лидирующее место в задаче кластеризации.

Для интеграции модели в пайплайн BERTopic я использовал небольшой класс-обертку:

class FRIDAEmbedderWithPrefix(BaseEmbedder):
    """Эмбеддер на основе модели FRIDA
    с использованием префиксного промпта.
    
    Класс оборачивает SentenceTransformer 
    и добавляет использование prompt_name.
    """
    def __init__(
        self,
        model_name: str = "ai-forever/FRIDA",
        device: str = "cuda:0"
    ) -> None:
        """Инициализация эмбеддера.
        
        @param model_name: название или путь к модели
        @param device: устройство для инференса 
        """
        self.prompt_name = "categorize_topic"
        self.batch_size = 16
        self.model = SentenceTransformer(
            model_name_or_path=model_name,
            device=device
        )

    def embed(
        self,
        documents: List[str],
        verbose: bool = True
    ) -> np.ndarray:
        """Построение эмбеддингов для списка документов.
        
        @param documents: список текстов
        @param verbose: отображать ли прогресс-бар
        @return: эмбеддинги
        """
        embeddings = self.model.encode(
            documents,
            prompt_name=self.prompt_name,
            show_progress_bar=verbose,
            batch_size=self.batch_size
        )
        return embeddings

Этот класс решает две задачи: позволяет передать кастомную эмбеддинг-модель в BERTopic и добавляет использование префикса «categorize_topic», который рекомендован для FRIDA в задаче кластеризации.

BERTopic ожидает наличие метода embed(), через который вызывается процесс векторизации в пайплайне.

Размерность эмбеддингов датасета после процесса векторизации:

sent_model = FRIDAEmbedderWithPrefix()
embeddings = sent_model.embed(df_sample["clean_minus"])
print(f"Размерность векторизованного датасета: {embeddings.shape}")

Размерность векторизованного датасета: (3168, 1536)

Алгоритмы кластеризации плохо работают с такими высокими размерностями векторов из-за эффекта «проклятия размерности». Расстояния становятся менее информативными, плотность распределения искажается, а вычислительная сложность растёт.

Уменьшение размерности

Для снижения размерности в машинном обучении существуют различные методы: метод главных компонент PCA (Principal Component Analysis), t-SNE (t-distributed Stochastic Neighbor Embedding), UMAP (Uniform Manifold Approximation and Projection).

PCA — это линейный метод, он хуже работает с нелинейной структурой, характерной для эмбеддингов.

t-SNE отлично визуализирует кластеры, но плохо масштабируется и хуже сохраняет глобальную структуру.

UMAP сочетает преимущества обоих подходов: он быстрее t-SNE, лучше масштабируется и сохраняет как локальную, так и глобальную структуру данных.

Я использовал алгоритм UMAP.

Определим UMAP-модель для снижения размерности эмбеддингов:

umap_model = UMAP(
    n_neighbors=15,
    n_components=2,
    min_dist=0.0,
    metric="cosine",
    random_state=SEED,
    transform_seed=SEED,
    n_jobs=-1
)

Основные параметры модели:

• n_neighbors=15 — количество ближайших соседей, учитываемое при построении графа;

• n_components=2 — размерность целевого пространства;

• min_dist=0.0 — минимальная дистанция между точками в низкоразмерном пространстве;

• metric=«cosine» — метрика расстояния в исходном пространстве;

• random_state — воспроизводимость процесса обучения модели;

• transform_seed — воспроизводимость процесса применения модели к новым данным;

• n_jobs=-1 — для задействования всех ядер CPU.

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

Визуализации эмбеддингов на scatter plot для методов UMAP и PCA:

def plot_2d_embs(
    embs: np.ndarray,
    file_name: str,
    title: str,
    folder_path: str = exp_results_path
) -> None:
    """Построение 2D-визуализации эмбеддингов.
    
    @param embs: матрица эмбеддингов размерности (n_samples, 2)
    @param file_name: имя файла для сохранения графика (без расширения)
    @param title: заголовок графика
    @param folder_path: имя корневого каталога 
    """
    plt.figure(figsize=(16, 12))
    plt.scatter(
        embs[:, 0],
        embs[:, 1],
        s=5,
        alpha=0.6
    )
    plt.title(title)
    plt.xlabel("Component 1")
    plt.ylabel("Component 2")
    plt.savefig(
        f'{folder_path}/{file_name}.png',
        dpi=300,
        bbox_inches='tight'
    )
    plt.show()

embeddings_umap_2d = umap_model.fit_transform(embeddings)
plot_2d_embs(embs=embeddings_umap_2d, file_name="only_map", title="UMAP")
print(f"Размерность векторов после применения UMAP: {embeddings_umap_2d.shape}")

Размерность векторов после применения UMAP: (3168, 2)

pca = PCA(n_components=2, random_state=SEED)
embeddings_pca_2d = pca.fit_transform(embeddings)
plot_2d_embs(embs=embeddings_pca_2d, file_name="pca_map", title="PCA")

На графике UMAP-проекции эмбеддингов видно, что появляются компактные группы точек, видны локальные плотности, структура становится более «кластероподобной».

В свою очередь PCA-проекция эмбеддингов представляет более равномерное распределение точек, структура выглядит «размытой», явно выделенные плотные области отсутствуют.

Кластеризация с помощью HDBSCAN

После снижения размерности с помощью UMAP мы получаем компактное представление эмбеддингов. Следующий шаг — автоматическое выделение тематических групп, для которого я предлагаю использовать плотностный иерархический алгоритм кластеризации HDBSCAN.

Почему именно HDBSCAN, а не K-Means?

Алгоритм K-Means требует заранее задавать число кластеров, предполагает кластеры сферической формы и не учитывает шум. В задачах кластеризации текстов это ограничение критично, так как данные имеют сложную и неравномерную структуру, могут содержат выбросы.

HDBSCAN строит иерархию кластеров на основе плотности от небольших плотных групп к более крупным. Для каждого кластера оценивается устойчивость (stability): чем дольше кластер сохраняется при изменении плотности, тем он значимее.

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

Это хорошо подходит для текстов, где кластеры могут сильно различаться по размеру и плотности.

Для начала работы с алгоритмом HDBSCAN определим модель:

hdbscan_model = HDBSCAN(
    min_cluster_size=15,
    min_samples=5,
    metric="euclidean",
    cluster_selection_method="eom",
    prediction_data=False,
    gen_min_span_tree=True
)

Назначение параметров алгоритма:

• min_cluster_size=15 — минимальный размер кластера;

• min_samples=5 — параметр плотности (сколько соседей нужно точке, чтобы считаться «плотной»);

• metric=”euclidean” — метрика расстояния в пространстве эмбеддингов;

• cluster_selection_method=”eom” — метод выбора кластеров на основе их устойчивости;

• prediction_data=False — сохранять ли данные для последующего отнесения новых точек к кластерам;

• gen_min_span_tree=True — строить ли минимальное остовное дерево (полезно для анализа и визуализации структуры данных).

Запускаем процесс кластеризации:

cluster_labels = hdbscan_model.fit_predict(embeddings_2d)
n_clusters = len(set(cluster_labels)) - (1 if -1 in cluster_labels else 0)

print(f"Количество найденных кластеров: {n_clusters}")
print(f"Уникальные метки: {[int(item) for item in set(cluster_labels)]}")

Количество найденных кластеров: 45

Уникальные метки: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, -1]

Визуализируем и раскрасим полученные кластеры:

plt.figure(figsize=(16, 12))

scatter = plt.scatter(
    embeddings_2d[:, 0],
    embeddings_2d[:, 1],
    c=cluster_labels,
    cmap="tab20",
    s=5,
    alpha=0.7
)

plt.colorbar(scatter, label="Cluster")
plt.title("HDBSCAN with UMAP")
plt.xlabel("Component 1")
plt.ylabel("Component 2")
plt.show()

Плотные области окрасились в различные цвета — это и есть выделенные алгоритмом HDBSCAN кластеры.

При использовании HDBSCAN часть текстов может не попасть ни в один из выделенных кластеров. Такие объекты помечаются как шум (индекс кластера -1). Это происходит, если текст слишком уникален, находится на границе нескольких кластеров или относится к редкому кластеру с недостаточной плотностью.

В некоторых случаях шум можно кластеризовать отдельно: выделить тексты из шумового кластера и повторно применить алгоритм только к ним.

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

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

Иерархию кластеров HDBSCAN можно визуализировать с помощью дерева:

fig, ax = plt.subplots(figsize=(15, 10))
hdbscan_model.condensed_tree_.plot(axis=ax, log_size=True)

Каждая ветвь дерева соответствует кластеру на определенном уровне плотности. Длинные ветви отражают более устойчивые кластеры (существующие в широком диапазоне плотностей), короткие ветви — это менее устойчивые структуры, которые могут исчезать при небольшом изменении параметров плотности. Такая иерархия позволяет анализировать устойчивость кластеров и понимать структуру данных при разных уровнях плотности, что особенно важно для неоднородных текстовых данных.

Связка UMAP и HDBSCAN хорошо работает на текстовых данных, поскольку UMAP сохраняет локальную структуру пространства эмбеддингов при понижении размерности, а HDBSCAN выделяет плотные и устойчивые кластеры, автоматически отделяя шум. Эта комбинация алгоритмов широко используется в задачах кластеризации текстов и лежит в основе многих современных пайплайнов, включая BERTopic.

Интерпретация кластеров: c-TF-IDF, LLM и KeyBERTInspired

После этапа кластеризации возникает главный практический вопрос: как понять, о чём получившиеся кластеры?

Алгоритмы UMAP и HDBSCAN работают с эмбеддингами и формируют группы текстов, но сами по себе они не дают человекочитаемого описания темы.

Для решения этой задачи BERTopic использует последовательный многоступенчатый механизм интерпретации тем (третий этап опционален):

1. Vectorizer — токенизация и формирование словаря из n-грамм.

2. c-TF-IDF — вычисление важности ключевых слов, характеризующих тему.

3. Representation models: LLM для генерации человекочитаемого названия темы на основе ключевых слов и репрезентативных документов, KeyBERTInspired — дополнительное семантическое выделения ключевых слов.

Токенизация (Vectorizer)

Сначала тексты внутри каждого кластера необходимо разбить на токены. Для этого я использую CountVectorizer с кастомным токенизатором LemmaTokenizer:

class LemmaTokenizer:
    """Токенизатор с лемматизацией.
    
    Преобразует текст в список лемм,
    используя морфологический анализатор для русского языка.
    """
    def __init__(self) -> None:
        """Инициализация морфологического анализатора."""
        self.morph = MorphAnalyzer()

    def __call__(self, doc: str) -> List[str]:
        """Токенизация и лемматизация текста.
        
        @param doc: входной текст для обработки
        @return: список лемм
        """
        tokens = re.findall(r'[w]+', doc)
        lemmas = [self.morph.parse(t)[0].normal_form for t in tokens]
        return lemmas

Для формирования списка стоп-слов я добавил функцию get_lemmatized_stopwords(), которая объединяет стандартные и пользовательские стоп-слова, после чего приводит их к нормальной форме:

def get_lemmatized_stopwords(
    custom_words: Optional[Iterable[str]] = None
) -> List[str]:
    """Получение списка лемматизированных стоп-слов.
    Объединяет стандартные стоп-слова с пользовательскими,
    после чего приводит лемматизирует их.
    
    @param custom_words: итерируемый набор пользовательских стоп-слов
    @return: список уникальных лемматизированных стоп-слов
    """
    ru_stopwords = set(get_stop_words('russian'))
    if custom_words:
        ru_stopwords.update(custom_words)
    morph = MorphAnalyzer()
    lemmatized_stopwords = {morph.parse(w)[0].normal_form for w in ru_stopwords}
    return list(lemmatized_stopwords)

Определение vectorizer_model:

vectorizer_model=CountVectorizer(
    ngram_range=(1, 2),
    tokenizer=LemmaTokenizer(),
    stop_words=stop_words_lemmatized,
    min_df=3,
)

В данной конфигурации vectorizer_model выполняются три операции:

1. Лемматизация. Кастомный токенизатор LemmaTokenizer приводит слова к нормальной форме.

2. Генерация n-грамм. Параметр ngram_range=(1,2) означает, что в словарь будут включены как отдельные слова, так и биграммы (например, «батарея», «качество фото»).

3. Фильтрация по частоте и удаление стоп-слов. Термы, встречающиеся реже трёх раз (min_df=3), исключаются. Стоп-слова удаляются из словаря.

В результате vectorizer_model формирует матрицу «кластер × терм», которая затем используется для вычисления важности слов внутри тем.

Выделение ключевых слов с помощью c-TF-IDF

Следующий шагом вычисляется class-based TF-IDF (c-TF-IDF). Идея алгоритма следующая: все тексты внутри кластера объединяются в один «большой документ», затем считается TF-IDF между этими «документами-кластерами».

Этот подход позволяет выявлять слова и биграммы, которые часто встречаются внутри конкретного кластера и редко — в других, что делает их характерными для темы. Другими словами, алгоритм c-TF-IDF превращает кластер в интерпретируемую тему, описанную набором ключевых слов и биграмм.

Для улучшенного взвешивания слов в кластерах разного размера я применил модификацию c-TF-IDF на основе алгоритма BM25:

ctfidf_model = ClassTfidfTransformer(
    bm25_weighting=True
)

Интерпретация тем (Representation Models)

BERTopic позволяет использовать несколько подходов для интерпретации тем, которые работают поверх результатов c-TF-IDF. Самый интересный из них, на мой взгляд — это генерация человекочитаемых названий с помощью LLM.

Использование LLM позволяет генерировать названия кластеров вида «Проблемы с приложениями», «Отсутствие наушников в комплекте», «Плохая камера телефона».

В качестве локальной LLM я использовал Qwen/Qwen3.5-4B, веса которой в формате bfloat16 помещаются с запасом для инференса на выбранную ранее видеокарту P100.

LLM получает на вход репрезентативные тексты каждого кластера, ключевые слова и биграммы, которые были выделены с помощью c-TF-IDF на предыдущем шаге. Это позволяет модели лучше понимать контекст кластера и избегать слишком общих или абстрактных названий тем.

Минимальный пример структуры промпта, который можно использовать в пайплайне BERTopic:

Примеры текстов:
[DOCUMENTS]

Ключевые слова:
[KEYWORDS]

Верни только название темы.

Поля [DOCUMENTS] и [KEYWORDS] в промпте обязательны, если мы хотим, чтобы BERTopic подставлял в них репрезентативные тексты и ключевые слова соответственно. По умолчанию BERTopic использует только [KEYWORDS].

В свой промпт я добавил дополнительные инструкции и ограничения для модели, которые помогают контролировать результат генерации:

• «Название должно быть связанное длиной до 3-5 слов».

• «Не используй глаголы».

• «Используй ключевые слова как подсказку».

• «Возвращай только название темы, без пояснений».

• «Не добавляй лишние символы».

Для интеграции LLM в пайплайн BERTopic я использовал кастомный класс, который объединяет загрузку модели, создание промпта и объекта TextGeneration, необходимого для работы с BERTopic:

class BERTopicLLMRepresentation:
    """Класс для генерации названий с помощью локальной LLM."""
    def __init__(
        self,
        model_id: str,
        max_new_tokens: int = 20,
        temperature: float = 0.7,
        top_p: float = 0.8,
        top_k: int = 20,
        do_sample: bool = True,
        nr_docs: int = 5,
    ) -> None:
        """Инициализация LLM и параметров генерации.
        
        @param model_id: идентификатор модели или локальный путь)
        @param max_new_tokens: максимальное количество генерируемых токенов
        @param temperature: температура для контроля случайности
        @param top_p: nucleus sampling
        @param top_k: ограничение на количество рассматриваемых токенов
        @param do_sample: использовать ли сэмплирование при генерации
        @param nr_docs: количество текстов для представления темы в BERTopic
        """
        self.model_id = model_id
        self.nr_docs = nr_docs

        self.system_prompt = """
        Ты - эксперт по кластеризации текстов и генерации тем.
        Твоя задача - прочитать несколько текстов и список 
        ключевых слов и фраз темы и дать ей краткое, информативное название.
        
        Следуй правилам:
        - Название должно быть связанное, длина до 3-5 слов
        - Не используй глаголы
        - Используй ключевые слова как подсказку
        - Возвращай только название темы, без пояснений
        - Не добавляй лишние символы
        
        Формат выхода: только название темы.
        """
        
        self.user_prompt = """
        Примеры текстов:
        [DOCUMENTS]
        
        Ключевые слова: [KEYWORDS]
        
        Верни только название темы и ничего более
        """
        
        self.tokenizer = AutoTokenizer.from_pretrained(
            model_id,
            trust_remote_code=True
        )

        self.model = AutoModelForCausalLM.from_pretrained(
            model_id,
            device_map="auto",
            trust_remote_code=True
        )

        self.model.eval()

        self.generator = pipeline(
            task="text-generation",
            model=self.model,
            tokenizer=self.tokenizer,
            max_new_tokens=max_new_tokens,
            temperature=temperature,
            top_p=top_p,
            top_k=top_k,
            do_sample=do_sample,
            max_length=None,
        )

    def _build_prompt(self) -> str:
        """Формирование промпта для генерации.
        
        @return: сформированный промпт
        """
        messages = [
            {"role": "system", "content": self.system_prompt},
            {"role": "user", "content": self.user_prompt},
        ]

        return self.tokenizer.apply_chat_template(
            messages,
            tokenize=False,
            add_generation_prompt=True,
            enable_thinking=False
        )

    def build(self) -> TextGeneration:
        """Создание representation_model для BERTopic.
        
        @return: объект TextGeneration
        """
        prompt = self._build_prompt()

        return TextGeneration(
            self.generator,
            prompt=prompt,
            nr_docs=self.nr_docs
        )

Я использовал параметры генерации, рекомендуемые авторами модели для режима non-thinking.

При использовании локальной LLM в качестве единственной representation_model через класс TextGeneration стандартное представление тем BERTopic заменяется на сгенерированное. Ключевые слова и биграммы, полученные с помощью c-TF-IDF, больше не отображаются и не могут участвовать в визуализациях.

Я добавил в representation_model дополнительный способ описания тем с помощью KeyBERTInspired. Это метод, основанный на идеях KeyBERT, который выбирает ключевые слова и биграммы не по частоте, а по их семантической близости к теме в пространстве эмбеддингов. Благодаря этому темы получаются более понятными и интерпретируемыми, чем при использовании c-TF-IDF.

Кастомная модель интерпретации тем будет выглядеть следующим образом:

llm_repr = BERTopicLLMRepresentation(model_id="Qwen/Qwen3.5-4B").build()

custom_representation_model = {
    "KeyBERTInspired_representation": KeyBERTInspired(
        random_state=SEED
    ),
    "LLM_representation": llm_representation_model
}

print(custom_representation_model)

Сборка пайплайна BERTopic

После подготовки всех компонентов их можно объединить в единый пайплайн с помощью класса BERTopic, который выглядит следующим образом:

topic_model = BERTopic(
    language=None,
    embedding_model=embedding_model,
    umap_model=UMAP(
        random_state=SEED,
        n_neighbors=15,
        n_components=10,
        min_dist=0.0,
        metric='cosine',
        transform_seed=SEED
    ),
    hdbscan_model=HDBSCAN(
        min_cluster_size=15,
        min_samples=5,
        metric='euclidean',
        cluster_selection_method='eom',
        prediction_data=True
    ),
    vectorizer_model=vectorizer_model,
    ctfidf_model=ctfidf_model,
    representation_model=custom_representation_model,
    verbose=True,
    calculate_probabilities=True
)

В этом пайплайне я увеличил параметр n_components модели UMAP с 2 до 10 (рекомендуемый диапазон от 5 до 15), чтобы лучше сохранить структуру данных. Это помогает HDBSCAN находить более точные и устойчивые кластеры.

Запуск пайплайна осуществляется вызовом метода fit_transform():

topics, _= topic_model.fit_transform(
    documents=df_sample["clean_minus"].tolist()
)

В логе работы пайплайна можно увидеть все этапы его работы, которые мы рассмотрели ранее.

Результаты кластеризации удобно проанализировать с помощью вызова метода get_topic_info():

topic_info_df = topic_model.get_topic_info()
topic_info_df.shape

(40, 7)

В моем случае метод вернул датафрейм с 40 строками (по числу кластеров, включая шумовой) и следующими столбцами:

• «Topic» — идентификатор кластера;

• «Count» — количество текстов в кластере;

• «Name» — название темы, составленное с помощью ключевых слов биграмм c-TF-IDF;

• «Representation» — топ ключевых и биграмм;

• «KeyBERTInspired_representation» — ключевые слова и биграммы KeyBERTInspired;

• «LLM_representation» — название темы, сгенерированное LLM;

• «Representative_Docs» — репрезентативные тексты кластеров.

По умолчанию BERTopic использует поле «Name» в качестве названия тем для визуализаций. Чтобы заменить названия на сгенерированные с помощью LLM, их нужно установить через set_topic_labels(), переименовав одновременно шумовой кластер:

def set_custom_llm_topic_name(model: BERTopic) -> None:
    """Установка сгенерированных с помощью LLM названий тем 
    в качестве кастомных в модель BERTopic.

    @param model: тематическая модель BERTopic
    """
    llm_topic_labels = {
    topic: list(zip(*values))[0][0].strip()
        for topic, values in model.topic_aspects_["LLM_representation"].items()
    }
    llm_topic_labels[-1] = "Шумовой кластер"
    model.set_topic_labels(llm_topic_labels)

Такая модификация тематической модели добавляет новый столбец «CustomName» в датафрейм с результатами кластеризации.

Для добавления результатов кластеризации к исходным данным, воспользуемся следующим способом:

def set_topic_name_to_documents(
    df: pd.DataFrame,
    model: BERTopic,
    topics: List[int]
) -> pd.DataFrame:
    """Добавление в исходный датасет с текстами 
    меток кластеров модели BERTopic и сгенерированных
    названий тем.

    @param df: исходный датасет
    @param model: обученная модель BERTopic
    @param topics: метки кластеров
    @return: датасет с метками и имена кластеров
    """
    llm_topic_labels = {
    topic: list(zip(*values))[0][0].strip()
        for topic, values in model.topic_aspects_["LLM_representation"].items()
    }
    llm_topic_labels[-1] = "Шумовой кластер"
    
    df["topic"] = topics
    df["topic_llm_name"] = df["topic"].progress_map(llm_topic_labels.get)
    
    return df


df_sample_upd = set_topic_name_to_documents(df=df_sample, model=topic_model, topics=topics)

Теперь каждый текст в исходном датасете будет иметь идентификатор кластера и сгенерированное название темы.

Визуализация результатов кластеризации

После построения тематической модели полезно не только изучить таблицу тем, но и исследовать структуру тематического пространства. BERTopic предоставляет несколько интерактивных визуализаций (на базе Plotly), которые помогают анализировать взаимное расположение тем, ключевые слова, размер и плотность кластеров.

При вызове методов визуализации я использую параметр custom_labels=True, для отображения сгенерированных названий тем.

Начнем с глобальной карты тем:

topic_model.visualize_topics(
    top_n_topics=len(topic_info_df),
    custom_labels=True,
    width=1600,
    height=1600
)

Каждая окружность на рисунке — это отдельная тема, расстояние между ними отражают семантическую близость, а размер окружности показывает количество текстов в ней.

Если на карте тем одна окружность визуально расположена внутри другой, это означает, что темы имеют почти одинаковые координаты в 2-мерной проекции. Обычно это происходит, когда темы семантически очень близки и могут рассматриваться как подтемы одной области. Это хорошие кандидаты для topic reduction.

Отображение самих текстов отзывов можно построить методом visualize_documents():

topic_model.visualize_documents(
    df_sample["clean_minus"].tolist(),
    hide_annotations=True,
    custom_labels=True,
    width=1200,
    height=750
)

В этом случае каждая точка соответствует отдельному тексту, а цвет указывает на присвоенную ему тему. Такая визуализация позволяет оценить, насколько хорошо документы разделяются по кластерам и есть ли пересечения или «размытые» области между темами.

Код для отображения ключевых слов и биграмм по каждой теме:

topic_model.visualize_barchart(
    topics=topic_info_df["Topic"].tolist(),
    top_n_topics=len(topic_info_df),
    custom_labels=True,
    width=350,
    height=250
)

График показывает топ-5 ключевых слов и биграмм с их весами (на основе c-TF-IDF) для каждой темы в виде столбчатых диаграмм. Этот тип визуализации используется для интерпретации тем и сравнения их содержания между собой.

Ниже приведен код для построения иерархической структуры тем:

hierarchical_topics = topic_model.hierarchical_topics(
    docs=df_sample["clean_minus"].tolist(),
    linkage_function=lambda x: sch.linkage(x, 'ward', optimal_ordering=True)
)

topic_model.visualize_hierarchy(
    hierarchical_topics=hierarchical_topics,
    width=1800,
    height=1125,
    custom_labels=True
)

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

Матрицу сходства тем можно построить с использованием метода visualize_heatmap():

topic_model.visualize_heatmap(
    top_n_topics=len(topic_info_df),
    custom_labels=True,
    width=1200,
    height=1200
)

Строки и столбцы — это темы, цветом выделена семантическая близость: тёмные области отвечают за высокая похожесть, светлые — более низкую. Визуализация позволяет быстро увидеть похожие темы, дублирование кластеров, группы связанных тем.

Оценка качества кластеризации

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

Для пайплайна BERTopic (с применением UMAP и HDBSCAN) не существует единственной универсальной метрики качества, поскольку различные аспекты модели требуют отдельной оценки. Я предлагаю рассмотреть четыре метрики, отражающие ключевые свойства тематической модели: покрытие данных, согласованность тем, различимость и устойчивость тем. Совместное использование этих метрик позволяет получить целостную оценку качества тематической модели.

Покрытие кластеризации

Доля шумовых точек после применения алгоритма HDBSCAN показывает насколько данные вообще поддаются кластеризации. Если выбросов слишком много, то модель либо слишком строгая, либо в данных нет четкой структуры. Но важно также и смотреть на распределение самих кластеров. Если один кластер занимает бо́льшую часть данных, это уже признак переобобщения, то есть модель теряет детальную структуру и сводит все к крупным темам.

Посмотрим на эти метрики для нашей модели:

def compute_cluster_coverage(model: BERTopic) -> Tuple[float, dict]:
    """Вычисление доли шумового кластера
    и доли топ-5 не шумовых кластеров.
    
    @param model: обученная модель BERTopic
    @return: доли шумового и не шумовых кластеров
    """
    topics = np.array(model.topics_)
    total = len(topics)

    outliers_ratio = np.mean(topics == -1)

    unique, counts = np.unique(topics[topics != -1], return_counts=True)
    top_5_ratio = [round(float(item)/total, 3) for item in counts[:5]]

    return float(outliers_ratio), list(zip([float(item) for item in counts[:10]], top_5_ratio))


outliers_ratio, top_5_ratio = compute_cluster_coverage(model=topic_model)
print(f"Доля шума (кластер -1): {outliers_ratio:.3f}")
print(f"Топ-5 размеров кластеров: {", ".join([f"{k}: {v}" for k, v in top_5_ratio])}")

Доля шума (кластер -1): 0.187

Топ-5 размеров кластеров: 324.0: 0.102, 274.0: 0.086, 210.0: 0.066, 204.0: 0.064, 200.0: 0.063

Доля выбросов составляет 0.187 и находится ниже условного порогового значения 0.2-0.3, что указывает на хорошее покрытие данных кластерами. Доли крупнейших кластеров составляют 0.102, 0.086, 0.066, это говорит об отсутствии одной или нескольких доминирующих тем.

Согласованность тем: Topic Coherence

Topic Coherence — это набор метрик, показывающих насколько слова внутри одной темы связаны между собой. Высокая coherence означает что тема интерпретируема и человек сможет дать ей осмысленное название. Разные варианты метрик используют различные принципы: совместную встречаемость слов в документах, скользящие окна или нормализованную взаимную информацию. Поэтому значения метрик могут существенно различаться в зависимости от структуры данных и типа корпуса.

Для валидации результатов я использую случайный baseline (coherence тем из случайно выбранных слов корпуса). Метрики coherence для реальных тем должны превосходить baseline:

def compute_coherence(
    model: BERTopic,
    documents: List[str],
    top_n: int = 10
) -> None:
    """Вычисление coherence тем.
    
    Для оценки значимости результата используется baseline 
    coherence случайно сформированных тем из слов корпуса.

    @param model: обученная модель BERTopic
    @param documents: исходные тексты
    @param top_n: количество топ-слов на тему
    """
    analyzer = model.vectorizer_model.build_analyzer()
    tokenized_docs = [analyzer(doc) for doc in documents]
    
    topic_ids = [t for t in model.get_topic_info()['Topic'] if t != -1]
    topic_words = [
        [w for w, _ in model.get_topic(tid)[:top_n]]
        for tid in topic_ids
    ]

    corpus_vocab = set(w for doc in tokenized_docs for w in doc)

    dictionary = Dictionary(tokenized_docs)
    all_words = list(corpus_vocab)
    n_topics = len(topic_ids)

    random_topics = [
        random.sample(all_words, top_n)
        for _ in range(n_topics)
    ]

    dictionary = Dictionary(tokenized_docs)

    for coh_metric in ["c_uci", "c_npmi", "u_mass"]:
        score = CoherenceModel(
            topics=topic_words,
            texts=tokenized_docs,
            dictionary=dictionary,
            coherence=coh_metric
        ).get_coherence()

        score_rnd = CoherenceModel(
            topics=random_topics,
            texts=tokenized_docs,
            dictionary=dictionary,
            coherence=coh_metric
        ).get_coherence()

        delta = score - score_rnd
        
        print(f"{coh_metric} score: {score:.3f}, random score: {score_rnd:.3f}, delta: {delta:.3f}")


compute_coherence(
    model=topic_model,
    documents=df_sample["clean_minus"].tolist()
)

c_uci score: -5.445, random score: -10.689, delta: 5.244

c_npmi score: -0.081, random score: -0.386, delta: 0.305

u_mass score: -9.832, random score: -19.729, delta: 9.897

Все три метрики дают положительную delta, это подтверждает то, что модель нашла реальную тематическую структуру в данных. Абсолютные же значения метрик низкие. Это ожидаемо для коротких текстов при медианной длине в 6 токенов на отзыв (после лемматизации и удаления стоп-слов). Слова темы редко встречаются вместе в одном отзыве, что объективно снижает статистику совстречаемости.

Разнообразие тем: Topic Diversity

Даже если темы внутри себя согласованы, они всё равно могут дублировать друг друга. Topic Diversity показывает насколько темы различаются между собой. Метрика измеряет, как сильно пересекаются ключевые слова и биграммы из разных тем. Низкое значение метрики говорит о дублировании тем, а слишком высокое — о том, что модель начинает дробить данные на слишком мелкие и слабо связанные темы.

Моя реализация расчета этой метрики:

def compute_topic_diversity(model: BERTopic, top_n: int = 10) -> float:
    """Вычисление доли уникальных слов 
    среди top-n слов всех тем.

    @param model: обученная модель BERTopic
    @param top_n: количество слов на тему
    @return: diversity (от 0 до 1)
    """
    all_words = []

    for topic_id in model.get_topic_info()['Topic']:
        if topic_id == -1:
            continue

        words = [w for w, _ in model.get_topic(topic_id)[:top_n]]
        all_words.extend(words)

    if not all_words:
        return 0.0

    return len(set(all_words)) / len(all_words)


print(f"Разнообразие тем: {compute_topic_diversity(model=topic_model):.2f}")

Разнообразие тем: 0.80

Полученное значение topic diversity 0.80 попадает в оптимальный диапазон (примерно 0.6–0.85). Темы хорошо различаются между собой и не имеют значительного пересечения по ключевым словам. Это свидетельствует об отсутствии выраженного дублирования тем и достаточной степени их разнообразия.

Устойчивость: Stability (ARI)

Хорошая кластеризация должна быть воспроизводимой: небольшие изменения случайности ^[23] не должны сильно менять результат. В пайплайн BERTopic стохастичность вносит шаг уменьшения размерности с помощью UMAP. Adjusted Rand Index (ARI) позволяет измерить воспроизводимость структуры кластеров между запусками модели. Высокий ARI означает, что модель выделяет устойчивые паттерны, а не случайные группировки.

Для расчета метрики тематическая модель запускалась с разными random_state на этапе umap_model (для ускорения я отключил шаг representation_model):

def compute_stability(
    documents: List[str],
    embedding_model: FRIDAEmbedderWithPrefix,
    vectorizer_model: CountVectorizer,
    ctfidf_model: ClassTfidfTransformer,
    n_runs: int = 10
) -> dict:
    """Оценка устойчивости алгоритма UMAP через random_state
    с помощью Adjusted Rand Index (ARI).

    @param documents: исходные тексты
    @param embedding_model: модель эмбеддингов
    @param vectorizer_model: векторизатор
    @param ctfidf_model: c-TF-IDF модель
    @param n_runs: количество запусков
    @return: статистики ARI
    """
    label_sets = []

    for seed in tqdm(range(n_runs)):
        model = BERTopic(
            language=None,
            embedding_model=embedding_model,
            umap_model=UMAP(
                random_state=seed,
                n_neighbors=15,
                n_components=10,
                min_dist=0.0,
                metric='cosine',
                transform_seed=seed
            ),
            hdbscan_model=HDBSCAN(
                min_cluster_size=15,
                min_samples=5,
                metric='euclidean',
                cluster_selection_method='eom',
                prediction_data=True
            ),
            vectorizer_model=vectorizer_model,
            ctfidf_model=ctfidf_model,
            representation_model=None,
            calculate_probabilities=False,
            verbose=False
        )

        topics, _ = model.fit_transform(documents)
        label_sets.append(topics)

    scores = []
    for i in range(len(label_sets)):
        for j in range(i + 1, len(label_sets)):
            scores.append(adjusted_rand_score(label_sets[i], label_sets[j]))

    return {
        "mean": float(round(np.mean(scores), 3)),
        "std": float(round(np.std(scores), 3)),
        "min": float(round(np.min(scores), 3)),
        "max": float(round(np.max(scores), 3))
    }


stability_dict = compute_stability(
    documents=df_sample["clean_minus"].tolist(),
    embedding_model=embedding_model,
    vectorizer_model=vectorizer_model,
    ctfidf_model=ctfidf_model
)

print(f"Устойчивость Adjusted Rand Index (ARI): {stability_dict}")

Устойчивость Adjusted Rand Index (ARI): {‘mean’: 0.717, ‘std’: 0.056, ‘min’: 0.631, ‘max’: 0.833}

Среднее значение ARI равно 0.717 при стандартном отклонении 0.056. Это говорит о том, что модель в целом стабильно воспроизводит схожую кластерную структуру при изменении случайности в UMAP.

Все четыре метрики указывают на достаточно хорошее качество тематической модели, которая с высокой вероятностью отражает реальную структуру данных.

Анализ тем для определенного отзыва

После обучения тематической модели важно понимать не только какая тема присвоена конкретному отзыву, но и насколько этот отзыв связан с разными темами.

В BERTopic для этого есть несколько методов: find_topics(), transform() и approximate_distribution().

Начнем с метода find_topics(), который вычисляет косинусное сходство между эмбеддингом отзыва и центроидами всех тем. Он возвращает id и название темы, значение сходства для топ-n наиболее похожих тем для переданного отзыва:

def find_relevant_topics(text: str, model: BERTopic, llm_topic_labelstop_n: int = 3) -> dict:
    """Поиск наиболее похожих top-n тем для отзыва.

    @param text: текст отзыва
    @param model: обученная модель BERTopic
    @param top_n: количество релевантных тем для вывода
    @return: релевантные темы и скоры
    """
    similar_topics, similarity = topic_model.find_topics(
        search_term=text,
        top_n=3
    )
    llm_topic_labels = dict(
        zip(topic_model.topic_labels_.keys(), topic_model.custom_labels_)
    )
    topic_with_sim = {
        llm_topic_labels[k]: round(float(v), 3) for k, v in zip(similar_topics, similarity)
    }
    return topic_with_sim

  
text = "Нет в комплекте ни силиконовой накладки, ни антиударного стекла для защиты от царапин, даже наушников нет"
topic_with_sim = find_relevant_topics(text=text, model=topic_model, llm_topic_labels=llm_topic_labels)
print(f"Наиболее похожие темы: {topic_with_sim}")

Наиболее похожие темы: {‘Проблемы с чехлом и стеклом’: 0.977, ‘Защита экрана от царапин’: 0.971, ‘Отсутствие наушников в комплекте’: 0.971}

Если нужно отнести отзыв к одной конкретной теме, используется метод transform(). Он запускает весь пайплайн кластеризации и возвращает одну наиболее вероятную тему для отзыва, а также приближенную вероятность принадлежности к этой теме (не классический softmax):

def predict_topic(text: str, model: BERTopic, llm_topic_labels: dict) -> dict:
    """Предсказание темы и вероятности для отзыва.

    @param text: текст отзыва
    @param model: обученная модель BERTopic
    @param llm_topic_labels: id и названия тем
    @return: предсказанная тема и вероятность
    """
    pred_topics, pred_probs = model.transform([text])
    return llm_topic_labels[int(pred_topics[0])], round(max(pred_probs[0]), 3)


text = "плохо работает сканер отпечатка пальца на солнце"
pred_topic, pred_prob = predict_topic(
    text=text,
    model=topic_model,
    llm_topic_labels=llm_topic_labels
)
print(f"Тема: {pred_topic}")
print(f"Вероятность темы: {pred_prob}")

Тема: Проблемы сканера отпечатков пальцев

Вероятность темы: 0.975

Метод approximate_distribution() оценивает распределение тем внутри отзыва. Текст отзыва разбивается на перекрывающиеся фрагменты (скользящим окном), для каждого фрагмента вычисляется похожесть для всех тем, а затем оценки суммируются, формируя итоговое распределение вероятностей для всего отзыва:

def get_approx_distr(
    text: str,
    model: BERTopic
) -> None:
    """Получение распределения тем для отзыва.

    @param text: текст отзыва
    @param model: обученная модель BERTopic  
    """ 
    topic_distr, topic_token_distr = model.approximate_distribution(
        documents=text,
        window=3,
        stride=1,
        min_similarity=0.1
    )
    fig_visualize_distribution = model.visualize_distribution(
        topic_distr[0],
        custom_labels=True,
        width=800,
        height=600
    )
    fig_visualize_distribution.show()


text = "Очень долго загружаются приложения и игры, не положили наушники, камера слабая"
get_approx_distr(text=text, model=topic_model)

Оптимизация структуры тем: объединение и работа с шумом

После первичной кластеризации может возникнуть следующая ситуация: выделено большое количество кластеров, некоторые из которых дублируют друг друга, а также присутствует достаточно большой шумовой кластер. Это нормальное поведение ^[24] для HDBSCAN. Он формирует локально плотные группы и одна большая тема может распадаться на несколько мелких.

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

Метод reduce_topics() позволяет объединять похожие кластеры в новые темы:

topic_model.reduce_topics(
    docs=df_sample["clean_minus"].tolist(),
    nr_topics="auto"
)

topics = topic_model.topics_

BERTopic «под капотом» считает эмбеддинги кластеров, вычисляет между ними косинусную близость, строит иерархическое дерево и объединяет наиболее похожие кластеры в новую тему. Если задать численное значение параметра nr_topics, то BERTopic объединит кластеры до указанного количества.

Автоматическое сокращение не всегда идеально. Иногда стоит попробовать объединить темы вручную, указав индексы кластеров в параметре topics_to_merge метода merge_topics():

topic_model.merge_topics(
    docs=df_sample["clean_minus"].tolist(),
    topics_to_merge=[4, 36]
)

При таком подходе тексты выбранных кластеров объединяются, пересчитывается c-TF-IDF для новых тем, обновляются ключевые слова и модели интерпретации.

Метод reduce_outliers() перераспределяет тексты, попавшие в шумовой кластер, между уже существующими темами:

new_topics = topic_model.topics_

new_topics = topic_model.reduce_outliers(
    documents=df_sample["clean_minus"].tolist(),
    topics=topics
)

topic_model.update_topics(
    docs=df_sample["clean_minus"].tolist(),
    topics=new_topics
)

Каждый текст с индексом -1 сравнивается с центроидами существующих кластеров и присваиваются наиболее подходящей теме.

Чтобы не «сломать» тематическую модель, постобработку тем лучше делать в следующем порядке:

1. Уменьшаем количество кластеров, формируя новые темы (reduce_topics).

2. При необходимости делаем слияние в ручном режиме (merge_topics).

3. Перераспределяем шумовые тексты в существующие темы (reduce_outliers).

4. Фиксируем финальное состояние модели (update_topics).

Неправильная последовательность (применение reduce_outliers до reduce_topics) может вернуть старое количество кластеров или сделать модель неконсистентной.

Заключение

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

Библиотека BERTopic объединяет современные подходы и модели машинного обучения в единый пайплайн: контекстные эмбеддинги модели FRIDA, снижения размерности с помощью UMAP и иерархическую плотностную кластеризацию HDBSCAN. В результате тематическая модель способна находить устойчивые темы даже в шумных и разнородных данных.

Дополнительные инструменты визуализации помогают исследовать структуру кластеров и их взаимосвязи. Использование LLM в пайплайне делает результат более интерпретируемым, превращая наборы ключевых слов в понятные названия тем.

В итоге получается полноценный аналитический пайплайн: от «сырых» текстов до интерпретируемых тем и визуализаций, которые можно использовать в продуктовой аналитике, исследовании пользовательского опыта ^[25] и мониторинге обратной связи.