c91e7f8c20
移除结构化 audience 字段，强化 voc_业务_2 源评论归因匹配与 Persona 引用展示，更新 README 与流水线默认清理 SQLite。 Co-authored-by: Cursor <cursoragent@cursor.com>
240 lines
8.5 KiB
Markdown
240 lines
8.5 KiB
Markdown
# 亚马逊评论 VOC 结构化分析
|
||
|
||
> **分支「辉哥版本」**：可结构化、可聚类、可溯源归因的亚马逊站内评论分析流水线。
|
||
> 基于 DeepSeek Chat API + 本地 MLX 向量，完成：合并 CSV → 清洗 → LLM 结构化 → 向量化 → 聚类 → 词频 → **业务 HTML 报告**（Persona / 差评主题 / 根因 / KANO，每条洞察可回溯到真实评论）。
|
||
|
||
**仓库**：https://git.onesvm.com/whoops/amz_review_analyse
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
- [核心能力](#核心能力)
|
||
- [快速开始（推荐）](#快速开始推荐)
|
||
- [主流程说明](#主流程说明)
|
||
- [结构化字段](#结构化字段)
|
||
- [溯源与归因](#溯源与归因)
|
||
- [环境要求](#环境要求)
|
||
- [安装](#安装)
|
||
- [项目结构](#项目结构)
|
||
- [常见问题](#常见问题)
|
||
|
||
---
|
||
|
||
## 核心能力
|
||
|
||
| 能力 | 说明 |
|
||
|------|------|
|
||
| **LLM 结构化提取** | 从评论抽取 `persona_signals`（画像信号）、`pain_points`（需求痛点）、`product_feedback`（方面/观点/情感/类别） |
|
||
| **本地向量化** | Apple Silicon 上运行 `Qwen3-Embedding-4B-mxfp8`（MLX），无需云端 Embedding |
|
||
| **语义聚类** | UMAP + HDBSCAN：`3a` 全量痛点、`3b` 按情感分桶的 aspect-opinion 聚类 |
|
||
| **Persona 发现** | 绑定聚类簇 + keywords 二次过滤，统计命中数与占比 |
|
||
| **差评主题 & 根因** | LLM 归纳主题；根因引用由系统从真实评论回填（结构化字段优先匹配） |
|
||
| **可溯源 HTML 报告** | Persona 卡片、根因区块展示源评论原文 + ASIN 链接；附录展示结构化/聚类抽样 |
|
||
| **断点续跑** | `main_voc分析.py --from-step` / `run_pipeline.py --from-step` |
|
||
|
||
---
|
||
|
||
## 快速开始（推荐）
|
||
|
||
业务报告入口在 `voc_业务_2/`，一键跑数据管道并生成 HTML：
|
||
|
||
```bash
|
||
cd voc_业务_2
|
||
|
||
# 1. 编辑 config.yaml：input_dir 指向原始评论 CSV 目录
|
||
# 2. 全流程（step 1–6 + 自动 build_report）
|
||
../310py/bin/python run_pipeline.py --input-dir "../你的评论CSV目录"
|
||
```
|
||
|
||
产物示例：
|
||
|
||
- 根目录 SQLite：`voc_structured.sqlite`、`voc_embeddings.sqlite`、`voc_clustering.sqlite`
|
||
- HTML 报告：`voc_业务_2/output/{产品slug}-voc-report.html`
|
||
|
||
仅重跑报告（数据库已就绪）：
|
||
|
||
```bash
|
||
../310py/bin/python build_report.py --product "产品名" --industry "行业"
|
||
```
|
||
|
||
---
|
||
|
||
## 主流程说明
|
||
|
||
### 方式 A：`voc_业务_2/run_pipeline.py`（业务报告）
|
||
|
||
```
|
||
原始 CSV → main_voc分析 step 1–6 → build_report.py → HTML
|
||
```
|
||
|
||
- 每步默认**清理旧 SQLite**（不加 `--keep-db`），避免与历史 job 混用
|
||
- 产品名/行业可在 `config.yaml` 留空，由 LLM 从评论样本自动识别
|
||
|
||
### 方式 B：`main_voc分析.py`（含经典 voc_report）
|
||
|
||
```bash
|
||
./310py/bin/python main_voc分析.py \
|
||
--input-dir "reviews_export" \
|
||
--product "Bikini Trimmer" \
|
||
--industry "个人护理"
|
||
```
|
||
|
||
七步：合并 → 清洗 → 结构化 → 向量化 → 聚类 → 词频 → HTML（`voc_report.py`）。
|
||
|
||
断点示例：
|
||
|
||
```bash
|
||
./310py/bin/python main_voc分析.py --from-step 4 # 从向量化续跑
|
||
./310py/bin/python main_voc分析.py --only-step 7 # 仅重生成 voc_report
|
||
```
|
||
|
||
更细步骤见 **[main_voc分析.md](main_voc分析.md)**、**[VOC分析方法论与报告生成逻辑.md](VOC分析方法论与报告生成逻辑.md)**。
|
||
|
||
---
|
||
|
||
## 结构化字段
|
||
|
||
当前 schema（`prompts/schema.yaml`）根字段为 **3 项**（已移除 `audience`）：
|
||
|
||
```json
|
||
{
|
||
"persona_signals": ["sensitive skin", "travel grooming"],
|
||
"pain_points": ["ingrown hair"],
|
||
"product_feedback": [
|
||
{
|
||
"aspect": "battery life",
|
||
"opinion": "dies after one use",
|
||
"sentiment": "Negative",
|
||
"category": "Function"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
- 所有字段值须为**自然英文**（多语言评论先理解再英文输出）
|
||
- `product_feedback.category` 优先 8 类标准类别（Trust / Ingredient / Quality / Function / Appearance / Logistics / Customer Service / Price）
|
||
|
||
Prompt 编辑入口：`prompts/extraction/`、`voc_业务_2/prompts.yaml`。
|
||
|
||
---
|
||
|
||
## 溯源与归因
|
||
|
||
整条链路通过 **`source_row`**（与 `merged_reviews_cleaned.csv` 行号一致）关联：
|
||
|
||
```
|
||
评论原文 (CSV)
|
||
↓ source_row
|
||
comment_extractions (voc_structured.sqlite)
|
||
↓ extraction_id / source_row
|
||
embedding_items (voc_embeddings.sqlite)
|
||
↓
|
||
cluster_assignments (voc_clustering.sqlite) → Persona 绑定簇 → source_rows 命中池
|
||
↓
|
||
build_report.py HTML
|
||
├── Persona 卡片：命中池内结构化/原文匹配，展示 1–3 条源评论
|
||
├── 根因分析：Negative product_feedback 优先匹配，展示 1–4 条
|
||
└── 附录（voc_report）：结构化 JSON + 聚类短语抽样
|
||
```
|
||
|
||
配置项（`voc_业务_2/config.yaml`）：
|
||
|
||
```yaml
|
||
persona_quote_max: 3 # Persona 卡片最多展示条数
|
||
rootcause_quote_max: 4 # 每条根因最多展示条数
|
||
```
|
||
|
||
---
|
||
|
||
## 环境要求
|
||
|
||
| 依赖 | 说明 |
|
||
|------|------|
|
||
| Python | ≥ 3.10（推荐 3.12，项目内 `310py`） |
|
||
| DeepSeek API Key | 结构化、Persona/主题/根因/KANO 等 Chat 步骤 |
|
||
| 本地 Embedding 模型 | `Qwen3-Embedding-4B-mxfp8/`（约 4GB，gitignore，需自行下载） |
|
||
| Apple Silicon | 本地 MLX 向量化 |
|
||
| spaCy `en_core_web_sm` | 词频步骤 |
|
||
|
||
**API Key**（任选其一，勿提交 Git）：
|
||
|
||
```bash
|
||
export DEEPSEEK_API_KEY="sk-xxx"
|
||
# 或项目根 .deepseek_key（已被 .gitignore）
|
||
```
|
||
|
||
---
|
||
|
||
## 安装
|
||
|
||
```bash
|
||
git clone https://git.onesvm.com/whoops/amz_review_analyse.git
|
||
cd amz_review_analyse
|
||
|
||
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"
|
||
```
|
||
|
||
Embedding 模型：从 [Hugging Face mlx-community/Qwen3-Embedding-4B-mxfp8](https://huggingface.co/mlx-community/Qwen3-Embedding-4B-mxfp8) 下载到项目根，或设置 `VOC_EMBED_MODEL_PATH`。
|
||
|
||
---
|
||
|
||
## 项目结构
|
||
|
||
```text
|
||
├── main_voc分析.py # 七步主流程编排
|
||
├── 结构化_server.py # LLM 结构化 → voc_structured.sqlite
|
||
├── 向量化.py # persona_signal / pain / aspect_opinion 向量
|
||
├── 聚类.py # 3a 痛点 + 3b 情感分桶聚类
|
||
├── voc_report.py # 经典 HTML 报告（Dashboard + 附录验证）
|
||
├── prompts/ # 结构化 & 报告 Prompt（可热加载）
|
||
├── voc_业务_2/
|
||
│ ├── run_pipeline.py # ★ 业务一键流水线
|
||
│ ├── build_report.py # ★ 业务 HTML 报告生成
|
||
│ ├── llm_analyzer.py # Persona / 主题 / KANO / 根因 LLM
|
||
│ ├── report_utils.py # 统计、引用匹配、HTML 拼装
|
||
│ ├── data_loader.py # SQLite / CSV 加载
|
||
│ ├── config.yaml # 产品路径、并发、引用条数等
|
||
│ └── template.html # 报告模板
|
||
└── output/ # 报告与词频（gitignore）
|
||
```
|
||
|
||
---
|
||
|
||
## 常见问题
|
||
|
||
**Q：Persona 显示「命中 N 条」但没有源评论？**
|
||
A：确保已用最新 `report_utils.pick_persona_quotes` 重跑 `build_report.py`；命中池有数据时会多层回退展示，优先结构化 `persona_signals` / `pain_points` 匹配。
|
||
|
||
**Q：结构化校验报 persona_signals 错误？**
|
||
A：「辉哥版本」已移除 `audience` 字段；请重跑 step 3 生成新格式 JSON，勿混用旧库。
|
||
|
||
**Q：提示缺少 API Key？**
|
||
A：配置 `DEEPSEEK_API_KEY` 或 `.deepseek_key`（Chat 已用 DeepSeek，DashScope 密钥不可用）。
|
||
|
||
**Q：向量化找不到模型？**
|
||
A：确认 `Qwen3-Embedding-4B-mxfp8/` 在项目根或设置 `VOC_EMBED_MODEL_PATH`。
|
||
|
||
---
|
||
|
||
## 分支说明
|
||
|
||
| 分支 | 说明 |
|
||
|------|------|
|
||
| `main` | 基础流水线 + DeepSeek + 本地 Embedding |
|
||
| **`辉哥版本`** | 业务报告（voc_业务_2）、结构化三字段、聚类溯源、Persona/根因源评论归因 |
|
||
|
||
---
|
||
|
||
## 鸣谢
|
||
|
||
- [DeepSeek API](https://api.deepseek.com) — Chat 结构化与分析
|
||
- [mlx-community/Qwen3-Embedding-4B-mxfp8](https://huggingface.co/mlx-community/Qwen3-Embedding-4B-mxfp8) — 本地向量化
|
||
- [UMAP](https://umap-learn.readthedocs.io/)、[HDBSCAN](https://hdbscan.readthedocs.io/) — 聚类
|
||
|
||
---
|
||
|
||
*详细算法与 SQLite 表结构见 [main_voc分析.md](main_voc分析.md)。*
|