qiuqiu-rag-shopping-agent

KO | EN

gitlite — search

#javascript #python #react #ai #typescript #llm #machine-learning #windows #awesome #cli #pytorch #mcp #ios #openai

qiuqiu-rag-shopping-agent

(★ 10)

球球 Shopping Agent — 基于 RAG 的多模态电商智能导购 AI Agent

qiuqiu-rag-shopping-agent Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 球球 Shopping Agent — 基于 RAG 的多模态电商智能导购 AI Agent

## 产品介绍

**球球（qiuqiu）** 是一个基于 RAG 技术的 AI 智能导购助手，部署在 Android 原生 App 上，覆盖从"浏览→决策→下单"的完整购物链路。

球球的定位不是传统客服或冰冷的搜索引擎，而是 **用户身边懂行的朋友**——有自己的审美和立场，会说"我觉得这款更值"，也会说"这个我不太推荐"，但所有立场都来自真实的数据和用户评价，不是幻觉或偏见。

**球球能做的事：**

- **需求不清时** — 先做品类教育（"抗初老精华分抗氧型和维稳型两条路线"），再通过交互式追问收敛需求（肤质？预算？核心诉求？）
- **需求明确时** — 给出有依据、有立场的商品推荐，每款商品的推荐理由都有因果论证和真实用户评价佐证
- **想对比时** — 自动提取关键维度生成结构化对比表格，给出明确的选购结论
- **想了解口碑时** — 梳理好评差评，总结真实用户反馈，不回避缺点
- **跨品类场景时** — 一句"帮我搭配爬山装备"，从鞋服、防晒到路上补给一站式搭配
- **想买时** — 直接对话加购、选规格、改数量、下单，不用跳出对话流

## 功能实现清单

### 一、基础功能（最小闭环）

**端到端对话链路**
- 用户在 Android 原生 App 中输入文字，发送到后端
- 后端通过 RAG 检索匹配商品，拼装 Prompt 调用豆包大模型
- 大模型通过 SSE 流式返回回复，客户端逐字渲染
- 回复中嵌入可点击的商品卡片，点击跳转商品详情页

**商品推荐能力**
- 理解用户模糊需求（"推荐一款适合油皮的洗面奶"），从 100 条商品库中检索并推荐
- 推荐内容包含：商品名、价格、核心卖点、用户评价引用，不编造不存在的商品或价格
- 商品卡片展示品名、价格、评分、主图，支持点击跳转详情

**商品详情页**
- 展示商品主图、价格区间、多 SKU 规格选择、商品描述
- 展示该商品的 FAQ 问答和真实用户评价
- 支持加入购物车、收藏

### 二、数据工程与特征治理
- **非结构化数据向量化**：将商品名、品牌、品类、子类目、营销描述拼接为 `search_text`，使用 `text2vec-base-chinese` 中文 Embedding 模型编码为 768 维向量，存入 ChromaDB
- **Chunking 策略**：商品详情拆分为独立的 FAQ 片段和用户评价片段（共 892 条 chunks），每条 chunk 关联 `product_id`，支持按商品维度精确召回
- **数据一致性**：商品价格、品牌、SKU 等结构化字段存储在 ChromaDB metadata 中，推荐时直接读取，不依赖大模型生成，杜绝价格幻觉
- **预计算指标**：入库时从全量评价计算商品平均评分和评价数量，避免运行时随机采样导致评分偏差

### 三、模型/Agent 编排
- **意图识别与路由**：三级意图分类 — 正则快速识别问候/元问题 → LLM 轻量分类购物/闲聊 → 购物意图进入 RAG 链路。非购物查询不触发检索，节省资源
- **RAG 链路可靠性**：系统提示词中硬性约束"只推荐检索结果中的商品，不编造商品名、价格、功效、成分"，并通过 `` 标记机制确保卡片与文本推荐一致
- **Prompt Engineering**：15K 字符系统提示词，涵盖角色设定、多模式路由（clarify/recommend/compare/review/converge/scenario）、输出格式规范（三段 bubble 结构、KV 卖点列表、评价引用规则）、自检清单
- **多轮 Query 改写**：用 LLM 判断用户后续输入是"新搜索"还是"收窄/追问"，前者改写为独立 query 重新检索，后者基于上轮推荐直接回答，避免重复检索
- **模糊需求追问**：首轮宽泛品类浏览（如"推荐一款精华"）自动进入 clarify 模式，先做品类教育再追问关键条件（肤质、预算、诉求），渲染为交互式选择卡片

