BERTopic

BERTopic（一种基于 Transformer 的主题建模技术）是一种主题建模（Topic Modeling）方法，它利用 🤗 Transformer 模型库和 c-TF-IDF 生成密集聚类（dense clusters），既能创建易于理解的主题，又能保留主题描述中的关键术语。

BERTopic 支持多种主题建模技术：

引导式建模	监督式建模	半监督式建模
手动建模	多主题分布	层次化建模
基于类别的建模	动态主题建模	在线/增量建模
多模态建模	多维度建模	文本生成/大语言模型（LLM）
零样本建模 (新增！)	模型合并 (新增！)	种子词 (新增！)

对应的 Medium 文章可在此处查看、此处和此处。如需更详细说明，可阅读论文或查看简要概述。

安装

使用 uv 安装（含 sentence-transformers）：

uv add bertopic

或使用 pip：

pip install bertopic

如需安装支持其他嵌入模型（embedding models）的 BERTopic，可选择以下任一方式：

# 选择嵌入后端
pip install bertopic[flair,gensim,spacy,use]

# 图像主题建模
pip install bertopic[vision]

如需轻量级安装（不含 transformers、UMAP 和/或 HDBSCAN，适用于 Model2Vec 训练或推理），请参阅本教程。

快速入门

如需深入了解 BERTopic 的功能特性，可查阅完整文档，或参考以下示例：

名称	链接
从此开始 - BERTopic 最佳实践
🆕 新增！ - 大规模数据主题建模（GPU 加速）
🆕 新增！ - 使用 Llama 2 🦙 进行主题建模
🆕 新增！ - 使用量化大语言模型（LLMs）进行主题建模
使用 BERTopic 进行主题建模
BERTopic 中的（自定义）嵌入模型
BERTopic 高级自定义
BERTopic 的（半）监督主题建模
基于特朗普推文的动态主题建模
arXiv 摘要主题建模

快速开始

我们首先从著名的 20 newsgroups（20 个新闻组）数据集中提取主题，该数据集包含英文文档：

from bertopic import BERTopic
from sklearn.datasets import fetch_20newsgroups
 
docs = fetch_20newsgroups(subset='all',  remove=('headers', 'footers', 'quotes'))['data']

topic_model = BERTopic()
topics, probs = topic_model.fit_transform(docs)

生成主题及其概率后，我们可以访问所有主题及其主题表示：

>>> topic_model.get_topic_info()

主题	计数	名称
-1	4630	-1_can_your_will_any
0	693	49_windows_drive_dos_file
1	466	32_jesus_bible_christian_faith
2	441	2_space_launch_orbit_lunar
3	381	22_key_encryption_keys_encrypted
...

-1 主题指代所有离群文档，通常被忽略。主题中的每个词描述了该主题的潜在主题，可用于解释该主题。接下来，我们查看生成的最频繁主题：

>>> topic_model.get_topic(0)

[('windows', 0.006152228076250982),
 ('drive', 0.004982897610645755),
 ('dos', 0.004845038866360651),
 ('file', 0.004140142872194834),
 ('disk', 0.004131678774810884),
 ('mac', 0.003624848635985097),
 ('memory', 0.0034840976976789903),
 ('software', 0.0034415334250699077),
 ('email', 0.0034239554442333257),
 ('pc', 0.003047105930670237)]

使用 .get_document_info，我们还可以提取文档级别的信息，例如其对应的主题、概率、是否为该主题的代表性文档等：

>>> topic_model.get_document_info(docs)

文档                                   主题	名称	                        Top_n_words                     概率    ...
I am sure some bashers of Pens...	0	0_game_team_games_season	game - team - games...	        0.200010       ...
My brother is in the market for...      -1     -1_can_your_will_any	        can - your - will...	        0.420668       ...
Finally you said what you dream...	-1     -1_can_your_will_any	        can - your - will...            0.807259       ...
Think! It's the SCSI card doing...	49     49_windows_drive_dos_file	windows - drive - docs...	0.071746       ...
1) I have an old Jasmine drive...	49     49_windows_drive_dos_file	windows - drive - docs...	0.038983       ...

🔥 提示: 使用 BERTopic(language="multilingual") 选择支持 50 多种语言的模型。

微调主题表示

