BERTopic实战：从嵌入到聚类，轻松搞定语义主题建模

简介：这套BERTopic模型教程代码包面向自然语言处理与主题建模入门者，聚焦如何用BERT文本嵌入替换传统词袋表示，再经UMAP降维、HDBSCAN聚类和类间词频逆文档频率生成主题，解决传统LDA忽略语义关联的问题，适合文本挖掘、舆情分析、文档归纳等场景。资源共14个文件，906KB大小，包含离线演示与交互式Python脚本、示例文本、CSV主题输出、主题分布与热力图等PNG可视化、依赖说明和README，目录清晰，方便边看边跑。已有151人学习下载。读者可借此完整走通BERTopic流程，学会参数调节，掌握层次主题与动态主题模型的扩展用法，是一份能快速落地的入门代码包。

1. 先跑通再理解：BERTopic 模型为什么值得上手

手里有一批没标好的文档，想快速知道大家在聊什么主题。以前我用 LDA 跑，结果里全是“价格”“商品”这种大词，看不出语义边界。换成 BERTopic 模型之后，文档先变成向量，再聚类，最后每个类自动生成主题词，输出的是“语义相近的一群文档”，不是“词频共现的一堆词”。这篇文章就是给你一份能直接抄的落地路径：最小训练脚本、参数怎么设、模型怎么存，以及最容易翻车的几个坑。适合做运营内容聚类、客服工单分主题、电商评论提炼的人。你只需要有一份文档列表，最好还是没清洗过的原始文本，因为清洗步骤也会一起给到。

2. BERTopic 的原理骨架：嵌入、UMAP、HDBSCAN、c-TF-IDF 是怎么串成一条流水线的

要把 BERTopic 用明白，不用啃完 transformer 的公式，只需要理解它的四段接力：先让嵌入模型把每篇文档变成向量，再用 UMAP 把高维向量压到低维，接着用 HDBSCAN 找稠密区域，最后用 c-TF-IDF 给每个聚类生成主题词。每一段只做一件事，但前后是强依赖关系。我见过不少人在聚类参数上反复调，却忽略了嵌入层才是决定主题质量的上限，这一章就把四个环节的选型逻辑讲清楚。

2.1 四段式流水线：为什么比 LDA 更接近人的理解

LDA 和 NMF 这类传统主题模型，本质是在做“文档-词共现”统计，把经常一起出现的词绑成一个主题。这有一个硬伤：同义词、转述句、反讽表达在字面上完全不像，但在语义上是一回事。比如“充电慢”和“续航不行”在字面上没有共同词，人一眼就知道都在说电池问题，LDA 却很难把它们归到一类。

BERTopic 的思路是先做语义嵌入。每个文档经过 sentence-transformer 编码成一个向量，向量里包含的是“整句话的意思”，不是单个词的词频。接下来用 UMAP 降维，把几百维的向量压缩到五维左右，同时保留局部相似结构。然后交给 HDBSCAN 聚类，HDBSCAN 不需要预先指定主题个数，能自动把稠密区域识别成一类，把稀疏的点标成离群点。最后一步是 c-TF-IDF，把每个聚类里的文档拼起来算“类专属词”，得到人眼可读的主题词表。

这就是 BERTopic 模型和 LDA 最本质的区别：LDA 在词层面找共现，BERTopic 在句层面找语义相近。实际操作中，你会发现它对短文本、口语化文本尤其友好，因为嵌入层已经把句子结构调整过了，不需要像 LDA 那样拼命做同义词合并。

2.2 嵌入层的选型：embedding 模型怎么挑，主题质量从这里决定

嵌入层是整条流水线的天花板。UMAP 和 HDBSCAN 只能尽量不破坏嵌入结果，没法把嵌入搞砸的语义拉回来。所以选嵌入模型，比选聚类参数更值得花时间。

我平时用的方案大概是这么几类：