### 四、后端服务化
- **SSE 流式 API**：`POST /chat` 接口使用 SSE 协议，支持 `text`（文本片段）、`product`（商品卡片）、`clarify`（追问卡片）、`bubble_break`（气泡分段）、`debug`（调试信息）、`[DONE]`（结束）六种事件类型
- **商品详情 API**：`GET /products/{id}` 返回商品元数据 + 关联 FAQ + 用户评价
- **语音识别 API**：`POST /asr` 接收音频文件，返回转写文本
- **服务预热**：启动时自动加载 Embedding、Reranker、ASR 模型，并预热 6 条高频查询缓存，减少首次请求延迟
- **错误处理**：RAG 预热失败不阻塞启动；LLM 超时有兜底；Query 改写失败回退原始查询

### 五、客户端工程与体验
- **原生 SSE 流式渲染**：Kotlin 原生解析 SSE 事件流，逐字追加渲染 AI 回复，类豆包打字机效果
- **Markdown 富文本渲染**：支持标题层级、加粗、列表、表格、引用块、图片等 Markdown 语法的原生渲染
- **商品卡片组件**：对话流中内嵌可点击的商品卡片（品名、价格、评分、主图），点击跳转详情页，详情页返回时恢复对话位置
- **交互式追问卡片**：clarify 模式下渲染带选项按钮的追问卡片，用户点选后自动拼接为新查询发送
- **语音输入**：集成麦克风录音，上传至后端 ASR 识别后自动填入输入框

### 六、加分项实现

#### 6.1 业务闭环 — 购物车与下单
- **对话式加购**：用户说"把这个加到购物车""加购小棕瓶"，客户端通过正则意图识别 + 关键词匹配定位商品，自动加入购物车
- **购物车管理**：支持自然语言删除（"删掉第二个"）、改数量（"把数量改成 3"），客户端本地解析执行
- **多 SKU 规格选择**：有多规格的商品（如衣服尺码/颜色），必须选择规格后才能加购；对话中加购多 SKU 商品时自动跳转详情页选规格
- **下单确认流程**：用户说"下单""买了"，Agent 引导确认收货地址，汇总订单信息，模拟完成下单闭环
- **购物车页面**：独立购物车页面展示已加购商品、数量、总价，支持增减数量和删除

#### 6.2 多模态交互
- **语音输入（ASR）**：集成 sherpa-onnx 离线语音识别模型，用户长按麦克风录音，后端识别为文字后走标准 RAG 流程

#### 6.3 对话智能与 RAG 增强
- **多轮上下文记忆**：支持追问和补充条件（"再便宜点的呢？""要轻量的"），Agent 通过 Query 改写保持上下文连贯
- **反选与排除**：正确处理否定语义（"不要含酒精的""除了耐克还有什么"），从候选集中排除匹配商品
- **多商品结构化对比**：用户要求对比 2-3 款商品时，Agent 自动提取关键维度生成对比表格 + 差异分析 + 结论建议
- **场景化跨品类推荐**：识别场景意图（"帮我搭配爬山装备""开学需要准备什么"），按预设模板跨品类检索（鞋服/防护/补给等），每个槽位独立检索 + Rerank，组合为分组推荐
- **别名/昵称扩展**：自动将用户口语昵称（小棕瓶、神仙水、飞马）映射为完整搜索词，提升召回率
- **品类硬过滤**：当 query 明确包含品类关键词时，用 ChromaDB metadata filter 强制限定 sub_category，解决 Embedding 对相近品类区分度不足的问题
- **Cross-Encoder Rerank**：粗召回后用 `bge-reranker-base` 二阶段精排，显著提升 top-N 精度
- **多数投票品类过滤**：统计粗召回结果的 sub_category 分布，保留主品类商品，去除跨品类噪音

#### 6.4 工程质量与性能优化
- **热门查询缓存**：LRU 缓存（128 条）缓存 RAG 检索结果，query 归一化后作为 key，相同问题命中缓存时跳过向量检索和 Rerank
- **Embedding 缓存**：相同文本不重复计算向量，减少 Embedding 推理次数
- **预设查询预热**：服务启动时预热 6 条高频查询（推荐笔记本、精华、户外装备等），首次用户请求直接命中缓存
- **Query 改写缓存**：相同 query + 上下文的改写结果缓存，避免重复调用 LLM
- **收藏状态双向同步**：商品卡片与详情页的收藏爱心状态实时同步，任一处操作另一处立即更新

