VOC LLM 结构化分析 (VOC_LLM结构化)

基于大语言模型（DeepSeek OpenAI 兼容 API）与本地 MLX 向量的亚马逊 VOC（Voice of Customer）评论分析流水线：合并 CSV → 清洗 → LLM 结构化 → 向量化 → 聚类与词频 → 生成 HTML 分析报告。

📖 目录

• 核心特性
• 环境要求
• 安装指南
• 使用说明
• 示例与输出
• 项目结构
• 常见问题
• 参与贡献
• 开源协议
• 联系方式与鸣谢

✨ 核心特性

• 七步全流程编排 — main_voc分析.py 一键串联：合并、清洗、结构化、向量化、聚类、词频、HTML 报告
• 断点续跑 — 支持 --from-step / --only-step，从任意步骤恢复，调试时节省 API 成本
• LLM 结构化提取 — 从评论中抽取受众、痛点、方面、观点、情感等字段（prompts/schema.yaml 可配置）
• 本地向量化 — Apple Silicon 上运行 Qwen3-Embedding-4B-mxfp8（MLX），无需云端 Embedding API
• 语义聚类 — UMAP + HDBSCAN 多阶段聚类，辅以 LLM 评估簇质量自动调参
• 词频分析 — LLM 归纳专有名词 + spaCy 全量词频统计，报告内嵌词云与六类归类
• 可编辑 Prompt — prompts/ 目录下 Markdown / YAML 热加载，产品运营可直接改话术（见 prompts/README.md）
• 并行加速 — 聚类与词频在步骤 5–6 由线程池并行执行；结构化批间并行（默认 8 路）

🛠 环境要求

依赖	说明
Python	>= 3.10（推荐 3.12，项目内 310py）
pip / uv	安装 requirements.txt 中的包
spaCy 英文模型	经 uv pip 安装 en-core-web-sm（见安装指南，词频步骤必需）
DeepSeek API Key	结构化、聚类评估、词频、报告等 Chat 步骤
本地 Embedding 模型	目录 Qwen3-Embedding-4B-mxfp8/（约 4GB，已 gitignore，需自行下载）
Apple Silicon	本地向量化依赖 MLX（M 系列芯片）

Chat API Key（任选其一，勿提交到 Git）：

1. 环境变量 DEEPSEEK_API_KEY
2. 环境变量 DEEPSEEK_API_KEY_FILE 指向单行密钥文件
3. 项目根目录 .deepseek_key（单行，无引号）

可选：DEEPSEEK_MODEL（默认 deepseek-v4-pro）、DEEPSEEK_BASE_URL（默认 https://api.deepseek.com）。

📦 安装指南

1. 克隆项目到本地：

git clone https://git.onesvm.com/whoops/amz_review_analyse.git
cd amz_review_analyse   # 或你的本地目录名

2. 创建虚拟环境并安装依赖（推荐）：

uv venv 310py --python 3.12
uv pip install --python 310py/bin/python -r requirements.txt
uv pip install --python 310py/bin/python \
  "en-core-web-sm @ https://github.com/explosion/spacy-models/releases/download/en_core_web_sm-3.8.0/en_core_web_sm-3.8.0-py3-none-any.whl"

3. 配置 DeepSeek API Key：

export DEEPSEEK_API_KEY="sk-xxx"
# 或在项目根创建 .deepseek_key（已被 .gitignore 忽略）

4. 准备本地 Embedding 模型（首次向量化前）：

将 Qwen3-Embedding-4B-mxfp8 放到项目根，或设置 VOC_EMBED_MODEL_PATH 指向模型目录。可从 Hugging Face 下载。

5. 准备原始评论 CSV 目录（目录内所有 *.csv 表头须一致），例如亚马逊导出的 *_realtime.csv。

🚀 使用说明

全流程分析

./310py/bin/python main_voc分析.py \
  --input-dir "reviews_export" \
  --product "cat deterrent indoor" \
  --industry "Pet Supplies"

• --input-dir：原始 CSV 目录
• --product：产品名（写入结构化任务与报告路径）
• --industry：行业名，默认 -（可在步骤 3 写入库）
• --keep-db：保留已有结构化 voc_*.sqlite，不覆盖删除

加速（批间并行，默认已开启）

步骤 3 结构化默认多批并行 Chat 请求；步骤 4 向量为本地 MLX 串行批处理（勿对同一模型多线程）：