如果语料以中文为主，我一般直接试 bge 系列；如果只是先验证流程，all-MiniLM-L6-v2 就够，跑起来快，后面再换模型重训。需要特别提醒的是，这些模型默认是处理句子的，如果你的文档特别长，比如几千字的文章，最好先分段再平均，否则嵌入向量会被大量无关信息稀释。

还有一点容易被忽略：嵌入模型加载后会占内存，模型维度越高占得越多。很多人以为卡顿是聚类导致的，其实换一个大维度嵌入模型后，内存直接翻倍。先想清楚语料量级，再决定嵌入层。

2.3 UMAP 与 HDBSCAN 的联合效果：两个参数就可以决定你的主题长什么样

主题个数不是直接设置的，而是由 HDBSCAN 的密度阈值决定的。这里最关键的两个参数，一个是 UMAP 的n_neighbors，一个是 HDBSCAN 的min_cluster_size。

n_neighbors决定了降维时保留多大范围的局部结构。数值越小，UMAP 越关注点与最近邻居的关系，聚类边界会更细碎，适合标签类语料；数值越大，结构越平滑，小主题容易被吞掉。我一般从 15 开始，如果你的文本主题之间差异很大，可以降到 10 以下。

min_cluster_size是 HDBSCAN 判断“多少篇文档才能算一个主题”的下限。它直接控制主题个数：值越小，主题越多越细；值越大，主题越少越粗。默认 10 适合几百到几千篇的语料，如果是几万篇，我一般直接提到 20 到 50，否则会跑出一堆占比不到 1% 的碎片主题。

还有一个组合习惯值得抄：UMAP 的metric用cosine，降维后 HDBSCAN 的metric用euclidean。原因是降维后的空间已经接近局部欧氏结构，再在原始高维空间用余弦距离聚类反而费时。

n_components这里多说一句:很多人为了可视化直接降到 2，但聚类需要更多信息量，2 维会丢失太多结构。正确做法是训练时降到 5 维，可视化时单独再降一次到 2 维。

2.4 c-TF-IDF：从“聚在一起”到“主题是什么词”的最后一步

聚类完成后，每个类拿到一批文档编号。问题是，这批文档的共同点是什么？c-TF-IDF 解决的就是这个。

它的逻辑比经典 TF-IDF 更直观：先把每个类里的所有文档拼成一整篇“类文档”，统计每个词在这个类里出现的次数；然后把“该类出现这个词的文档比例”作为惩罚项。一个词如果在所有类里都频繁出现，说明它没有区分度，权重被压低；一个词只在当前类里高频率出现，它就是这类的高权重主题词。

所以 c-TF-IDF 输出的是“对区分这个类最有贡献的词”，而不是“这个类里出现最多的词”。这也是为什么 BERTopic 主题词表经常看起来比 LDA 干净很多的原因。topic_model.get_topic(0)返回的结果就是按这个权重排出来的，前几个词基本一眼能看出这一类在讲什么。

需要留意的是，c-TF-IDF 是在词表层面工作的，它不感知语义。如果文本里有两个同义词“性价比”和“划算”，它们的分数是分别计算的，不会自动合并。想要让主题词表更紧凑，后面用 MMR 做多样性控制是一种办法，但如果你想合并同义词，得在预处理阶段自己处理，或者接受主题词表里同时出现这两个词。

3. 用代码跑通 BERTopic：从原始文本到主题图和模型保存

这一章是全文核心，我按自己平时在项目里的步骤来：先列最小依赖，再给数据清洗函数，然后是完整训练脚本，最后是模型保存和复用。你按顺序执行，能得到一份可用的 BERTopic 模型，而不是一个 demo。

3.1 环境准备与最小依赖：先少装，别把环境搞得一塌糊涂

BERTopic 的安装比想象中轻，核心依赖就几个。新手最容易踩的坑是把umap-learn装错成umap，两个包都能 import 成功，但 API 完全不一样，后面跑聚类会莫名报错。

pip install bertopic pip install umap-learn hdbscan plotly