## 技术架构

系统分为 **Android 客户端** 和 **FastAPI 服务端** 两层，通过 HTTP（SSE 流式）通信。

**Android 客户端（Kotlin 原生）**

- **MainActivity** — 主界面：对话页、商品详情页、购物车页、结算页
- **CartIntentParser** — 购物车意图识别：正则分流 + 关键词多维度打分匹配商品 + 序数词/批量支持
- **CartStore** — 购物车与收藏持久化（SharedPreferences）
- **MarkdownRenderer** — Markdown 富文本渲染：标题/列表/表格/引用/图片/加粗
- **ChatClient** — 网络通信：SSE 流式对话（POST /chat）、ASR 上传（POST /asr）、商品详情获取（GET /products）

**FastAPI 服务端（Python）**

- **路由层**（server/api/routes/）— 三个接口：POST /chat（SSE 流式对话）、POST /asr（语音识别）、GET /products/{id}（商品详情）
- **Orchestrator**（对话编排器）— 意图分类 → Query 改写 → RAG 检索/收窄 → Prompt 拼装 → LLM 流式生成 → SSE 事件流输出
- **Retriever**（RAG 检索）— 别名扩展 → 品类硬过滤 → 向量粗召回 → 多数投票品类过滤 → Reranker 精排 → 反选过滤 → 场景多槽位检索
- **SenseVoice ASR** — sherpa-onnx 离线语音识别
- **豆包 LLM**（Doubao-Seed-2.0-lite）— 意图分类、Query 改写、回复生成（流式 SSE）
- **ChromaDB**（向量数据库）— products 100 条 + chunks 892 条
- **本地 ML 模型** — Embedding: text2vec-base-chinese / Reranker: bge-reranker-base
- **4 层缓存** — RAG 检索 LRU 128 条 + Embedding LRU 1024 条 + Query 改写 LRU 256 条 + Prompt 文件 mtime 缓存

## 技术栈

| 层 | 技术 | 说明 |
|------|------|------|
| 客户端 | Android (Kotlin) | 原生开发，minSdk 26，targetSdk 35 |
| 后端框架 | FastAPI (Python 3.10+) | 异步 SSE 流式接口 |
| 大模型 | Doubao-Seed-2.0-lite | 字节豆包 API（OpenAI-compatible） |
| 向量数据库 | ChromaDB | 本地持久化，零配置 |
| Embedding | shibing624/text2vec-base-chinese | 中文语义向量，768 维 |
| Reranker | BAAI/bge-reranker-base | Cross-Encoder 二阶段精排 |
| ASR | sherpa-onnx | 端侧语音识别，离线可用 |
| 流式通信 | SSE (Server-Sent Events) | 逐字推送，低延迟 |

## 项目结构

```
rag-shopping-agent/
├── client/android/              # Android 原生客户端 (Kotlin)
│   └── app/src/main/
│       ├── java/.../MainActivity.kt     # 主界面（对话、详情页、购物车、结算、语音、动画）
│       ├── java/.../MarkdownRenderer.kt # Markdown → Spannable 渲染（标题/列表/表格/引用/图片）
│       ├── java/.../CartIntentParser.kt # 购物车意图分类 + 商品匹配（正则/序数词/关键词打分）
│       ├── java/.../ChatClient.kt       # SSE 流式通信 + ASR 上传 + 商品详情获取
│       ├── java/.../CartStore.kt        # 购物车/收藏本地持久化（SharedPreferences）
│       └── res/layout/activity_main.xml
│
├── server/                      # 后端服务 (Python)
│   ├── api/
│   │   ├── main.py              # FastAPI 入口（CORS、路由、预热）
│   │   └── routes/
│   │       ├── chat.py          # POST /chat — 对话接口（SSE 流式）
│   │       ├── products.py      # GET /products/{id} — 商品详情
│   │       └── asr.py           # POST /asr — 语音识别
│   ├── agent/
│   │   ├── orchestrator.py      # Agent 编排：意图分类 → RAG/收窄 → Prompt → LLM → SSE
│   │   └── prompts/
│   │       ├── system_prompt.md # 系统提示词（角色、路由、格式规范、自检清单）
│   │       └── chat_prompt.md   # 闲聊/元问题 prompt（球球人设）
│   ├── rag/
│   │   └── retriever.py         # RAG 检索（别名扩展 + 品类过滤 + 双路检索 + Rerank + 场景检索 + 缓存）
│   ├── asr/
│   │   └── recognizer.py        # ASR 语音识别（SenseVoice + 音频归一化 + 重采样）
│   ├── config/
│   │   └── settings.py          # 配置（从 .env 读取）
│   └── requirements.txt
│
├── data/
│   ├── raw/                     # 原始商品数据（100 条 + 图片）
│   ├── processed/
│   │   ├── products.jsonl       # 清洗后商品数据
│   │   └── chunks.jsonl         # FAQ + 用户评价片段
│   ├── scripts/
│   │   ├── clean.py             # 数据清洗
│   │   └── ingest.py            # 向量数据库入库
│   └── chroma_db/               # ChromaDB 持久化目录（本地生成）
│
├── docs/                        # 项目文档
├── .env                         # 环境变量（不入仓库）
└── .gitignore
```

