BERTopic 自定义参数调整指南
参数调整有风险，调参需谨慎！
- 不当的参数组合可能导致空结果或无意义输出，浪费算力
- 建议新手用户使用预设策略（保守/平衡/激进）
- 只有当你理解每个参数含义时，才使用自定义模式
- 每次调参都会消耗算力，请先在小数据集上测试
参数重要性排序
1. 主题数量控制
控制最终生成的主题数量，这是最重要的参数之一
主题数量模式 (topicCountMode)
选择自动发现还是手动指定主题数量
建议
新手建议使用自动发现，有经验用户可以根据业务需求手动指定
固定主题数量 (fixedTopicCount)
当选择手动指定时，设置具体的主题数量
注意事项
- •设置过少（<3）：可能丢失重要信息
- •设置过多（>文档数/5）：可能产生碎片化主题
- •建议范围：文档数的10%-30%
建议
根据文档内容复杂度设置，一般5-15个主题较为合适
2. 文本向量化参数 ⚠️ 极易出错
控制文本特征提取，影响主题词汇的质量和数量
词频过滤参数 - 重点关注！
最小文档频率 (min_df)
词汇至少在多少个文档中出现才被保留
注意事项
- •过大：过滤掉重要的低频词汇
- •与文档数量相关：小数据集用1-3，大数据集用5-10
建议
小数据集用1，大数据集（>1000文档）用3-5
参数验证公式
有效词汇计算：
保留词汇 = 在 [min_df × 文档总数] 范围内出现的词汇
安全检查：
min_df × 文档总数
⚠️ 如果不满足上述条件，将没有词汇被保留，导致空结果！
举例说明：
假设有100个文档，min_df=5
→ 保留在5到90个文档中出现的词汇
→ 过滤掉只在1-4个文档中出现的生僻词
其他向量化参数
向量化类型 (vectorizer_type)
文本特征提取方式
建议
TF-IDF适合大多数场景，能更好识别主题特征词
N-gram范围 (ngram_range)
考虑的词汇组合长度范围
注意事项
- •[1,1]：只考虑单词
- •[1,2]：考虑单词和词组，推荐设置
- •[1,3+]：包含长词组，可能增加噪声
建议
[1,2] 平衡单词和短语信息
3. HDBSCAN聚类参数
控制密度聚类算法的行为，直接决定主题的形成
最小聚类大小 (min_cluster_size)
形成一个主题至少需要的文档数量
注意事项
- •过小（<3）：产生大量小主题，可能是噪声
- •过大（>文档数/5）：主题过少，信息粗糙
- •建议：文档数的3%-10%
建议
小数据集用3-5，大数据集用10-20
最小样本数 (min_samples)
核心点周围的最小邻居数，控制聚类密度要求
建议设置为null或min_cluster_size的一半
聚类选择方法 (cluster_selection_method)
从聚类层次结构中选择最终聚类的策略
EOM适合大多数场景
4. UMAP降维参数
控制高维文档嵌入向量的降维过程，影响主题的空间分布
邻居数量 (n_neighbors)
每个点考虑的邻居数量，控制局部vs全局结构平衡
• 过小(<5)：保留局部结构，可能产生孤立簇
• 过大(>30)：关注全局结构，可能丢失细节
建议：10-20，小数据集用5-10
降维维度 (n_components)
降维后的目标维度数
• 过小(<3)：信息丢失严重
• 过大(>10)：降维效果不明显
建议：默认5维适合大多数场景
最小距离 (min_dist)
降维后点之间的最小距离，控制聚集程度
• 过小(<0.01)：点过度聚集，难以区分
• 过大(>0.3)：点过度分散，失去聚类结构
建议：0.05-0.15适合大多数文本分析任务
其他UMAP参数
5. 距离度量设置
控制不同阶段使用的距离计算方法，影响主题的形成和边界
HDBSCAN距离 (hdbscan_distance)
聚类算法使用的距离度量，直接影响主题划分
建议
新手建议使用欧氏距离，最稳定且适合大多数场景
嵌入距离 (embedding_distance)
文档嵌入向量间的距离计算方式
推荐：余弦距离（适合文本）
UMAP距离 (umap_distance)
UMAP降维过程中使用的距离度量
推荐：与嵌入距离保持一致
6. 其他设置
影响主题表示和性能的辅助参数
多样性参数 (diversity)
主题词汇的多样性程度，影响主题词的选择
• 0：选择最相关的词汇
• 1：最大化词汇多样性
建议：默认0.1适合大多数场景
计算概率 (calculate_probabilities)
是否计算文档属于每个主题的概率
• 开启：提供更丰富信息
• 关闭：信息较少
常见问题与调参建议
常见错误情况
结果为空
通常是min_df设置过大，或者min_cluster_size过大
主题过多
min_cluster_size过小，建议增大到文档数的5-10%
主题质量差
检查n_neighbors和min_dist是否合理
算法崩溃
通常是UMAP参数不兼容，检查n_neighbors是否小于文档数
调参建议流程
- 1.先用预设策略测试，了解数据特征
- 2.确定合适的主题数量（手动指定或自动）
- 3.重点检查min_df，确保参数合理
- 4.调整min_cluster_size控制主题粒度
- 5.最后调整UMAP和距离度量参数
- • 小步调整：每次只改动1-2个参数
- • 记录实验：记录每次调整的效果
- • 先小后大：在小数据集上验证参数
- • 关注核心：主题数量和聚类大小是最重要的参数
- • 词频参数优先：min_df是最容易出错的参数
- • 保守策略：不确定时选择更保守的参数设置
参数重要性排序（按出错概率）
- • min_df
- • min_cluster_size
- • n_neighbors
- • n_components
- • hdbscan_distance
- • diversity
- • min_dist
- • calculate_probabilities
- • max_features