说明：bertopic安装时会把sentence-transformers、scikit-learn一起拉进来，所以不用单独装太多。plotly是用来画主题图的，想省事可以不装，但visualize_topics()会失效。hdbscan在 Windows 上偶尔需要预编译包，如果装不上，检查一下 Python 版本是否在 3.9 以上，我见过 3.7 老环境装 hdbscan 直接把安装过程卡死的情况。

装完后可以快速验证一下：

import bertopic from bertopic import BERTopic print(bertopic.__version__)

能看到版本号说明环境没问题。版本不要太老，0.16 之前的版本 API 差异比较大，很多参数名对不上，直接装最新版就行。

3.2 数据准备与清洗：哪些预处理真的值得做

BERTopic 对停用词不太敏感，因为它有嵌入层，不像 LDA 那样需要先去掉大量停用词才能看到主题。但有两类东西必须处理：HTML 标签和超链接。它们会占据 token 数量，干扰嵌入向量的语义。

import re def clean_text(text: str) -> str: text = re.sub(r"<[^>]+>", " ", text) # HTML 标签 text = re.sub(r"http\S+", " ", text) # 超链接 text = re.sub(r"\b\d{2,}\b", " NUM ", text) # 长数字替换成占位符 text = re.sub(r"[ \t]+", " ", text) # 连续空白压缩 return text.strip() docs = [clean_text(d) for d in raw_docs]

这段代码做了三件事。第一是去掉 HTML 标签，标签本身没有语义，还会造成不同页面模板产生伪主题。第二是去掉超链接，链接字符串对主题判断没有帮助。第三是把连续两位以上的数字替换成NUM占位符，防止“2021”“2023”这种年份数字被聚成一个主题。

值得说明的是，中文语料我不建议在这里做分词。很多人习惯了先分词再去停用词，但 sentence-transformer 的 tokenizer 自带分词能力，强行分词反而破坏句子结构。先跑一遍聚类，看到主题词表有噪音再回头补清洗，比一开始就做一堆预处理更高效。

3.3 最小训练脚本：训练、看主题、画图一条龙

环境准备好、数据清洗完，就能训练了。下面这个脚本是完整可跑的，直接把模型、UMAP、HDBSCAN 都显式传进去，方便后面调参。

from bertopic import BERTopic from umap import UMAP from hdbscan import HDBSCAN from sentence_transformers import SentenceTransformer docs = [...] # 清洗后的文档列表 embedding_model = SentenceTransformer("sentence-transformers/all-MiniLM-L6-v2") umap_model = UMAP( n_neighbors=15, n_components=5, min_dist=0.0, metric="cosine", random_state=42, ) hdbscan_model = HDBSCAN( min_cluster_size=10, min_samples=1, metric="euclidean", cluster_selection_method="eom", ) topic_model = BERTopic( embedding_model=embedding_model, umap_model=umap_model, hdbscan_model=hdbscan_model, ) topics, probs = topic_model.fit_transform(docs) print(topic_model.get_topic_info().head(10))

这里每个组件都有明确分工。embedding_model负责把文档变成向量，这是语义理解的源头。umap_model负责把高维向量降到 5 维，n_neighbors=15保留局部结构，random_state=42保证可复现。hdbscan_model负责聚类，min_cluster_size=10控制最小主题规模，这个值在你语料变大后要跟着调大。

fit_transform返回两个结果：topics是每篇文档被分配的主题编号，probs是模型对该分配的置信度。注意一点，HDBSCAN 本质是硬聚类，probs的数值参考意义有限，不需要对它做太多解读。

训练完先看主题总览：

topic_info = topic_model.get_topic_info() print(topic_info[["Topic", "Count", "Name"]])

Topic列里的-1表示离群点，也就是 HDBSCAN 认为不属于任何主题的文档。这个后面会专门讲怎么处理。

接着看具体主题的词表：

topic_model.get_topic(0)

返回的是(词, 权重)列表，权重来自 c-TF-IDF。一眼扫过去就能判断这个主题是否合理，比如全是数字或全是停用词，就需要回炉清洗。