## 快速体验

后端服务已部署在云端（`http://47.96.123.217:10005`），安装 APK 即可直接体验，无需配置环境。

1. 将 `app-debug.apk` 传输到 Android 手机并安装（需 Android 8.0+）
2. 打开 App，直接输入文字或长按麦克风说话

> 首次发送消息时云端会做一次模型预热，响应可能略慢（数秒），之后即恢复流畅的逐字流式效果。

## 从零本地部署

### 环境要求

- Python 3.10+
- Android Studio（Gradle 8.7.3 + Kotlin 2.0.21，编译客户端）
- Git（首次运行会自动下载 Embedding / Reranker 模型约 400MB，需联网）
- Android 设备（compileSdk 35 / minSdk 26 / targetSdk 35）

### 1. 克隆仓库

```bash
git clone https://github.com/pingfangww/rag-shopping-agent.git
cd rag-shopping-agent
```

### 2. 安装后端依赖

```bash
python3 -m venv .venv
source .venv/bin/activate       # Windows: .venv\Scripts\activate
pip install -r server/requirements.txt
```

> 首次安装会自动下载 Embedding 和 Reranker 模型（约 400MB），请确保网络通畅。

### 3. 配置环境变量

在项目根目录创建 `.env` 文件：

```
LLM_BASE_URL=https://ark.cn-beijing.volces.com/api/v3/
LLM_MODEL=ep-20260514111645-lmgt2
LLM_API_KEY=你的豆包_API_Key
VECTOR_DB_PATH=./data/chroma_db
```

### 4. 数据入库

将商品数据灌入 ChromaDB 向量数据库（首次约 2 分钟）：

```bash
# macOS 需设置（解决 libexpat 兼容问题）
export DYLD_LIBRARY_PATH="/opt/homebrew/opt/expat/lib"

python -m data.scripts.ingest
```

### 5. 启动后端

```bash
uvicorn server.api.main:app --host 0.0.0.0 --port 8000
```

启动后自动预热 RAG 与 ASR 模型。访问 http://localhost:8000/docs 验证服务正常，http://localhost:8000/hello 应返回 `hello world`。

### 6. 编译运行 Android 客户端

1. 用 Android Studio 打开 `client/android/` 目录，等待 Gradle 同步完成
2. 修改后端地址：编辑 `MainActivity.kt` 中的 `serverBaseUrl`：
   - 模拟器访问本机：`http://<本机IP>:8000`
   - 真机同局域网：`http://<电脑局域网IP>:8000`（如 `http://192.168.1.100:8000`）
   - 连接已部署云端：`http://47.96.123.217:10005`
3. 连接设备或启动模拟器，点击 Run

也可命令行直接打包 APK：

```bash
cd client/android
./gradlew :app:assembleDebug
# 产物：app/build/outputs/apk/debug/app-debug.apk
```

## API 接口

| 接口 | 方法 | 说明 |
|------|------|------|
| `/chat` | POST | 对话接口，SSE 流式返回文本和商品卡片事件 |
| `/products/{id}` | GET | 商品详情（含 FAQ、评价、SKU） |
| `/asr` | POST | 语音识别（上传音频文件，返回文字） |
| `/static/{path}` | GET | 商品图片静态资源 |

## 数据规模

- 100 条商品，覆盖 4 大品类（数码电子、美妆护肤、运动鞋服、食品饮料）
- 892 条检索片段（FAQ + 用户评价）
- 商品数据含多 SKU 规格、价格区间、品牌、子类目等结构化字段

qiuqiu-rag-shopping-agent

qiuqiu-rag-shopping-agent Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

qiuqiu-rag-shopping-agent

qiuqiu-rag-shopping-agent Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README