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

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-06-17 09:17:37 +08:00

11 KiB

Raw Blame History

亚马逊评论 VOC 结构化分析

基于 DeepSeek Chat + 本地 MLX 向量的亚马逊站内评论分析流水线。
仓库内存在 两套报告方案，共用同一套数据管道（步骤 1–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

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`	✓ 正文

一键运行：

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

断点续跑：

./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。

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

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

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

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` → 输出报告

一键运行：

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

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

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

断点续跑数据管道：

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

业务方法论见 VOC分析方法论与报告生成逻辑.md。

快速开始

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）：

{
  "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：

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`	词频步骤

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）。

项目结构

├── 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`	同源备份

鸣谢

算法与 SQLite 表结构详见 main_voc分析.md。

11 KiB Raw Blame History Unescape Escape