OnesvmWhoops c91e7f8c20 辉哥版本：结构化聚类溯源归因与业务报告增强。

移除结构化 audience 字段，强化 voc_业务_2 源评论归因匹配与 Persona 引用展示，更新 README 与流水线默认清理 SQLite。

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

2026-06-17 09:11:04 +08:00

8.5 KiB

Raw Blame History

亚马逊评论 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：

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

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

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

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

七步：合并 → 清洗 → 结构化 → 向量化 → 聚类 → 词频 → HTML（voc_report.py）。

断点示例：

./310py/bin/python main_voc分析.py --from-step 4      # 从向量化续跑
./310py/bin/python main_voc分析.py --only-step 7      # 仅重生成 voc_report

更细步骤见 main_voc分析.md、VOC分析方法论与报告生成逻辑.md。

结构化字段

当前 schema（prompts/schema.yaml）根字段为 3 项（已移除 audience）：

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

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

export DEEPSEEK_API_KEY="sk-xxx"
# 或项目根 .deepseek_key（已被 .gitignore）

安装

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 下载到项目根，或设置 VOC_EMBED_MODEL_PATH。

项目结构

├── 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 — Chat 结构化与分析
mlx-community/Qwen3-Embedding-4B-mxfp8 — 本地向量化
UMAP、HDBSCAN — 聚类

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

8.5 KiB Raw Blame History Unescape Escape