README：补充经典版与辉哥版本对比及分步流程说明。

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-06-17 09:17:37 +08:00 · 2026-06-17 09:17:37 +08:00 · d4c33502e6
commit d4c33502e6
parent c91e7f8c20
1 changed files with 194 additions and 125 deletions
--- a/README.md
+++ b/README.md
@ -1,77 +1,79 @@
 # 亚马逊评论 VOC 结构化分析

-> **分支「辉哥版本」**：可结构化、可聚类、可溯源归因的亚马逊站内评论分析流水线。  
-> 基于 DeepSeek Chat API + 本地 MLX 向量，完成：合并 CSV → 清洗 → LLM 结构化 → 向量化 → 聚类 → 词频 → **业务 HTML 报告**（Persona / 差评主题 / 根因 / KANO，每条洞察可回溯到真实评论）。
+> 基于 DeepSeek Chat + 本地 MLX 向量的亚马逊站内评论分析流水线。  
+> 仓库内存在 **两套报告方案**，共用同一套数据管道（步骤 1–6），仅在「报告生成」阶段分叉。

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

 ---

 ## 目录

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

 ---

-## 核心能力
+## 新旧版本对比

-| 能力 | 说明 |
-|------|------|
-| **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` |
+| 维度 | 经典版（`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 步）

-业务报告入口在 `voc_业务_2/`，一键跑数据管道并生成 HTML：
+入口：`main_voc分析.py`  
+分支：`main`

-```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目录"
+```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` | ✓ 正文 |

- 根目录 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 \
@ -80,22 +82,113 @@ cd voc_业务_2
  --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
+./310py/bin/python main_voc分析.py --from-step 4 --keep-db   # 保留已有 SQLite
 ```

-更细步骤见 **[main_voc分析.md](main_voc分析.md)**、**[VOC分析方法论与报告生成逻辑.md](VOC分析方法论与报告生成逻辑.md)**。
+详细参数见 **[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`）根字段为 **3 项**（已移除 `audience`）：
+辉哥版本 schema（`prompts/schema.yaml`）：

 ```json
 {
@ -112,129 +205,105 @@ cd voc_业务_2
 }
 ```

- 所有字段值须为**自然英文**（多语言评论先理解再英文输出）
- `product_feedback.category` 优先 8 类标准类别（Trust / Ingredient / Quality / Function / Appearance / Logistics / Customer Service / Price）
-
-Prompt 编辑入口：`prompts/extraction/`、`voc_业务_2/prompts.yaml`。
+经典版旧 schema 曾含 `audience`（购买关系）；辉哥版本已移除，画像信息统一写入 `persona_signals`。

 ---

 ## 溯源与归因

-整条链路通过 **`source_row`**（与 `merged_reviews_cleaned.csv` 行号一致）关联：
+全链路通过 **`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 命中池
+embedding_items → cluster_assignments
    ↓
-build_report.py HTML
-    ├── Persona 卡片：命中池内结构化/原文匹配，展示 1–3 条源评论
-    ├── 根因分析：Negative product_feedback 优先匹配，展示 1–4 条
-    └── 附录（voc_report）：结构化 JSON + 聚类短语抽样
+Persona.source_rows（命中池）
+    ↓
+build_report.py
+    ├── Persona 卡片：结构化 persona_signals/pain_points 优先匹配
+    ├── 根因：Negative aspect+opinion 优先匹配
+    └── 附录（仅 voc_report）：结构化 JSON 抽样
 ```

-配置项（`voc_业务_2/config.yaml`）：
+`voc_业务_2/config.yaml`：

 ```yaml
-persona_quote_max: 3      # Persona 卡片最多展示条数
-rootcause_quote_max: 4    # 每条根因最多展示条数
+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 向量化 |
+| Python | ≥ 3.10（推荐 3.12） |
+| DeepSeek API Key | 结构化、聚类调参、词频、报告 LLM |
+| `Qwen3-Embedding-4B-mxfp8/` | 本地 MLX 向量（约 4GB，需自行下载） |
+| 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`。
+API Key：`DEEPSEEK_API_KEY` 环境变量，或项目根 `.deepseek_key`（勿提交 Git）。

 ---

 ## 项目结构

 ```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）
+├── 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：确保已用最新 `report_utils.pick_persona_quotes` 重跑 `build_report.py`；命中池有数据时会多层回退展示，优先结构化 `persona_signals` / `pain_points` 匹配。
+A：用最新代码重跑 `build_report.py`；命中池非空时会多层回退，优先结构化字段匹配。

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

 ---

-## 分支说明
+## 分支与仓库

-| 分支 | 说明 |
-|------|------|
-| `main` | 基础流水线 + DeepSeek + 本地 Embedding |
-| **`辉哥版本`** | 业务报告（voc_业务_2）、结构化三字段、聚类溯源、Persona/根因源评论归因 |
+| 分支 / 仓库 | 说明 |
+|-------------|------|
+| `main` | 经典 7 步 + `voc_report.py` |
+| **`辉哥版本`** | 业务报告 + 三字段结构化 + 溯源归因 |
+| `1svm/amz_review_analyse_Hui` | 辉哥版本主仓库 |
+| `whoops/amz_review_analyse` | 同源备份 |

 ---

 ## 鸣谢

- [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/) — 聚类
+- [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)。*
+*算法与 SQLite 表结构详见 [main_voc分析.md](main_voc分析.md)。*