在 BERTopic 中，我们可以选择多种不同的主题表示方法。它们彼此差异较大，为主题表示提供了有趣的视角和变体。一个很好的起点是 KeyBERTInspired（基于 KeyBERT 启发的主题表示方法），对许多用户而言，它能提高主题连贯性并减少停用词：

from bertopic.representation import KeyBERTInspired

# 微调主题表示
representation_model = KeyBERTInspired()
topic_model = BERTopic(representation_model=representation_model)

然而，您可能希望使用更强大的方法来描述聚类。您甚至可以使用 ChatGPT 或其他 OpenAI 模型生成标签、摘要、短语、关键词等：

import openai
from bertopic.representation import OpenAI

# 使用 GPT 微调主题表示
client = openai.OpenAI(api_key="sk-...")
representation_model = OpenAI(client, model="gpt-4o-mini", chat=True)
topic_model = BERTopic(representation_model=representation_model)

🔥 提示: 无需逐一尝试这些不同的主题表示方法，您可以在 BERTopic 中使用多角度主题表示同时建模。

可视化

训练完 BERTopic 模型后，我们可以逐个检查数百个主题以充分理解提取的主题。但这非常耗时且缺乏全局视角。相反，我们可以使用 BERTopic 中的多种可视化选项。例如，我们可以以类似 LDAvis 的方式可视化生成的主题：

topic_model.visualize_topics()

模块化

默认情况下，使用 BERTopic 进行主题建模的主要步骤是 sentence-transformers（句子嵌入模型）、UMAP（降维算法）、HDBSCAN（聚类算法）和 c-TF-IDF（主题表示算法）按顺序执行。但这些步骤之间具有一定的独立性，使 BERTopic 非常模块化。换言之，BERTopic 不仅允许您构建自己的主题模型，还能在自定义主题模型基础上探索多种主题建模技术：

https://user-images.githubusercontent.com/25746895/218420473-4b2bb539-9dbe-407a-9674-a8317c7fb3bf.mp4

您可以替换其中任何模型，甚至完全移除它们。以下步骤完全模块化：

1. 嵌入文档
2. 降低嵌入维度
3. 将降维后的嵌入聚类为主题
4. 主题向量化
5. 加权主题词
6. 使用一种或多种表示方法表示主题

功能

BERTopic 拥有许多功能，可能令人眼花缭乱。为解决此问题，您将找到所有方法的概述及其用途的简要说明。

常见功能

以下是对BERTopic（神经主题建模工具）中常见功能的概述。

方法	代码
拟合模型	.fit(docs)
拟合模型并预测文档	.fit_transform(docs)
预测新文档	.transform([new_doc])
访问单个主题	.get_topic(topic=12)
访问所有主题	.get_topics()
获取主题频率	.get_topic_freq()
获取所有主题信息	.get_topic_info()
获取所有文档信息	.get_document_info(docs)
获取每个主题的代表性文档	.get_representative_docs()
更新主题表示	.update_topics(docs, n_gram_range=(1, 3))
生成主题标签	.generate_topic_labels()
设置主题标签	.set_topic_labels(my_custom_labels)
合并主题	.merge_topics(docs, topics_to_merge)
减少主题数量	.reduce_topics(docs, nr_topics=30)
减少离群点	.reduce_outliers(docs, topics)
查找主题	.find_topics("vehicle")
保存模型	.save("my_model", serialization="safetensors")
加载模型	BERTopic.load("my_model")
获取参数	.get_params()

属性

训练完BERTopic模型后，模型内部会保存多个属性。这些属性部分描述了模型在拟合过程中如何存储信息。以下所有属性均以_结尾，是可用于访问模型信息的公共属性。

属性	描述
.topics_	训练或更新主题模型后，为每个文档生成的主题。
.probabilities_	如果使用HDBSCAN（分层密度聚类算法），则为每个文档生成的概率。
.topic_sizes_	每个主题的大小
.topic_mapper_	用于在主题合并/减少时跟踪主题及其映射的类。
.topic_representations_	每个主题的前n个术语及其相应的c-TF-IDF（类TF-IDF）值。
.c_tf_idf_	通过c-TF-IDF（类TF-IDF）计算得到的主题-术语矩阵。
.topic_aspects_	每个主题的不同方面或表示。
.topic_labels_	每个主题的默认标签。
.custom_labels_	通过.set_topic_labels生成的每个主题的自定义标签。
.topic_embeddings_	如果使用了embedding_model（嵌入模型），则为每个主题的嵌入向量。
.representative_docs_	如果使用HDBSCAN（分层密度聚类算法），则为每个主题的代表性文档。

