amz_review_analyse/README.md

# 亚马逊评论 VOC 结构化分析

> 基于 DeepSeek Chat + 本地 MLX 向量的亚马逊站内评论分析流水线。  
> 仓库内存在 **两套报告方案**，共用同一套数据管道（步骤 1–6），仅在「报告生成」阶段分叉。

**仓库**：
- https://git.onesvm.com/1svm/amz_review_analyse_Hui（辉哥版本）
- https://git.onesvm.com/whoops/amz_review_analyse

---

## 目录

- [新旧版本对比](#新旧版本对比)
- [流程一：经典版（7 步）](#流程一经典版7-步)
- [流程二：辉哥版本（6 步 + 业务报告）](#流程二辉哥版本6-步--业务报告)
- [快速开始](#快速开始)
- [结构化字段](#结构化字段)
- [溯源与归因](#溯源与归因)
- [环境要求与安装](#环境要求与安装)
- [项目结构](#项目结构)
- [常见问题](#常见问题)

---

## 新旧版本对比

| 维度 | 经典版（`main` 分支） | 辉哥版本（`辉哥版本` 分支） |
|------|----------------------|----------------------------|
| **定位** | 通用 VOC 分析报告，偏「数据总览 + LLM 撰写洞察」 | 业务决策报告，偏「Persona / 主题 / 根因 / KANO + 源评论归因」 |
| **入口命令** | `main_voc分析.py`（一步跑完 7 步） | `voc_业务_2/run_pipeline.py`（step 1–6 + 自动 `build_report.py`） |
| **报告脚本** | `voc_report.py` | `voc_业务_2/build_report.py` |
| **报告模板** | 程序内拼装 HTML | `voc_业务_2/template.html` |
| **报告输出** | `output/{产品}/{产品}_voc_report.html` | `voc_业务_2/output/{slug}-voc-report.html` |
| **结构化 schema** | 旧：含 `audience` 等 4 根字段 | 新：仅 `persona_signals` / `pain_points` / `product_feedback` |
| **向量化实体** | 含 `audience` 向量（旧） | `persona_signal` / `pain_point` / `aspect_opinion`（无 audience） |
| **聚类阶段** | `3a` 全量痛点 + `3b` 情感分桶 | 同左（共用 `聚类.py`） |
| **报告核心模块** | Dashboard KPI、词云、词频六类、LLM 正文洞察、聚类附录 | Persona 卡片、差评/好评主题表、KANO 四象限、JTBD、人群×场景矩阵、根因分析 |
| **源评论展示** | 附录「结构化/聚类效果验证」按 `source_row` 抽样 | Persona / 根因卡片内嵌 1–3 / 1–4 条真实评论 + ASIN 链接 |
| **引用匹配** | 附录直接展示结构化 JSON | 命中池 `source_rows` → 结构化字段优先 → 原文 keyword 回退 |
| **Prompt 配置** | `prompts/`（结构化 + 报告） | 数据层共用 `prompts/`；业务 LLM 见 `voc_业务_2/prompts.yaml` |
| **适用场景** | 快速出一份带词频、聚类可视化的综合报告 | 产品定义、竞品对标、根因归因、需逐条溯源的业务汇报 |

**共用部分（两版相同）**：步骤 1–6 的脚本、三个 SQLite 库、`merged_reviews_cleaned.csv` 与 `source_row` 行号约定。

**不可混用**：辉哥版本生成的结构化 JSON（无 `audience`）与旧库不兼容；换版本分析时请重跑 step 3（不要 `--keep-db`）。

---

## 流程一：经典版（7 步）

入口：`main_voc分析.py`  
分支：`main`

```mermaid
flowchart LR
  S1[1 合并CSV] --> S2[2 清洗]
  S2 --> S3[3 结构化LLM]
  S3 --> S4[4 向量化MLX]
  S4 --> S5[5 聚类]
  S4 --> S6[6 词频]
  S5 --> S7[7 voc_report报告]
  S6 --> S7
```

| 步骤 | 脚本 | 输入 | 输出 | LLM |
|:--:|------|------|------|:---:|
| **1** | `合并评论数据.py` | 原始 CSV 目录 | `merged_reviews.csv` | — |
| **2** | `content清洗.py` | 合并 CSV | `merged_reviews_cleaned.csv` | — |
| **3** | `结构化_server.py` | 清洗 CSV | `voc_structured.sqlite` | ✓ |
| **4** | `向量化.py` | 结构化库 + CSV | `voc_embeddings.sqlite` | — |
| **5** | `聚类.py` | 向量库 | `voc_clustering.sqlite` | ✓ 调参 |
| **6** | `词频.py` | 清洗 CSV | `output/word_freq.csv`、`voc_terms.json` | ✓ 术语 |
| **7** | `voc_report.py` | 上述全部产物 | `output/{产品}/{产品}_voc_report.html` | ✓ 正文 |

**一键运行**：

```bash
./310py/bin/python main_voc分析.py \
  --input-dir "reviews_export" \
  --product "Bikini Trimmer" \
  --industry "个人护理"
```

**断点续跑**：

```bash
./310py/bin/python main_voc分析.py --from-step 4      # 从向量化续跑
./310py/bin/python main_voc分析.py --only-step 7      # 仅重生成 voc_report
./310py/bin/python main_voc分析.py --from-step 4 --keep-db   # 保留已有 SQLite
```

详细参数见 **[main_voc分析.md](main_voc分析.md)**。

---

## 流程二：辉哥版本（6 步 + 业务报告）

入口：`voc_业务_2/run_pipeline.py`  
分支：`辉哥版本`

数据管道与经典版 **步骤 1–6 完全相同**（内部调用 `main_voc分析.py --only-step N`），**跳过** 经典版 step 7，改为业务报告：

```mermaid
flowchart LR
  S1[1 合并CSV] --> S2[2 清洗]
  S2 --> S3[3 结构化LLM]
  S3 --> S4[4 向量化MLX]
  S4 --> S5[5 聚类]
  S4 --> S6[6 词频]
  S5 --> R[build_report业务报告]
  S6 --> R
```

### 阶段 A：数据管道（step 1–6）

| 步骤 | 说明 | 产物 |
|:--:|------|------|
| 1 | 多 CSV 合并 | `merged_reviews.csv` |
| 2 | 去重、清洗 | `merged_reviews_cleaned.csv` |
| 3 | LLM 结构化（三字段 schema） | `voc_structured.sqlite` |
| 4 | 本地 MLX 向量化 | `voc_embeddings.sqlite` |
| 5 | UMAP + HDBSCAN 聚类 | `voc_clustering.sqlite` |
| 6 | spaCy 词频 + LLM 术语 | `output/word_freq.csv` |

`run_pipeline.py` 每步默认**清理旧 SQLite**（不加 `--keep-db`），避免与历史 job 混用。

### 阶段 B：业务报告（`build_report.py`）

在 SQLite 就绪后，按顺序执行（部分 LLM 任务并发）：

| 序号 | 模块 | 说明 |
|:--:|------|------|
| B1 | 加载数据 | 评论、聚类、结构化 extraction、竞品 ASIN 统计 |
| B2 | Persona 发现 | LLM 绑定聚类簇 → 计算命中数/占比 → 选取源评论 |
| B3 | 差评/好评主题 | LLM 归纳主题 + 结构化字段统计频次 |
| B4 | KANO + JTBD + 情感词 | 三任务并发 LLM |
| B5 | 人群×场景矩阵 | 依赖 KANO 结果 |
| B6 | 根因分析 | 各 Persona 并发 LLM → 系统回填源评论 |
| B7 | 渲染 HTML | 填充 `template.html` → 输出报告 |

**一键运行**：

```bash
cd voc_业务_2
# 编辑 config.yaml：input_dir 指向原始 CSV 目录
../310py/bin/python run_pipeline.py --input-dir "../你的评论CSV目录"
```

**仅重跑报告**（数据库已就绪）：

```bash
cd voc_业务_2
../310py/bin/python build_report.py --product "产品名" --industry "行业"
```

**断点续跑数据管道**：

```bash
../310py/bin/python run_pipeline.py --from-step 4   # 从向量化起
../310py/bin/python run_pipeline.py --from-step 5   # 仅重跑聚类
```

业务方法论见 **[VOC分析方法论与报告生成逻辑.md](VOC分析方法论与报告生成逻辑.md)**。

---

## 快速开始

```bash
git clone https://git.onesvm.com/1svm/amz_review_analyse_Hui.git
cd amz_review_analyse_Hui
git checkout 辉哥版本          # 业务报告版
# git checkout main           # 经典 voc_report 版

uv venv 310py --python 3.12
uv pip install --python 310py/bin/python -r requirements.txt
export DEEPSEEK_API_KEY="sk-xxx"

# 辉哥版本（推荐业务使用）
cd voc_业务_2 && ../310py/bin/python run_pipeline.py --input-dir "../评论CSV目录"

# 或经典版
./310py/bin/python main_voc分析.py --input-dir "评论CSV目录" --product "产品名"
```

---

## 结构化字段

辉哥版本 schema（`prompts/schema.yaml`）：

```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"
    }
  ]
}
```

经典版旧 schema 曾含 `audience`（购买关系）；辉哥版本已移除，画像信息统一写入 `persona_signals`。

---

## 溯源与归因

全链路通过 **`source_row`**（与 `merged_reviews_cleaned.csv` 行号一致）关联：

```
评论原文 (CSV)
    ↓ source_row
comment_extractions (voc_structured.sqlite)
    ↓
embedding_items → cluster_assignments
    ↓
Persona.source_rows（命中池）
    ↓
build_report.py
    ├── Persona 卡片：结构化 persona_signals/pain_points 优先匹配
    ├── 根因：Negative aspect+opinion 优先匹配
    └── 附录（仅 voc_report）：结构化 JSON 抽样
```

`voc_业务_2/config.yaml`：

```yaml
persona_quote_max: 3       # Persona 卡片最多展示条数
rootcause_quote_max: 4     # 每条根因最多展示条数
```

---

## 环境要求与安装

| 依赖 | 说明 |
|------|------|
| Python | ≥ 3.10（推荐 3.12） |
| DeepSeek API Key | 结构化、聚类调参、词频、报告 LLM |
| `Qwen3-Embedding-4B-mxfp8/` | 本地 MLX 向量（约 4GB，需自行下载） |
| Apple Silicon | 向量化依赖 MLX |
| spaCy `en_core_web_sm` | 词频步骤 |

```bash
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"
```

API Key：`DEEPSEEK_API_KEY` 环境变量，或项目根 `.deepseek_key`（勿提交 Git）。

---

## 项目结构

```text
├── main_voc分析.py              # 经典版：七步编排入口
├── voc_report.py                # 经典版：step 7 报告
├── 结构化_server.py / 向量化.py / 聚类.py / 词频.py
├── prompts/                     # 结构化 Prompt（两版共用）
├── voc_业务_2/                  # 辉哥版本业务报告
│   ├── run_pipeline.py          # step 1–6 + 自动 build_report
│   ├── build_report.py          # 业务 HTML 报告
│   ├── report_utils.py          # 统计、溯源引用、渲染
│   ├── config.yaml / prompts.yaml / template.html
│   └── output/                  # 业务报告输出
└── output/                      # 经典版报告 + 词频（gitignore）
```

---

## 常见问题

**Q：两个版本可以共用同一份 SQLite 吗？**  
A：step 1–6 产物可共用，但结构化库须为**同一 schema**。从经典版（含 audience）切到辉哥版本时，必须重跑 step 3。

**Q：Persona 显示「命中 N 条」但没有源评论？**  
A：用最新代码重跑 `build_report.py`；命中池非空时会多层回退，优先结构化字段匹配。

**Q：选哪个版本？**  
A：需要 Persona、KANO、根因、源评论归因 → **辉哥版本**；需要词云、词频 Dashboard、LLM 长文洞察 → **经典版**。也可只跑 step 1–6，再分别生成两种报告。

---

## 分支与仓库

| 分支 / 仓库 | 说明 |
|-------------|------|
| `main` | 经典 7 步 + `voc_report.py` |
| **`辉哥版本`** | 业务报告 + 三字段结构化 + 溯源归因 |
| `1svm/amz_review_analyse_Hui` | 辉哥版本主仓库 |
| `whoops/amz_review_analyse` | 同源备份 |

---

## 鸣谢

- [DeepSeek API](https://api.deepseek.com)
- [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)。*