# 全流程
./310py/bin/python main_voc分析.py --input-dir "reviews_export" --product "产品名"

# 调低结构化并发（遇 429 时）
./310py/bin/python main_voc分析.py --input-dir "reviews_export" --product "产品名" \
  --struct-workers 4

# 环境变量：export VOC_STRUCT_WORKERS=8 VOC_EMBED_BATCH_SIZE=16

断点续跑

# 从向量化起续跑（步骤 4 起可省略 --product，自动读结构化库）
./310py/bin/python main_voc分析.py --from-step 4 --keep-db

# 仅重跑词频（复用已有 voc_terms.json）
./310py/bin/python main_voc分析.py --from-step 6 --skip-wordfreq-llm

# 仅重新生成 HTML 报告
./310py/bin/python 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）

./310py/bin/python prompts/smoke.py          # 检查 prompt 能否加载
./310py/bin/python prompts/smoke.py --live   # 联调模型（需 DEEPSEEK_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	本地 Qwen3 向量（维度见库内 dimensions 字段）
voc_clustering.sqlite	多阶段聚类标签
output/voc_terms.json	专有名词 / 停用词
output/word_freq.csv	全量词频表
output/{product}/{product}_voc_report.html	最终 VOC 分析报告（词云、词频、分簇、AI 正文）

stdout 会打印 JSON 摘要（含 report_html 等键）。

📂 项目结构

VOC_LLM结构化/
├── main_voc分析.py          # 主流程编排入口（七步）
├── main_voc分析_jieba.py    # 词频使用 jieba 的变体入口
├── main_voc分析.md          # 流程与算法详细说明
├── voc_llm.py               # DeepSeek Chat 密钥与客户端
├── local_embedding.py       # 本地 MLX Qwen3 向量化
├── 合并评论数据.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、配置
├── Qwen3-Embedding-4B-mxfp8/ # 本地模型（gitignore，需自行放置）
├── requirements.txt
├── output/                  # 报告与词频输出（gitignore）
└── README.md                # 本文件

❓ 常见问题

Q：提示缺少 DEEPSEEK_API_KEY？
A：按上文配置环境变量或 .deepseek_key，并确认密钥未提交到仓库。

Q：只有 .dashscope_key 报错？
A：Chat 已切换为 DeepSeek，DashScope 密钥不能用于 api.deepseek.com，请改用 .deepseek_key。

Q：步骤 4 向量化失败 / 找不到模型？
A：确认 Qwen3-Embedding-4B-mxfp8/ 在项目根，或设置 VOC_EMBED_MODEL_PATH；需在 Apple Silicon + Python 3.10+ 环境。

Q：步骤 4 报错找不到 product？
A：从步骤 1–3 完整跑过，或确保 voc_structured.sqlite 中已有最新 job；步骤 4 起可省略 --product。

Q：词频步骤报 spaCy 模型缺失？
A：执行 uv pip install --python 310py/bin/python "en-core-web-sm @ https://github.com/explosion/spacy-models/releases/download/en_core_web_sm-3.8.0/en_core_web_sm-3.8.0-py3-none-any.whl"。

Q：合并 CSV 失败？
A：确保 --input-dir 下所有 CSV 表头完全一致。

Q：修改 LLM 话术后报告解析失败？
A：勿修改 prompts/schema.yaml 中 report.markers 四段标记名；改完运行 ./310py/bin/python 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 约定。

安全提醒：勿提交 .deepseek_key、.dashscope_key、.env、真实评论 CSV、*.sqlite、output/ 及本地模型目录（见 .gitignore）。

📄 开源协议

本项目尚未在仓库中附带 LICENSE 文件。若为内部项目，请按组织规范使用；若计划开源，请补充协议文件（如 MIT）并更新本节链接。

✉️ 联系方式与鸣谢

• 详细技术文档：main_voc分析.md、prompts/README.md
• 项目仓库：https://git.onesvm.com/whoops/amz_review_analyse

鸣谢

• DeepSeek API — Chat 结构化、聚类评估、词频与报告
• mlx-community/Qwen3-Embedding-4B-mxfp8 — 本地向量化
• UMAP、HDBSCAN — 聚类管线
• spaCy — 英文词频与 NLP

---

README 与 main_voc分析.py 七步流程保持一致；深度说明请参阅 main_voc分析.md。