画图看整体结构也很简单：

topic_model.visualize_topics()

这个函数会生成一个交互式气泡图，每个气泡代表一个主题，气泡大小对应文档数量。图是用 plotly 渲染的，输出为 HTML，可以直接在浏览器里打开，也可以存成文件发给同事看。

3.4 保存与复用：模型体积、加载和后处理的“后悔药”

训练一次可能要几分钟到几十分钟，如果每次调参都要重新训练，效率太低了。BERTopic 提供了标准的保存和加载接口：

topic_model.save("bertopic_model_dir") loaded_topic_model = BERTopic.load("bertopic_model_dir")

save会创建一个目录，里面包含当前模型参数和内部状态。加载后可以用同样的接口继续分析，但要注意：训练用的文档不会保存在模型里，topics也不在模型中保留。如果你想保存每篇文档的主题分配结果，直接存数组：

import pandas as pd result_df = pd.DataFrame({"doc_id": list(range(len(docs))), "topic": topics}) result_df.to_csv("topic_result.csv", index=False)

我一般会把三样东西一起存：模型目录、主题分配 CSV、get_topic_info()的主题表。这样后面无论是重新画图、分析主题占比，还是给新文档预测主题，都有依据。

给新文档预测主题时，需要重新做嵌入：

new_topics, new_probs = loaded_topic_model.transform(new_docs)

注意transform依然会使用模型内部的 embedding 模型，所以新文档也要先做同样的清洗。如果数据量大，提前算好 embedding 传给transform会更稳妥。

4. 避坑与排查：真实语料上 BERTopic 最容易翻车的五个地方

BERTopic 看起来代码少，但真实项目里翻车点非常集中。以下五条是我在客服工单、电商评论、舆情文章三类语料上都遇到过的问题，按“现象 → 原因 → 解决”写清楚，方便你对号入座。

4.1 主题词全是数字和符号：清洗不到位，HDBSCAN 把噪声也聚成了类

现象：get_topic(0)返回的前几个词是“2021”“12345”“500”，完全看不出主题语义。原因：原始文本里的数字和符号没有处理，嵌入模型把它们当成正常 token，UMAP 降维后这些数字因为格式相似被聚在一起。解决：回到清洗函数，把连续数字替换成占位符：

text = re.sub(r"\b\d{2,}\b", " NUM ", text)

4.2 主题词全是“的、了、在”：嵌入太在意语法词，c-TF-IDF 压不住

现象：主题词表前十个词里有一半是停用词，主题虽然能区分，但词表没法直接展示给业务方。原因：c-TF-IDF 计算的类是全部文档拼起来的，通用词在类内出现次数高，如果该类独有词不够强，停用词就排上来了。解决：不要先删停用词，而是把停用词表传给 CountVectorizer：

from sklearn.feature_extraction.text import CountVectorizer vectorizer = CountVectorizer(stop_words="english", min_df=2) topic_model = BERTopic(vectorizer_model=vectorizer, ...)

英文语料直接传stop_words="english"，中文语料可以传一个自定义停用词 list。min_df=2表示词至少在两类中出现过才进入词表，能过滤掉只在一篇文章里出现的怪词。

4.3 主题每次跑都不一样：UMAP 随机性和模型没锁种子

现象：同一份语料，两次训练得到不同数量的主题，同一篇文档落入不同主题。原因：UMAP 初始化带随机性，HDBSCAN 的聚类顺序也会受影响。解决：给 UMAP 固定random_state=42，同时保存模型作为基准：

umap_model = UMAP(random_state=42, ...)

如果固定了种子还是结果不同，说明语料里部分主题边界太弱，模型本身不稳定。这种情况不要强行调参，而是回到嵌入层换一个更强的模型，比如从 MiniLM 换到 bge。顺手保存一次模型，后面不管怎么重跑都有参照物。

4.4 离群主题太多：HDBSCAN 把所有点都赶出群了

