# 黑马Agent升级：基于LangChain和RAG的智能客服

**Repository Path**: leke_code/longchain

## Basic Information

- **Project Name**: 黑马Agent升级：基于LangChain和RAG的智能客服
- **Description**: 基于 LangChain 的服装购买与知识问答客服项目，已从基础 RAG 升级为“可检索 + 可推荐 + 可追溯”的电商客服 Agent。接入阿里通义千问Qwen实现
- **Primary Language**: Python
- **License**: GPL-3.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 3
- **Created**: 2026-03-18
- **Last Updated**: 2026-03-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 智能服装客服（LangChain RAG 升级版）

这是一个基于 LangChain 的服装购买与知识问答客服项目，已从基础 RAG 升级为“可检索 + 可推荐 + 可追溯”的电商客服 Agent。

## 核心升级点

1. 混合检索
- 向量相似度检索 + MMR 多样性检索 + 关键词轻量重排。
- 相比单一 `top-k`，能减少漏召回，提升回答稳定性。

2. 业务工具层
- 内置 `BusinessTools`：
  - 尺码建议（身高/体重解析与规则推荐）
  - 商品推荐（风格/季节/预算的规则匹配）
  - 售后政策知识（退换货标准化回答）
- 业务工具结果与知识库检索结果融合后再交给大模型生成回答。

3. 来源可追溯
- 检索内容会注入“可引用来源”，让客服回答更可解释，方便后续审计与质检。

4. 会话级记忆
- 基于文件持久化的 `RunnableWithMessageHistory`，支持多 Session 历史隔离。

5. 工程化包装
- `requirements.txt`：统一依赖
- `.env.example`：统一配置模板
- Streamlit UI 升级：会话 ID 管理、历史清空、示例问题

## 混合检索实现详解（向量 Similarity + MMR + 关键词轻量重排）

本项目在 [`vector_stores.py`](/Users/zhangkaixuan/PycharmProjects/RAG/vector_stores.py) 中实现了三阶段混合检索，替代传统“单一路径 top-k”。

### 1. 为什么单一 top-k 容易漏召回

单一向量 `similarity_search(query, k)` 常见问题：

- 语义相近但信息重复：返回多段内容都在讲同一件事，覆盖面不够。
- 业务关键词弱化：电商场景里“退换货、尺码、预算”等词有时在纯语义里权重不够，容易丢关键片段。
- 查询表达变化敏感：用户换一种问法，top-k 的结果波动可能较大，导致回答稳定性下降。

### 2. 本项目三阶段检索流程

输入问题 `query` 后按以下流程执行：

1. 向量相似度召回  
调用 `similarity_search(query, k=config.top_k)` 获取最语义相似的一批文档。

2. MMR 多样性召回  
调用 `max_marginal_relevance_search(query, k=config.mmr_k)` 获取“相关且彼此不那么重复”的文档。

3. 合并去重 + 关键词轻量重排  
将两路结果合并，按 `page_content + metadata` 去重，再按关键词重叠分数排序，取前 `config.hybrid_top_k`。

对应核心入口：

- 检索函数：`VectorStoreService.retrieve_documents(query)`
- 关键词打分函数：`VectorStoreService._keyword_overlap_score(query, text)`

### 3. MMR 在这里的作用

可以把 MMR 理解为“相关性 + 新信息量”的平衡：

- 只看相关性：容易拿到高度重复片段。
- 加入多样性约束：更容易覆盖“尺码、颜色、洗护、售后”等不同子主题。

这对客服场景非常关键，因为一轮回答通常需要同时包含多个维度的信息，而不是只命中一个点。

### 4. 关键词轻量重排是怎么做的

本项目没有引入额外 reranker 模型，而是做了轻量规则重排（低成本、易维护）：

- 将 `query` 和候选文档 `text` 做简单分词（按空白拆分）；
- 计算重叠比例：`overlap = |query_tokens ∩ text_tokens| / |query_tokens|`；
- 按重叠分数降序排序。

收益：

- 可以补偿纯向量检索对高价值业务词的忽略；
- 在不增加外部模型调用成本的情况下，提升命中稳定性。

说明：中文场景下若要进一步提升效果，可替换为更好的分词策略（如 jieba）或接入专业 reranker。

### 5. 在 RAG 主链路中的接入方式

在 [`rag.py`](/Users/zhangkaixuan/PycharmProjects/RAG/rag.py) 中：

1. `_retrieve_bundle(query)` 调用 `retrieve_documents(query)`；
2. 将文档格式化为 `retrieved_context`（正文）和 `source_hints`（来源列表）；
3. 与 `business_context`（业务工具输出）合并后注入 Prompt；
4. 模型最终生成答案。

这使得回答不只“语义相关”，还具备“业务可用性 + 来源可追溯”。

### 6. 可调参数与建议

配置位置：[`config_data.py`](/Users/zhangkaixuan/PycharmProjects/RAG/config_data.py) 或 `.env`

- `TOP_K`：相似度召回数量（默认 4）
- `MMR_K`：MMR 召回数量（默认 4）
- `HYBRID_TOP_K`：最终输出给 LLM 的文档数（默认 5）

建议：

- 若回答经常“信息不全”：适当提高 `TOP_K/MMR_K`；
- 若回答太啰嗦或噪声大：降低 `HYBRID_TOP_K`；
- 若业务词命中弱：保留轻量重排并考虑升级为专用 reranker。

## 项目结构

```text
.
├── app_qa.py                # 客服问答前端
├── app_file_uploader.py     # 知识库上传前端
├── rag.py                   # RAG主服务（混合检索+业务工具+会话记忆）
├── vector_stores.py         # 混合检索与重排
├── business_tools.py        # 尺码/搭配/售后业务工具
├── product_catalog.py       # 内置商品样例库
├── knowledge_base.py        # 文本切片与向量写入
├── file_history_store.py    # 会话历史持久化
├── config_data.py           # 配置中心（支持环境变量）
├── data/                    # 知识库文本
└── requirements.txt
```

## 快速开始

1. 安装依赖
```bash
pip install -r requirements.txt
```

2. 配置环境变量
```bash
cp .env.example .env
```
然后设置 `DASHSCOPE_API_KEY`。

3. 启动知识库上传服务
```bash
streamlit run app_file_uploader.py
```

4. 启动客服问答服务
```bash
streamlit run app_qa.py
```

## todo

1. 加入商品库存/价格实时接口（Tools 调用 ERP 或商城 API）。
2. 引入 reranker 模型（如 bge-reranker）替换当前轻量重排。
3. 增加用户画像记忆（尺码偏好、颜色偏好、预算区间）做个性化推荐。
4. 接入埋点与评估集（回答准确率、转化率、平均响应时长）形成闭环优化。