8.8 KiB
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）：
- 环境变量
DASHSCOPE_API_KEY - 环境变量
DASHSCOPE_API_KEY_FILE指向单行密钥文件 - 项目根目录
.dashscope_key（单行，无引号）
可选：DASHSCOPE_MODEL（默认 qwen3.6-flash）。
📦 安装指南
- 克隆项目到本地：
git clone <你的仓库地址>
cd VOC_LLM结构化
- 创建虚拟环境并安装依赖（可选但推荐）：
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
- 配置 API Key：
export DASHSCOPE_API_KEY="sk-xxx"
# 或在项目根创建 .dashscope_key（已被 .gitignore 忽略）
- 准备原始评论 CSV 目录（目录内所有
*.csv表头须一致），例如亚马逊导出的*_realtime.csv。
🚀 使用说明
全流程分析
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，不覆盖删除
断点续跑
# 从向量化起续跑（步骤 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，调试时使用 |
程序式调用
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）
python3 prompts/smoke.py # 检查 prompt 能否加载
python3 prompts/smoke.py --live # 联调模型（需 API Key）
可选变体：jieba 词频
中文或需 jieba 分词时，可使用 main_voc分析_jieba.py（词频走 词频_jieba.py，其余步骤与主流程一致）。
更详细的步骤说明、算法与 SQLite 约定见 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在浏览器中打开的截图，便于新成员快速理解交付物形态。
📂 项目结构
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。建议流程：
- Fork 本仓库
- 创建特性分支：
git checkout -b feature/your-feature - 提交更改：
git commit -m '简要说明变更' - 推送并发起 Pull Request
修改主流程或 CLI 时，请同步更新 main_voc分析.md；修改 prompts/ 时请遵循 prompts/README.md 中的占位符与 schema 约定。
安全提醒：勿提交 .dashscope_key、.env、真实评论 CSV、*.sqlite 及 output/ 产物（见 .gitignore）。
📄 开源协议
本项目尚未在仓库中附带 LICENSE 文件。若为内部项目，请按组织规范使用；若计划开源，请补充协议文件（如 MIT）并更新本节链接。
✉️ 联系方式与鸣谢
- 详细技术文档：main_voc分析.md、prompts/README.md
- 作者 / 维护者：请在此填写团队或联系人
- 项目仓库：请在此填写 Git 远程地址
鸣谢
- 阿里云 DashScope / 通义千问 — Chat 与 Embedding API
- UMAP、HDBSCAN — 聚类管线
- spaCy — 英文词频与 NLP
- Standard Readme — README 结构参考
README 与 main_voc分析.py 七步流程保持一致；深度说明请参阅 main_voc分析.md。