现象：get_topic_info()里-1主题的文档数占比超过 30%，大量文档没有被归类。原因：min_cluster_size设置太大，或者语料本身噪声高，HDBSCAN 倾向于不聚类，把很多稀疏点标为离群点。解决：先调参数，再看要不要用reduce_outliers回填。

new_topics = topic_model.reduce_outliers(docs, topics, strategy="c-tf-idf")

这个函数会把离群点按就近主题的 c-TF-IDF 相似度重新分配，返回一个新的主题数组。strategy可以选c-tf-idf或embeddings，前者快，后者效果略好但需要重新计算嵌入。注意reduce_outliers不会修改原来的topics，需要把返回值接住。

4.5 几万篇文档内存爆掉：embedding 全留在内存里

现象：文档量到两三万时，训练脚本内存冲到十几 G，甚至直接卡死。原因：BERTopic 默认流程会把所有文档一次性编码成向量矩阵，UMAP 和 HDBSCAN 还要在此基础上复制计算。解决：把嵌入计算拆成批量，提前算好再传给fit_transform。

import numpy as np def batch_encode(docs, model, batch_size=256): for i in range(0, len(docs), batch_size): yield model.encode(docs[i:i + batch_size], show_progress_bar=False) embeddings = np.vstack(list(batch_encode(docs, embedding_model))) topic_model.fit_transform(docs, embeddings=embeddings)

这样fit_transform会自动跳过内部嵌入计算，只做降维和聚类。我一般两万篇以内直接np.vstack，超过五万就分批写入.npy文件，再用np.load配合mmap_mode="r"做映射读取，内存压力会小很多。

5. 主题太多怎么办：降维、去冗余和可用性验收

训练完成后，最常遇到的情况是主题数量太多，跑出来三四十个，没法汇报，也没法做后续标注。BERTopic 提供了专门的合并机制，不用重新训练。

5.1 一次把 40 个主题压到 10 个：nr_topics 的正确打开方式

直接调reduce_topics就能在主题层面做合并：

topic_model.reduce_topics(docs, topics, nr_topics=10) topic_model.get_topic_info()

它的原理是计算主题之间的 c-TF-IDF 相似度，把相近主题合并。nr_topics可以传固定数字，也可以传"auto"让模型自动决定。我更推荐传固定数字，可控性强，业务上说要 10 个就给 10 个。这个操作不会动文档嵌入，所以速度很快。做之前先save一份原始模型，方便对比合并前后效果。

5.2 主题词去重：MMR 让前 10 个词不全是同义词

有些主题的词表全是同义词，“价格”“价钱”“售价”反复出现。这不是模型错了，而是 c-TF-IDF 只看权重，不看词汇多样性。给模型加一个 MMR 就能压住：

from bertopic.representation import MaximalMarginalRelevance mmr_model = MaximalMarginalRelevance(diversity=0.4) topic_model = BERTopic(representation_model=mmr_model, ...)

diversity在 0.3 到 0.5 之间比较稳，值越大主题词越多样。这步只影响主题词表的展示，不影响聚类结构，可以放心调。

5.3 验收方法：不要只看图，抽样读文档比什么都管用

主题模型的结果必须回到文档里验证。我通常的做法是：选一个主题，随机抽三到五篇原始文档，通读一遍，确认它们是不是真的在聊同一件事。

import random topic_id = 0 indices = [i for i, t in enumerate(topics) if t == topic_id] for idx in random.sample(indices, min(3, len(indices))): print(docs[idx][:100])

这个方法看似简单，但能拦住大部分“图好看、实际没法用”的模型。我的习惯是把语料版本、嵌入模型名、UMAP 参数、HDBSCAN 参数、随机种子写进一个meta.json放进模型目录，三个月后回来跑，不会对着一个不知道参数的模型干瞪眼。这个流程走完，你手里的 BERTopic 模型就不再是黑匣子，而是一份能落地、能复现、能交付的结果。希望帮到你。

本文还有配套的精品资源，点击获取