# 基于DeepSeek的LLMTopcic分析

**Repository Path**: HarryJWC/DeepSeekLLMTopcicAna

## Basic Information

- **Project Name**: 基于DeepSeek的LLMTopcic分析
- **Description**: 基于DeepSeek的LLMTopcic分析
- **Primary Language**: Python
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-11-29
- **Last Updated**: 2026-02-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# TopicDeepSeek: 基于大语言模型的主题挖掘工具 V7.1 JW❤QX @小红书drharry
-----

这是一个基于 Python 的图形化（GUI）深度文本挖掘工具。不同于传统的 LDA 或 BERTopic，本工具复现并扩展了 TopicGPT 框架，利用 DeepSeek 大语言模型的强大语义理解能力，实现“人机协同”的主题生成、文档归类、证据引用以及变量因果关系推理。本工具专为社会科学研究者设计，旨在通过低代码操作，实现从非结构化文本到结构化变量及其因果网络的转化。

⚠️ **重要免责声明与设计原理**
**设计理论来源**: 本程序的核心逻辑严格遵循 

--1）Pham 等人发表的预印本论文 《TopicGPT: A Prompt-based Topic Modeling Framework》 (arXiv:2311.01449) 及其相关研究。

--2）Ties de Kok 发表的论文 《ChatGPT for Textual Analysis? How to use Generative LLMs in Accounting Research 》（期刊：Management Science，UTD）


**探索性功能**: 本工具中的 “因果关系分析” > > 这里输入引用文本与 “变量概念化” 属于基于 LLM 逻辑推理的探索性功能。虽然模型能提供令人惊艳的逻辑链条，但请用户务必结合专业知识自行分辨结果的有效性。


**非商业用途**: 本项目代码仅供学术交流与探索使用。

## 1. API 申请与成本预警 (必读!)
本工具的核心驱动力来自 DeepSeek 大模型 API，因此无法离线运行，且会产生 API 调用费用。

### 1.1 如何获取 DeepSeek API
访问 DeepSeek 开放平台: https://platform.deepseek.com/
注册账号并进行实名认证。
在“API Keys”栏目中创建一个新的 API Key（格式通常为 sk- 开头）。
将此 Key 填入软件界面的“参数配置”页中。

### 1.2 💰 成本与 Token 消耗预警
这个软件运行是非常消耗 Token 的！请务必注意您的余额！
**消耗原理**:
- **主题生成**: 需要抽取部分文档发送给 LLM。
- **主题分配 (最贵)**: LLM 需要阅读每一篇文档，并结合所有主题列表进行推理。如果您有 10,000 篇长文档，LLM 就需要阅读 10,000 次。
- **因果分析**: 涉及复杂的 Prompt 上下文推理，Token 消耗量大。

**建议**:
初次使用时，请务必先用小样本数据（如 50-100 条）跑通全流程，估算成本。
在“参数配置”中合理设置“样本大小”和“并发线程数”。

## 2. 环境搭建与安装
### 推荐使用 Windows 11 系统+Pycharm。
### Windows11+Pycharm环境下测试通过，MAC OS等其他系统可能出现严重BUG

### 2.1 安装依赖
确保您已安装 Python 3.8+。
在pycharm中运行以下命令安装所需库：

```bash
pip install pandas numpy scikit-learn matplotlib seaborn plotly sentence-transformers requests customtkinter python-dotenv networkx openpyxl xlsxwriter ttkthemes kaleido
```
注意：1)kaleido 用于导出静态图片，如安装失败可跳过，但将无法保存 PNG 格式图片（只能保存 HTML）。

### 2.2 运行程序
直接运行主程序脚本：python TopicDeepSeek.py
## 3. 参数配置完全指南 (Parameter Guide)
软件界面包含大量参数，以下是详细的学术定义与设置建议：

### 3.1 LLM 模型与数据源
- **Temperature (0.1-1.0)**: 控制 LLM 输出的随机性。推荐: 0.1。主题分析需要结果稳定，不建议调高。
- **Top P**: 核采样参数。推荐: 1.0。
- **输出结果语言**: 控制 LLM 生成的主题名称和描述的语言。选项: zh (中文), en (英文)。

### 3.2 嵌入模型 (Embedding Model)
用于计算主题之间的余弦相似度（Cosine Similarity），影响主题合并的效果。
- **预设模型**:
  - all-MiniLM-L6-v2: 速度快，英文效果好（默认）。
  - paraphrase-multilingual-MiniLM-L12-v2: 支持多语言。
  - shibing624/text2vec-base-chinese: 中文推荐。
- **自定义模型**: 勾选后可输入 HuggingFace 模型 ID 或本地文件夹路径。

### 3.3 算法核心参数
- **主题生成抽样数 (Sample Size)**: Step 1 中，从总数据中抽取多少条文档给 LLM 看以“发现”初始主题。建议: 50 - 200。太多会不仅慢且费钱，且边际效益递减。
- **并发工作线程**: 同时向 API 发送请求的数量。建议: 3 - 5。过高可能触发 API Rate Limit (429 Error)。
- **相似度阈值 (Similarity Threshold)**: Step 3 中，两个主题的 Embedding 相似度大于多少时，触发“合并”询问。建议: 0.5 - 0.75。越低合并越激进。
- **精炼循环次数**: Step 3 中，反复执行“计算相似度 -> 询问合并”的轮数。建议: 3。
- **最低主题频率**: Step 3 和 Step 6 中，文档数少于此值的主题将被视为“噪音”被剔除或忽略。建议: 5。