变体

主题建模可用于多种不同的使用场景。因此，BERTopic开发了多种变体，使得一个包可以适用于多种用例。

方法	代码
主题分布近似	.approximate_distribution(docs)
在线主题建模	.partial_fit(doc)
半监督主题建模	.fit(docs, y=y)
监督主题建模	.fit(docs, y=y)
手动主题建模	.fit(docs, y=y)
多模态主题建模	.fit(docs, images=images)
按类别主题建模	.topics_per_class(docs, classes)
动态主题建模	.topics_over_time(docs, timestamps)
分层主题建模	.hierarchical_topics(docs)
引导式主题建模	BERTopic(seed_topic_list=seed_topic_list)
零样本主题建模	BERTopic(zeroshot_topic_list=zeroshot_topic_list)
合并多个模型	BERTopic.merge_models([topic_model_1, topic_model_2])

可视化

由于评估具有一定的主观性，评估主题模型可能相当困难。可视化主题模型的不同方面有助于理解模型，并使其更容易根据您的喜好进行调整。

方法	代码
可视化主题	.visualize_topics()
可视化文档	.visualize_documents()
可视化文档层次结构	.visualize_hierarchical_documents()
可视化主题层次结构	.visualize_hierarchy()
可视化主题树	.get_topic_tree(hierarchical_topics)
可视化主题术语	.visualize_barchart()
可视化主题相似度	.visualize_heatmap()
可视化术语分数下降	.visualize_term_rank()
可视化主题概率分布	.visualize_distribution(probs[0])
可视化主题随时间变化	.visualize_topics_over_time(topics_over_time)
可视化按类别的主题	.visualize_topics_per_class(topics_per_class)

引用

要引用BERTopic论文，请使用以下bibtex参考文献：

@article{grootendorst2022bertopic,
  title={BERTopic: Neural topic modeling with a class-based TF-IDF procedure},
  author={Grootendorst, Maarten},
  journal={arXiv preprint arXiv:2203.05794},
  year={2022}
}

BERTopic 快速上手指南

环境准备

• 系统要求：Python 3.10 或更高版本
• 前置依赖：确保已安装基础 Python 环境（推荐使用虚拟环境）。若需 GPU 加速，需配置 CUDA 环境（非必需）
• 国内加速建议：安装时优先使用清华镜像源，显著提升下载速度

安装步骤

推荐使用国内镜像源安装（速度更快）：

pip install bertopic -i https://pypi.tuna.tsinghua.edu.cn/simple

如需安装额外功能模块（按需选择）：

# 安装 Flair/Gensim/Spacy 等嵌入模型支持
pip install bertopic[flair,gensim,spacy,use] -i https://pypi.tuna.tsinghua.edu.cn/simple

# 安装图像主题建模支持
pip install bertopic[vision] -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

以下是最简示例，使用内置数据集快速体验主题建模：

from bertopic import BERTopic
from sklearn.datasets import fetch_20newsgroups

# 加载示例数据（20 Newsgroups 英文文档集）
docs = fetch_20newsgroups(subset='all', remove=('headers', 'footers', 'quotes'))['data']

# 训练主题模型
topic_model = BERTopic()
topics, probs = topic_model.fit_transform(docs)

# 查看主题统计信息
print(topic_model.get_topic_info())

# 查看指定主题的关键词（示例：主题ID=0）
print(topic_model.get_topic(0))

关键说明：

1. fit_transform() 自动完成文档嵌入、聚类和主题生成
2. 输出中 -1 表示离群文档（通常可忽略）
3. 主题名称格式为 ID_关键词1_关键词2_...（如 0_game_team_games）
4. 多语言支持：初始化时添加参数 BERTopic(language="multilingual") 可处理 50+ 语言

提示：首次运行会自动下载预训练模型（约 400MB），建议在网络稳定的环境下执行。实际应用时，直接替换 docs 为您的中文文本列表即可（需确保文本已分句处理）。