diff --git a/README.md b/README.md index e73fd04..7a8e63b 100644 --- a/README.md +++ b/README.md @@ -1,233 +1,202 @@ -# VOC LLM 结构化分析 (VOC_LLM结构化) - -> 基于大语言模型(通义千问 / DashScope)的亚马逊 VOC(Voice of Customer)评论分析流水线:合并 CSV → 清洗 → LLM 结构化 → 向量化 → 聚类与词频 → 生成 HTML 分析报告。 - -## 📖 目录 - -- [核心特性](#-核心特性) -- [环境要求](#-环境要求) -- [安装指南](#-安装指南) -- [使用说明](#-使用说明) -- [示例与输出](#-示例与输出) -- [项目结构](#-项目结构) -- [常见问题](#-常见问题) -- [参与贡献](#-参与贡献) -- [开源协议](#-开源协议) -- [联系方式与鸣谢](#-联系方式与鸣谢) - -## ✨ 核心特性 - -- **七步全流程编排** — `main_voc分析.py` 一键串联:合并、清洗、结构化、向量化、聚类、词频、HTML 报告 -- **断点续跑** — 支持 `--from-step` / `--only-step`,从任意步骤恢复,调试时节省 API 成本 -- **LLM 结构化提取** — 从评论中抽取受众、痛点、方面、观点、情感等字段(`prompts/schema.yaml` 可配置) -- **语义聚类** — UMAP + HDBSCAN 多阶段聚类,辅以 LLM 评估簇质量自动调参 -- **词频分析** — LLM 归纳专有名词 + spaCy 全量词频统计,报告内嵌词云与六类归类 -- **可编辑 Prompt** — `prompts/` 目录下 Markdown / YAML 热加载,产品运营可直接改话术(见 `prompts/README.md`) -- **并行加速** — 聚类与词频在步骤 5–6 由线程池并行执行 - -## 🛠 环境要求 - -| 依赖 | 说明 | -|------|------| -| Python | >= 3.10(推荐 3.10+) | -| pip / venv | 安装 `requirements.txt` 中的包 | -| spaCy 英文模型 | `python -m spacy download en_core_web_sm`(词频步骤必需) | -| 阿里云 DashScope API Key | 结构化、向量化、聚类评估、词频、报告等步骤均需调用 | - -**API Key 配置方式**(任选其一,勿提交到 Git): - -1. 环境变量 `DASHSCOPE_API_KEY` -2. 环境变量 `DASHSCOPE_API_KEY_FILE` 指向单行密钥文件 -3. 项目根目录 `.dashscope_key`(单行,无引号) - -可选:`DASHSCOPE_MODEL`(默认 `qwen3.6-flash`)。 - -## 📦 安装指南 - -1. 克隆项目到本地: - -```bash -git clone <你的仓库地址> -cd VOC_LLM结构化 -``` - -2. 创建虚拟环境并安装依赖(可选但推荐): - -```bash -python3 -m venv 310py -source 310py/bin/activate # Windows: 310py\Scripts\activate -pip install -r requirements.txt -python -m spacy download en_core_web_sm -``` - -3. 配置 API Key: - -```bash -export DASHSCOPE_API_KEY="sk-xxx" -# 或在项目根创建 .dashscope_key(已被 .gitignore 忽略) -``` - -4. 准备原始评论 CSV 目录(目录内所有 `*.csv` 表头须一致),例如亚马逊导出的 `*_realtime.csv`。 - -## 🚀 使用说明 - -### 全流程分析 - -```bash -python3 main_voc分析.py \ - --input-dir "reviews_export" \ - --product "cat deterrent indoor" \ - --industry "Pet Supplies" -``` - -- `--input-dir`:原始 CSV 目录 -- `--product`:产品名(写入结构化任务与报告路径) -- `--industry`:行业名,默认 `Pet Supplies` -- `--keep-db`:保留已有结构化 `voc_*.sqlite`,不覆盖删除 - -### 断点续跑 - -```bash -# 从向量化起续跑(步骤 4 起可省略 --product,自动读结构化库) -python3 main_voc分析.py --from-step 4 --keep-db - -# 仅重跑词频(复用已有 voc_terms.json) -python3 main_voc分析.py --from-step 6 --skip-wordfreq-llm - -# 仅重新生成 HTML 报告 -python3 main_voc分析.py --only-step 7 -``` - -### 其他常用参数 - -| 参数 | 说明 | -|------|------| -| `--clean-intermediates` | 报告成功后删除中间 csv/sqlite,减少内存占用 | -| `--filter-small-clusters` | 报告仅保留簇内评论占比 ≥ 10% 的簇,仅当评论数量过万时启用 | -| `--save-llm-raw` | 将报告 LLM 原文保存为 `report_llm_raw.txt`,调试时使用 | - -### 程序式调用 - -```python -from pathlib import Path -from main_voc分析 import run_voc_analysis - -result = run_voc_analysis( - input_dir=Path("reviews_export"), - industry="Pet Supplies", - product_name="cat deterrent indoor", - from_step=1, - clean_databases=True, -) -print(result["report_html"]) -``` - -### Prompt 验收(无需 API Key) - -```bash -python3 prompts/smoke.py # 检查 prompt 能否加载 -python3 prompts/smoke.py --live # 联调模型(需 API Key) -``` - -### 可选变体:jieba 词频 - -中文或需 jieba 分词时,可使用 `main_voc分析_jieba.py`(词频走 `词频_jieba.py`,其余步骤与主流程一致)。 - ---- - -更详细的步骤说明、算法与 SQLite 约定见 **[main_voc分析.md](main_voc分析.md)**。 - -## 📸 示例与输出 - -流程结束后,主要产物如下: - -| 路径 | 说明 | -|------|------| -| `merged_reviews.csv` | 多文件合并结果 | -| `merged_reviews_cleaned.csv` | 清洗、去重后的评论 | -| `voc_structured.sqlite` | LLM 结构化结果 | -| `voc_embeddings.sqlite` | 256 维向量 | -| `voc_clustering.sqlite` | 多阶段聚类标签 | -| `output/voc_terms.json` | 专有名词 / 停用词 | -| `output/word_freq.csv` | 全量词频表 | -| `output/{product}/{product}_voc_report.html` | **最终 VOC 分析报告**(词云、词频、分簇、AI 正文) | - -stdout 会打印 JSON 摘要(含 `report_html` 等键)。 - -> 建议在 README 或文档中补充一张 `*_voc_report.html` 在浏览器中打开的截图,便于新成员快速理解交付物形态。 - -## 📂 项目结构 - -```text -VOC_LLM结构化/ -├── main_voc分析.py # 主流程编排入口(七步) -├── main_voc分析_jieba.py # 词频使用 jieba 的变体入口 -├── main_voc分析.md # 流程与算法详细说明 -├── 合并评论数据.py # 步骤 1:多 CSV 合并 -├── content清洗.py # 步骤 2:评论清洗与去重 -├── 结构化_server.py # 步骤 3:LLM 结构化入库 -├── 结构化_Prompt.py # 结构化 prompt 组装 -├── 向量化.py # 步骤 4:Embedding 入库 -├── 聚类.py # 步骤 5:UMAP + HDBSCAN -├── 词频.py / 词频_jieba.py # 步骤 6:术语提取 + 词频 -├── voc_report.py # 步骤 7:HTML 报告生成 -├── prompts/ # 可编辑 prompt、schema、配置 -│ ├── README.md -│ ├── schema.yaml -│ ├── extraction/ report/ word_freq/ -│ └── loader.py -├── requirements.txt -├── output/ # 报告与词频输出(gitignore) -└── README.md # 本文件 -``` - -## ❓ 常见问题 - -**Q:提示缺少 `DASHSCOPE_API_KEY`?** -A:按上文配置环境变量或 `.dashscope_key`,并确认密钥未提交到仓库。 - -**Q:步骤 4 报错找不到 `product`?** -A:从步骤 1–3 完整跑过,或确保 `voc_structured.sqlite` 中已有最新 job;步骤 4 起可省略 `--product`。 - -**Q:词频步骤报 spaCy 模型缺失?** -A:执行 `python -m spacy download en_core_web_sm`。 - -**Q:合并 CSV 失败?** -A:确保 `--input-dir` 下所有 CSV 表头完全一致。 - -**Q:修改 LLM 话术后报告解析失败?** -A:勿修改 `prompts/schema.yaml` 中 `report.markers` 四段标记名;改完运行 `python3 prompts/smoke.py` 验收。 - -## 🤝 参与贡献 - -欢迎提交 Issue 与 Pull Request。建议流程: - -1. Fork 本仓库 -2. 创建特性分支:`git checkout -b feature/your-feature` -3. 提交更改:`git commit -m '简要说明变更'` -4. 推送并发起 Pull Request - -修改主流程或 CLI 时,请同步更新 `main_voc分析.md`;修改 `prompts/` 时请遵循 `prompts/README.md` 中的占位符与 schema 约定。 - -**安全提醒**:勿提交 `.dashscope_key`、`.env`、真实评论 CSV、`*.sqlite` 及 `output/` 产物(见 `.gitignore`)。 - -## 📄 开源协议 - -本项目尚未在仓库中附带 `LICENSE` 文件。若为内部项目,请按组织规范使用;若计划开源,请补充协议文件(如 MIT)并更新本节链接。 - -## ✉️ 联系方式与鸣谢 - -- **详细技术文档**:[main_voc分析.md](main_voc分析.md)、[prompts/README.md](prompts/README.md) -- **作者 / 维护者**:请在此填写团队或联系人 -- **项目仓库**:请在此填写 Git 远程地址 - -### 鸣谢 - -- [阿里云 DashScope / 通义千问](https://help.aliyun.com/zh/model-studio/) — Chat 与 Embedding API -- [UMAP](https://umap-learn.readthedocs.io/)、[HDBSCAN](https://hdbscan.readthedocs.io/) — 聚类管线 -- [spaCy](https://spacy.io/) — 英文词频与 NLP -- [Standard Readme](https://github.com/RichardLitt/standard-readme) — README 结构参考 - ---- - -*README 与 `main_voc分析.py` 七步流程保持一致;深度说明请参阅 `main_voc分析.md`。* +# VOC LLM 结构化分析 (VOC_LLM结构化) + +> 基于大语言模型(通义千问 / DashScope)的亚马逊 VOC(Voice of Customer)评论分析流水线:合并 CSV → 清洗 → LLM 结构化 → 向量化 → 聚类与词频 → 生成 HTML 分析报告。 + +## 📖 目录 + +- [核心特性](#-核心特性) +- [环境要求](#-环境要求) +- [安装指南](#-安装指南) +- [使用说明](#-使用说明) +- [示例与输出](#-示例与输出) +- [项目结构](#-项目结构) +- [常见问题](#-常见问题) + + +## ✨ 核心特性 + +- **七步全流程编排** — `main_voc分析.py` 一键串联:合并、清洗、结构化、向量化、聚类、词频、HTML 报告 +- **断点续跑** — 支持 `--from-step` / `--only-step`,从任意步骤恢复,调试时节省 API 成本 +- **LLM 结构化提取** — 从评论中抽取受众、痛点、方面、观点、情感等字段(`prompts/schema.yaml` 可配置) +- **语义聚类** — UMAP + HDBSCAN 多阶段聚类,辅以 LLM 评估簇质量自动调参 +- **词频分析** — LLM 归纳专有名词 + spaCy 全量词频统计,报告内嵌词云与六类归类 +- **可编辑 Prompt** — `prompts/` 目录下 Markdown / YAML 热加载,产品运营可直接改话术(见 `prompts/README.md`) +- **并行加速** — 聚类与词频在步骤 5–6 由线程池并行执行 + +## 🛠 环境要求 + +| 依赖 | 说明 | +|------|------| +| Python | >= 3.10(推荐 3.10+) | +| pip / venv | 安装 `requirements.txt` 中的包 | +| spaCy 英文模型 | `python -m spacy download en_core_web_sm`(词频步骤必需) | +| 阿里云 DashScope API Key | 结构化、向量化、聚类评估、词频、报告等步骤均需调用 | + +**API Key 配置方式**(任选其一,勿提交到 Git): + +1. 环境变量 `DASHSCOPE_API_KEY` +2. 环境变量 `DASHSCOPE_API_KEY_FILE` 指向单行密钥文件 +3. 项目根目录 `.dashscope_key`(单行,无引号) + +可选:`DASHSCOPE_MODEL`(默认 `qwen3.6-flash`)。 + +## 📦 安装指南 + +1. 克隆项目到本地: + +```bash +git clone <你的仓库地址> +cd VOC_LLM结构化 +``` + +2. 创建虚拟环境并安装依赖(可选但推荐): + +```bash +python3 -m venv 310py +source 310py/bin/activate # Windows: 310py\Scripts\activate +pip install -r requirements.txt +python -m spacy download en_core_web_sm +``` + +3. 配置 API Key: + +```bash +export DASHSCOPE_API_KEY="sk-xxx" +# 或在项目根创建 .dashscope_key(已被 .gitignore 忽略) +``` + +4. 准备原始评论 CSV 目录(目录内所有 `*.csv` 表头须一致),例如亚马逊导出的 `*_realtime.csv`。 + +## 🚀 使用说明 + +### 全流程分析 + +```bash +python3 main_voc分析.py \ + --input-dir "reviews_export" \ + --product "cat deterrent indoor" \ + --industry "Pet Supplies" +``` + +- `--input-dir`:原始 CSV 目录 +- `--product`:产品名(写入结构化任务与报告路径) +- `--industry`:行业名,默认 `Pet Supplies` +- `--keep-db`:保留已有结构化 `voc_*.sqlite`,不覆盖删除 + +### 断点续跑 + +```bash +# 从向量化起续跑(步骤 4 起可省略 --product,自动读结构化库) +python3 main_voc分析.py --from-step 4 --keep-db + +# 仅重跑词频(复用已有 voc_terms.json) +python3 main_voc分析.py --from-step 6 --skip-wordfreq-llm + +# 仅重新生成 HTML 报告 +python3 main_voc分析.py --only-step 7 +``` + +### 其他常用参数 + +| 参数 | 说明 | +|------|------| +| `--clean-intermediates` | 报告成功后删除中间 csv/sqlite,减少内存占用 | +| `--filter-small-clusters` | 报告仅保留簇内评论占比 ≥ 10% 的簇,仅当评论数量过万时启用 | +| `--save-llm-raw` | 将报告 LLM 原文保存为 `report_llm_raw.txt`,调试时使用 | + +### 程序式调用 + +```python +from pathlib import Path +from main_voc分析 import run_voc_analysis + +result = run_voc_analysis( + input_dir=Path("reviews_export"), + industry="Pet Supplies", + product_name="cat deterrent indoor", + from_step=1, + clean_databases=True, +) +print(result["report_html"]) +``` + +### Prompt 验收(无需 API Key) + +```bash +python3 prompts/smoke.py # 检查 prompt 能否加载 +python3 prompts/smoke.py --live # 联调模型(需 API Key) +``` + +### 可选变体:jieba 词频 + +中文或需 jieba 分词时,可使用 `main_voc分析_jieba.py`(词频走 `词频_jieba.py`,其余步骤与主流程一致)。 + +--- + +更详细的步骤说明、算法与 SQLite 约定见 **[main_voc分析.md](main_voc分析.md)**。 + +## 📸 示例与输出 + +流程结束后,主要产物如下: + +| 路径 | 说明 | +|------|------| +| `merged_reviews.csv` | 多文件合并结果 | +| `merged_reviews_cleaned.csv` | 清洗、去重后的评论 | +| `voc_structured.sqlite` | LLM 结构化结果 | +| `voc_embeddings.sqlite` | 256 维向量 | +| `voc_clustering.sqlite` | 多阶段聚类标签 | +| `output/voc_terms.json` | 专有名词 / 停用词 | +| `output/word_freq.csv` | 全量词频表 | +| `output/{product}/{product}_voc_report.html` | **最终 VOC 分析报告**(词云、词频、分簇、AI 正文) | + +stdout 会打印 JSON 摘要(含 `report_html` 等键)。 + +> 建议在 README 或文档中补充一张 `*_voc_report.html` 在浏览器中打开的截图,便于新成员快速理解交付物形态。 + +## 📂 项目结构 + +```text +VOC_LLM结构化/ +├── main_voc分析.py # 主流程编排入口(七步) +├── main_voc分析_jieba.py # 词频使用 jieba 的变体入口 +├── main_voc分析.md # 流程与算法详细说明 +├── 合并评论数据.py # 步骤 1:多 CSV 合并 +├── content清洗.py # 步骤 2:评论清洗与去重 +├── 结构化_server.py # 步骤 3:LLM 结构化入库 +├── 结构化_Prompt.py # 结构化 prompt 组装 +├── 向量化.py # 步骤 4:Embedding 入库 +├── 聚类.py # 步骤 5:UMAP + HDBSCAN +├── 词频.py / 词频_jieba.py # 步骤 6:术语提取 + 词频 +├── voc_report.py # 步骤 7:HTML 报告生成 +├── prompts/ # 可编辑 prompt、schema、配置 +│ ├── README.md +│ ├── schema.yaml +│ ├── extraction/ report/ word_freq/ +│ └── loader.py +├── requirements.txt +├── output/ # 报告与词频输出(gitignore) +└── README.md # 本文件 +``` + +## ❓ 常见问题 + +**Q:提示缺少 `DASHSCOPE_API_KEY`?** +A:按上文配置环境变量或 `.dashscope_key`,并确认密钥未提交到仓库。 + +**Q:步骤 4 报错找不到 `product`?** +A:从步骤 1–3 完整跑过,或确保 `voc_structured.sqlite` 中已有最新 job;步骤 4 起可省略 `--product`。 + +**Q:词频步骤报 spaCy 模型缺失?** +A:执行 `python -m spacy download en_core_web_sm`。 + +**Q:合并 CSV 失败?** +A:确保 `--input-dir` 下所有 CSV 表头完全一致。 + +**Q:修改 LLM 话术后报告解析失败?** +A:勿修改 `prompts/schema.yaml` 中 `report.markers` 四段标记名;改完运行 `python3 prompts/smoke.py` 验收。 + + +--- + +*README 与 `main_voc分析.py` 七步流程保持一致;深度说明请参阅 `main_voc分析.md`。*