更新 README.md
This commit is contained in:
parent
5abcc95170
commit
303b368435
1 changed files with 202 additions and 233 deletions
435
README.md
435
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`。*
|
||||
|
|
|
|||
Loading…
Reference in a new issue