whoops/amz_review_analyse
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

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

Browse source 
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
OnesvmWhoops 2026-06-17 09:17:37 +08:00
parent c91e7f8c20
commit d4c33502e6
1 changed files with 194 additions and 125 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

315
README.md
View file

@ -1,77 +1,79 @@
# 亚马逊评论 VOC 结构化分析 # 亚马逊评论 VOC 结构化分析
> **分支「辉哥版本」**：可结构化、可聚类、可溯源归因的亚马逊站内评论分析流水线。 > 基于 DeepSeek Chat + 本地 MLX 向量的亚马逊站内评论分析流水线。
> 基于 DeepSeek Chat API + 本地 MLX 向量，完成：合并 CSV → 清洗 → LLM 结构化 → 向量化 → 聚类 → 词频 → **业务 HTML 报告**（Persona / 差评主题 / 根因 / KANO，每条洞察可回溯到真实评论）。 > 仓库内存在 **两套报告方案**，共用同一套数据管道（步骤 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-步--业务报告)
- [快速开始](#快速开始)
- [结构化字段](#结构化字段) - [结构化字段](#结构化字段)
- [溯源与归因](#溯源与归因) - [溯源与归因](#溯源与归因)
- [环境要求](#环境要求) - [环境要求与安装](#环境要求与安装)
- [安装](#安装)
- [项目结构](#项目结构) - [项目结构](#项目结构)
- [常见问题](#常见问题) - [常见问题](#常见问题)
--- ---
## 核心能力 ## 新旧版本对比
| 能力 | 说明 | | 维度 | 经典版（`main` 分支） | 辉哥版本（`辉哥版本` 分支） |
|------|------| |------|----------------------|----------------------------|
| **LLM 结构化提取** | 从评论抽取 `persona_signals`（画像信号）、`pain_points`（需求痛点）、`product_feedback`（方面/观点/情感/类别） | | **定位** | 通用 VOC 分析报告，偏「数据总览 + LLM 撰写洞察」 | 业务决策报告，偏「Persona / 主题 / 根因 / KANO + 源评论归因」 |
| **本地向量化** | Apple Silicon 上运行 `Qwen3-Embedding-4B-mxfp8`（MLX），无需云端 Embedding | | **入口命令** | `main_voc分析.py`（一步跑完 7 步） | `voc_业务_2/run_pipeline.py`（step 1–6 + 自动 `build_report.py`） |
| **语义聚类** | UMAP + HDBSCAN：`3a` 全量痛点、`3b` 按情感分桶的 aspect-opinion 聚类 | | **报告脚本** | `voc_report.py` | `voc_业务_2/build_report.py` |
| **Persona 发现** | 绑定聚类簇 + keywords 二次过滤，统计命中数与占比 | | **报告模板** | 程序内拼装 HTML | `voc_业务_2/template.html` |
| **差评主题 & 根因** | LLM 归纳主题；根因引用由系统从真实评论回填（结构化字段优先匹配） | | **报告输出** | `output/{产品}/{产品}_voc_report.html` | `voc_业务_2/output/{slug}-voc-report.html` |
| **可溯源 HTML 报告** | Persona 卡片、根因区块展示源评论原文 + ASIN 链接；附录展示结构化/聚类抽样 | | **结构化 schema** | 旧：含 `audience` 等 4 根字段 | 新：仅 `persona_signals` / `pain_points` / `product_feedback` |
| **断点续跑** | `main_voc分析.py --from-step` / `run_pipeline.py --from-step` | | **向量化实体** | 含 `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 ```mermaid
cd voc_业务_2 flowchart LR
S1[1 合并CSV] --> S2[2 清洗]
# 1. 编辑 config.yaml：input_dir 指向原始评论 CSV 目录 S2 --> S3[3 结构化LLM]
# 2. 全流程（step 1–6 + 自动 build_report） S3 --> S4[4 向量化MLX]
../310py/bin/python run_pipeline.py --input-dir "../你的评论CSV目录" 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 ```bash
./310py/bin/python main_voc分析.py \ ./310py/bin/python main_voc分析.py \
@ -80,22 +82,113 @@ cd voc_业务_2
--industry "个人护理" --industry "个人护理"
``` ```
七步：合并 → 清洗 → 结构化 → 向量化 → 聚类 → 词频 → HTML（`voc_report.py`）。 **断点续跑**：
断点示例：
```bash ```bash
./310py/bin/python main_voc分析.py --from-step 4 # 从向量化续跑 ./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 --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 ```json
{ {
@ -112,33 +205,30 @@ cd voc_业务_2
} }
``` ```
- 所有字段值须为**自然英文**（多语言评论先理解再英文输出） 经典版旧 schema 曾含 `audience`（购买关系）；辉哥版本已移除，画像信息统一写入 `persona_signals`。
- `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` 行号一致）关联： 全链路通过 **`source_row`**（与 `merged_reviews_cleaned.csv` 行号一致）关联：
``` ```
评论原文 (CSV) 评论原文 (CSV)
↓ source_row ↓ source_row
comment_extractions (voc_structured.sqlite) 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.source_rows（命中池）
├── Persona 卡片：命中池内结构化/原文匹配，展示 1–3 条源评论 ↓
├── 根因分析：Negative product_feedback 优先匹配，展示 1–4 条 build_report.py
└── 附录（voc_report）：结构化 JSON + 聚类短语抽样 ├── Persona 卡片：结构化 persona_signals/pain_points 优先匹配
├── 根因：Negative aspect+opinion 优先匹配
└── 附录（仅 voc_report）：结构化 JSON 抽样
``` ```
配置项（`voc_业务_2/config.yaml`）： `voc_业务_2/config.yaml`：
```yaml ```yaml
persona_quote_max: 3 # Persona 卡片最多展示条数 persona_quote_max: 3 # Persona 卡片最多展示条数
@ -147,94 +237,73 @@ rootcause_quote_max: 4 # 每条根因最多展示条数
--- ---
## 环境要求 ## 环境要求与安装
| 依赖 | 说明 | | 依赖 | 说明 |
|------|------| |------|------|
| Python | ≥ 3.10（推荐 3.12，项目内 `310py`） | | Python | ≥ 3.10（推荐 3.12） |
| DeepSeek API Key | 结构化、Persona/主题/根因/KANO 等 Chat 步骤 | | DeepSeek API Key | 结构化、聚类调参、词频、报告 LLM |
| 本地 Embedding 模型 | `Qwen3-Embedding-4B-mxfp8/`（约 4GB，gitignore，需自行下载） | | `Qwen3-Embedding-4B-mxfp8/` | 本地 MLX 向量（约 4GB，需自行下载） |
| Apple Silicon | 本地 MLX 向量化 | | Apple Silicon | 向量化依赖 MLX |
| spaCy `en_core_web_sm` | 词频步骤 | | spaCy `en_core_web_sm` | 词频步骤 |
**API Key**（任选其一，勿提交 Git）：
```bash ```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 \ 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" "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 ```text
├── main_voc分析.py # 七步主流程编排 ├── main_voc分析.py # 经典版：七步编排入口
├── 结构化_server.py # LLM 结构化 → voc_structured.sqlite ├── voc_report.py # 经典版：step 7 报告
├── 向量化.py # persona_signal / pain / aspect_opinion 向量 ├── 结构化_server.py / 向量化.py / 聚类.py / 词频.py
├── 聚类.py # 3a 痛点 + 3b 情感分桶聚类 ├── prompts/ # 结构化 Prompt（两版共用）
├── voc_report.py # 经典 HTML 报告（Dashboard + 附录验证） ├── voc_业务_2/ # 辉哥版本业务报告
├── prompts/ # 结构化 & 报告 Prompt（可热加载） │ ├── run_pipeline.py # step 1–6 + 自动 build_report
├── voc_业务_2/ │ ├── build_report.py # 业务 HTML 报告
│ ├── run_pipeline.py # ★ 业务一键流水线 │ ├── report_utils.py # 统计、溯源引用、渲染
│ ├── build_report.py # ★ 业务 HTML 报告生成 │ ├── config.yaml / prompts.yaml / template.html
│ ├── llm_analyzer.py # Persona / 主题 / KANO / 根因 LLM │ └── output/ # 业务报告输出
│ ├── report_utils.py # 统计、引用匹配、HTML 拼装 └── output/ # 经典版报告 + 词频（gitignore）
│ ├── data_loader.py # SQLite / CSV 加载
│ ├── config.yaml # 产品路径、并发、引用条数等
│ └── template.html # 报告模板
└── output/ # 报告与词频（gitignore）
``` ```
--- ---
## 常见问题 ## 常见问题
**Q：两个版本可以共用同一份 SQLite 吗？**
A：step 1–6 产物可共用，但结构化库须为**同一 schema**。从经典版（含 audience）切到辉哥版本时，必须重跑 step 3。
**Q：Persona 显示「命中 N 条」但没有源评论？** **Q：Persona 显示「命中 N 条」但没有源评论？**
A：确保已用最新 `report_utils.pick_persona_quotes` 重跑 `build_report.py`；命中池有数据时会多层回退展示，优先结构化 `persona_signals` / `pain_points` 匹配。 A：用最新代码重跑 `build_report.py`；命中池非空时会多层回退，优先结构化字段匹配。
**Q：结构化校验报 persona_signals 错误？** **Q：选哪个版本？**
A：「辉哥版本」已移除 `audience` 字段；请重跑 step 3 生成新格式 JSON，勿混用旧库。 A：需要 Persona、KANO、根因、源评论归因 → **辉哥版本**；需要词云、词频 Dashboard、LLM 长文洞察 → **经典版**。也可只跑 step 1–6，再分别生成两种报告。
**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 | | `main` | 经典 7 步 + `voc_report.py` |
| **`辉哥版本`** | 业务报告（voc_业务_2）、结构化三字段、聚类溯源、Persona/根因源评论归因 | | **`辉哥版本`** | 业务报告 + 三字段结构化 + 溯源归因 |
| `1svm/amz_review_analyse_Hui` | 辉哥版本主仓库 |
| `whoops/amz_review_analyse` | 同源备份 |
--- ---
## 鸣谢 ## 鸣谢
- [DeepSeek API](https://api.deepseek.com) — Chat 结构化与分析 - [DeepSeek API](https://api.deepseek.com)
- [mlx-community/Qwen3-Embedding-4B-mxfp8](https://huggingface.co/mlx-community/Qwen3-Embedding-4B-mxfp8) — 本地向量化 - [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/) — 聚类 - [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)。*