From d4c33502e6a1cf67ab6223165d492eacbbfc4363 Mon Sep 17 00:00:00 2001 From: OnesvmWhoops Date: Wed, 17 Jun 2026 09:17:37 +0800 Subject: [PATCH] =?UTF-8?q?README=EF=BC=9A=E8=A1=A5=E5=85=85=E7=BB=8F?= =?UTF-8?q?=E5=85=B8=E7=89=88=E4=B8=8E=E8=BE=89=E5=93=A5=E7=89=88=E6=9C=AC?= =?UTF-8?q?=E5=AF=B9=E6=AF=94=E5=8F=8A=E5=88=86=E6=AD=A5=E6=B5=81=E7=A8=8B?= =?UTF-8?q?=E8=AF=B4=E6=98=8E=E3=80=82?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Cursor --- README.md | 319 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 194 insertions(+), 125 deletions(-) diff --git a/README.md b/README.md index a52b80b..8f8fc65 100644 --- 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)。*