### 3.4 高级因果与层次参数
- **因果/概念化最小支持数**: Step 6/7 中，只有当一个主题/变量至少被这么多条引用（Quotes）支持时，才会被纳入因果分析。目的: 过滤掉证据不足的边缘观点，防止 LLM 瞎编因果。
- **多标签分配 (Multi-label)**: Step 2 中，是否允许一篇文档属于多个主题。建议: False (单标签) 更清晰；True 更符合真实语义复杂性。

## 4. 核心功能流程详解
本工具将 TopicGPT 的流程具象化为 7 个步骤，建议按顺序执行：

### 第一阶段：主题构建 (Topic Generation)
- **Step 1: 主题生成**: 从文档中抽取样本，引导 LLM 识别核心议题。
  - **原理**: 依据论文中的 Generation Prompt，让模型在阅读文档时动态创建或复用主题。
- **Step 2: 主题分配**: 将每一篇文档归类到最合适的主题，并强制要求 LLM 提供原文引用作为证据。
  - **亮点**: 解决了传统 LDA 模型“无法解释为什么归为此类”的黑箱问题。
- **Step 3: 主题精炼**: 利用 Embedding 相似度和 LLM 逻辑判断，自动合并语义重复的主题，剔除低频噪音。

### 第二阶段：深度分析 (Deep Analysis)
- **Step 4: 层次主题 (Hierarchy)**: 生成父主题与子主题的树状结构，挖掘话题的颗粒度。
- **Step 6: 主题因果分析 (Causality)**: [高阶功能] 分析不同主题之间是否存在逻辑上的因果链条（如“环境污染”->“政策出台”）。
- **Step 7: 变量概念化 (Conceptualization)**: [高阶功能] 将自然语言主题转化为社会科学中的“潜变量”或“显变量”，并分析变量间的调节或中介效应。

### 第三阶段：可视化 (Visualization)
- **Step 5: 生成报告**: 一键生成 HTML 交互式图表与 Excel 统计表。

## 5. 输出文件详解 (Output Details)
程序运行完毕后，topicgpt_output 文件夹内将生成以下文件，这是您科研分析的宝库：

### 📊 基础数据表 (Excel)
|文件名|阶段|作用与内容|
| ---- | ---- | ---- |
|step1_topics.xlsx|Step 1|初始生成的主题列表及其描述。|
|step2_topic_assignments.xlsx|Step 2|核心数据。包含所有文档 ID、原始内容、分配的主题、引用证据 (Quotes)。|
|step3_refined_topics.xlsx|Step 3|经过合并、去重、剔除低频后的最终主题列表。|
|step3_merge_statistics.xlsx|Step 3|记录了合并了多少对主题，剔除了多少低频主题。|
|step4_topic_hierarchy.xlsx|Step 4|父主题与子主题的层级对应关系表。|
|step5_complete_topic_summary.xlsx|Step 5|最终汇总表。包含主题名、描述、文档数、占比、代表性文档和子主题概览。|

### 🔗 因果与变量分析表
|文件名|阶段|作用与内容|
| ---- | ---- | ---- |
|step6_topic_causality_relations.xlsx|Step 6|主题级因果表。列出 Source Topic -> Target Topic 及其关系类型（单向/双向）和证据。|
|step7_variable_conceptualizations.xlsx|Step 7|变量定义表。将主题转化为变量（潜变量/显变量），并给出操作性定义。|
|step7_variable_causality_relations.xlsx|Step 7|变量级因果表。基于转化后的变量进行的因果推断。|

### 📈 可视化图表 (Visualizations 文件夹)
所有图表均为交互式 HTML，部分包含 PNG 静态图。
|文件名|图表类型|解读方式|
| ---- | ---- | ---- |
|viz_topic_hierarchy_sunburst.html|旭日图|内圈为父主题，外圈为子主题，面积代表文档数量。点击可下钻。|
|viz_topic_similarity_matrix_refined.html|热力图|展示精炼后主题两两之间的语义相似度。|
|viz_topic_embeddings_all.html|t-SNE 散点图|主题在语义空间的分布。距离越近，语义越相似；气泡越大，热度越高。|
|topic_causality_network.html|网络拓扑图|因果网络。节点是主题，连线是因果关系，箭头指示影响方向。|
|viz_topic_evolution.html|折线图|展示随着处理步骤进行，主题数量的收敛过程。|

## 6. 常见问题 (Q&A)
**Q1: 为什么程序运行到一半卡住了？**
A: 可能是网络问题导致连接 DeepSeek API 超时。程序内置了重试机制，但如果网络波动过大，建议检查代理或稍后重试。

**Q2: 为什么生成的主题很多是重复的？**
A: 请执行 Step 3 (主题精炼)。LLM 在生成阶段倾向于发散，精炼阶段利用向量相似度（Embedding）和 LLM 逻辑判断进行合并是 TopicGPT 框架的标准流程。

**Q3: “自定义嵌入模型”有什么用？**
A: 如果您处理的是中文专业领域文本（如医疗、法律），预设的通用模型可能对语义相似度判断不准。您可以去 HuggingFace 下载专门的中文 Embedding 模型并在配置页指定路径，以提升合并效果。

**Q4: 生成的因果关系靠谱吗？**
A: 仅供参考。这是基于文本内容的逻辑推断，而非统计学上的因果验证。它能帮您构建假设，但不能替代实证研究。

## 7. 引用与致谢
**核心算法**: Pham, C. M., Hoyle, A., Sun, S., Resnik, P., & Iyyer, M. (2023). TopicGPT: A Prompt-based Topic Modeling Framework. arXiv preprint arXiv:2311.01449.

**GUI 实现**: 本工具由 drharry (小红书) 修改并封装，原作者保留代码解释权。

**Terms of Use**: 本项目遵循学术与教育用途协议，严禁用于商业黑盒产品封装。