# 亚马逊评论 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)。*