用途
NMF 主题建模用于在文本语料库中发现潜在主题、执行无监督主题提取、对比 NMF 与 LDA 结果，以及寻找看似不相关内容领域之间的隐藏联系。
适用场景包括：跨文档语料库（帖子、评论、文章、评论）发现潜在主题；寻找不相关内容领域之间的隐藏连接；语料库拥有 100 篇以上含实质文本的文档；需要可解释、区分度高且重叠最小的主题；使用 TF-IDF 加权文本。
不适用场景：语料库少于 50 篇文档；文档极短（每篇少于 10 个词）且无增强策略；需要带不确定性估计的概率主题分布（应改用 LDA）；需要单一确定性分类（应改用监督方法）。
主要能力
NMF 将 TF-IDF 文档-词矩阵分解为两个非负矩阵：W（文档-主题）与 H（主题-词）。非负约束产生可加、可解释的主题，每个文档是主题的加权混合，每个主题是词的加权混合。相比 LDA，NMF 通常产生更连贯、重叠更少的主题，尤其在短文本上更明显。
文档提供了一个 NMF 与 LDA 的选择决策图：短文本或需要区分度高的主题时用 NMF；需要概率分布时用 LDA；需要语义深度时可考虑 BERTopic 或 Top2Vec。
使用方式
工作流分九步：
- 验证语料库规模与质量：给出语料库规模阈值建议（<50 篇不足；50-100 篇勉强，k 降至 3-5；100-500 篇可行，目标 5-10 个主题；500-2000 篇良好，目标 8-15 个主题；2000+ 篇优秀，可支持 15-25+ 个主题）。质量检查包括平均文档长度应达 20+ 词、去除空文档与重复项等。若语料库不足，应在输出文档中报告而非强行分析。
- 预处理文本并构建 TF-IDF 矩阵：提供 preprocess_text 代码示例，以及 TfidfVectorizer 参数（max_df 0.95、min_df 2、max_features 采用 2000、ngram_range (1, 2)）；建议迭代优化停用词。
- 通过一致性扫描选择主题数 k：提供 compute_coherence_umass 代码，扫描 k 范围（3-21），结合重构误差，用肘部法选择 k。
- 拟合最终 NMF 模型：示例参数为 n_components=k_chosen、init='nndsvda'、random_state=42、max_iter=500、alpha_W=0.1、alpha_H=0.1、l1_ratio=0.5。
- 提取并标注主题（需人工复核）：提供 display_topics 代码，并给出标注指南（基于前 5-7 个词命名；不连贯主题标注为“Incoherent -- Review”而不强行命名）。
- 计算文档-主题分布：基于 W 矩阵，使用 pandas 生成 doc-topic 数据框并判断主导主题；给出权重解读标准（>0.5 强关联；0.2-0.5 中等；<0.1 弱关联）。
- 识别跨主题连接：计算主题相关性、查找桥接文档代码。
- 可选与 LDA 对比验证：LDA 需原始计数而非 TF-IDF，提供 CountVectorizer 与 LatentDirichletAllocation 示例。
- 撰写报告：输出至 docs/analysis/05-nmf-topic-modeling.md，文档给出了包含方法论、一致性得分、发现主题、文档-主题分布、跨主题连接、主题相关性矩阵、LDA 对比、局限与注意事项的完整报告模板。
参数推荐
max_df 0.95；min_df 2-5；max_features 1000-5000（起始 2000）；n_components (k) 8-15（起始 10）；init "nndsvda"；solver "mu"（配合 beta_loss="kullback-leibler" 用于稀疏主题）；alpha_W / alpha_H 0.1；l1_ratio 0.5；random_state 42；每主题展示前 10-15 个词。
限制与注意事项
文档列出常见错误（如凭直觉选 k、跳过停用词迭代、将主题视为确定性类别、无视不连贯主题、对 NMF 使用原始计数、在极小语料库上运行、不做 NMF 与 LDA 对比、不读示例文档就标注主题）及对应修正。同时给出红旗警告：所有主题共享相同主导词（预处理失败）、一致性普遍差、多数文档主导权重 <0.1、单一主题吸收 >60% 文档、重构误差不随 k 增加而下降。边界方面：该技能应产出 8-10 个潜在主题、各 k 的一致性得分、文档-主题分布矩阵、跨主题连接分析、人工复核的主题标签与书面报告；不应在无人工验证时宣称主题代表“真实”类别，不应将 NMF 结果作为文档分类的唯一依据，不应跳过主题可解释性的人工复核，不应给不连贯主题强行命名。
原文在最后部分（Boundaries 末尾）存在截断，相关细节暂未提供。