agent_proj/README.md

# 智扫通智能机器人客服

> 基于 LangChain + RAG + Agent 的智能问答系统，专注于扫地机器人和扫拖一体机器人的专业客服

## 项目简介

智扫通是一个基于大语言模型的智能客服系统，利用 LangChain 的 Agent 框架和 RAG (检索增强生成) 技术，为用户提供专业、准确的扫地机器人相关问答服务。

### 核心功能
- **智能问答**：基于 ReAct 框架的 Agent 自主工具调用
- **专业知识库**：通过 RAG 从向量库检索专业资料
- **个性化服务**：支持生成用户使用报告
- **多轮对话**：保持会话上下文，提供连贯回答
- **流式输出**：实时显示思考过程和回答内容

## 技术栈

| 类别 | 技术/框架 | 版本 |
|------|----------|------|
| 前端 | Streamlit | 最新 |
| AI 框架 | LangChain | >= 0.3.0 |
| 大语言模型 | 通义千问 (qwen3-max) | - |
| 向量数据库 | Chroma | 最新 |
| Embedding | DashScope (text-embedding-v4) | - |
| 配置管理 | YAML | - |
| 语言 | Python | 3.9+ |

## 安装指南

### 1. 环境要求
- Python 3.9 或更高版本
- 已配置阿里云 DashScope API 密钥

### 2. 安装依赖

```bash
# 克隆项目
git clone https://github.zhang-heng.com/czzhangheng/agent_proj
cd agent_proj

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

### 3. 配置环境变量

在项目根目录创建 `.env` 文件，添加以下内容：

```bash
# DashScope API 密钥
DASHSCOPE_API_KEY=your_api_key_here
```

### 4. 知识库初始化

首次运行前需要初始化知识库：

```bash
# 加载知识库到向量库
python -m rag.vector_store
```

## 快速开始

### 1. 启动 Web 应用

```bash
# 启动 Streamlit 应用
streamlit run app.py
```

### 2. 访问界面

打开浏览器访问：`http://localhost:8501`

### 3. 开始对话

在聊天输入框中输入问题，例如：
- "扫地机器人如何保养？"
- "推荐适合小户型的扫地机器人"
- "生成我的使用报告"

## 项目结构

```
agent_proj/
├── agent/               # Agent 核心模块
│   ├── tools/          # 工具定义和中间件
│   └── react_agent.py  # ReAct Agent 封装
│
├── config/             # 配置文件
│   ├── agent.yaml      # Agent 配置
│   ├── chroma.yaml     # 向量库配置
│   ├── prompts.yaml    # Prompt 路径配置
│   └── rag.yaml        # RAG 模型配置
│
├── data/               # 知识库和外部数据
│   ├── external/       # 外部数据 (CSV)
│   └── 知识库文件 (pdf/txt) # 专业资料
│
├── docs/               # 项目文档
│
├── model/              # 模型工厂
│   └── factory.py      # LLM/Embedding 模型创建
│
├── prompts/            # Prompt 模板
│   ├── main_prompt.txt # 主系统 Prompt
│   ├── rag_summarize.txt # RAG 总结 Prompt
│   └── report_prompt.txt # 报告生成 Prompt
│
├── rag/                # RAG 服务
│   ├── rag_service.py  # RAG 总结服务
│   └── vector_store.py # 向量存储服务
│
├── utils/              # 工具模块
│   ├── config_handler.py # 配置加载
│   ├── file_handler.py # 文件处理
│   ├── logger_handler.py # 日志管理
│   ├── path_tool.py    # 路径工具
│   └── prompt_loader.py # Prompt 加载
│
├── chroma_db/          # Chroma 向量数据库
├── logs/               # 日志目录
├── app.py              # Streamlit 主应用
├── requirements.txt    # 依赖列表
└── README.md           # 项目说明
```

## 核心模块

### Agent 模块
- **ReactAgent**：封装 LangChain Agent，实现 ReAct 思考框架
- **工具系统**：支持 7 种工具，包括 RAG 检索、天气查询、用户信息获取等
- **中间件**：监控工具调用、动态提示词切换、日志记录

### RAG 模块
- **向量存储**：基于 Chroma 实现知识向量存储
- **文档加载**：支持 PDF 和 TXT 文件
- **文本分片**：使用 RecursiveCharacterTextSplitter 进行智能分片
- **相似度检索**：基于余弦相似度的 Top-K 检索

### 模型管理
- **模型工厂**：统一管理 LLM 和 Embedding 模型
- **动态配置**：通过 YAML 配置文件管理模型参数

## 配置说明

### 1. RAG 配置 (`config/rag.yaml`)

```yaml
# 大语言模型
chat_model_name: "qwen3-max"

# Embedding 模型
embeddings_model_name: "text-embedding-v4"
```

### 2. 向量库配置 (`config/chroma.yaml`)

```yaml
# 集合名称
collection_name: "agent"

# 持久化目录
persist_directory: "chroma_db"

# 检索 Top-K
k: 3

# 数据目录
data_path: "data"

# 分片配置
chunk_size: 200
chunk_overlap: 20
separators: ["\n\n", "\n", ".", "!", "?", "。", "？", "！", " "]
```

### 3. Agent 配置 (`config/agent.yaml`)

```yaml
# 外部数据路径
external_data_path: "data/external/records.csv"
```

### 4. Prompt 配置 (`config/prompts.yaml`)

```yaml
# 主 Prompt 路径
main_prompt_path: "prompts/main_prompt.txt"

# RAG 总结 Prompt 路径
rag_summarize_prompt_path: "prompts/rag_summarize.txt"

# 报告 Prompt 路径
report_prompt_path: "prompts/report_prompt.txt"
```

## 使用示例

### 1. 基本问答

**用户**："扫地机器人如何处理毛发？"

**系统**：
```
我需要从知识库中检索关于扫地机器人处理毛发的专业信息，以便给出准确的回答。

[参考资料]: 扫地机器人在处理毛发时，应定期清理滚刷和边刷，建议每使用2-3次清理一次。对于宠物家庭，建议每天清理。部分高端机型配备防缠绕设计，可有效减少毛发缠绕问题。 | 参考源： {'source': 'data/维护保养.txt'}

扫地机器人处理毛发的建议：
1. 定期清理滚刷和边刷，每使用2-3次清理一次
2. 宠物家庭建议每天清理
3. 选择配备防缠绕设计的高端机型
4. 定期检查过滤网，避免毛发堵塞
```

### 2. 个性化报告

**用户**："生成我的使用报告"

**系统**：
```
我需要为用户生成使用报告，首先获取用户ID，然后获取当前月份，再调用报告上下文工具，最后获取用户的使用数据。

[工具调用] get_user_id
用户ID：1005

[工具调用] get_current_month
当前月份：2025-06

[工具调用] fill_context_for_report
fill_context_for_report已调用

[工具调用] fetch_external_data
用户1005在2025-06的使用数据：{'特征': '高效模式使用频繁', '效率': '平均清洁时间30分钟', '耗材': '滚刷损耗正常', '对比': '比上月提升15%'}

根据您的使用数据，以下是您的6月使用报告：

**使用特征**：高效模式使用频繁
**清洁效率**：平均清洁时间30分钟
**耗材状态**：滚刷损耗正常
**性能对比**：比上月提升15%

建议：继续保持良好的使用习惯，可考虑定期深度清洁机器内部。
```

## 常见问题

### Q1: 如何添加新的知识库文件？

1. 将 PDF 或 TXT 文件放入 `data/` 目录
2. 重新运行知识库初始化命令：
   ```bash
   python -m rag.vector_store
   ```

### Q2: 如何修改 Agent 的工具？

编辑 `agent/tools/agent_tools.py` 文件，添加或修改工具定义。

### Q3: 如何调整 RAG 检索效果？

修改 `config/chroma.yaml` 中的配置：
- `chunk_size`：调整文本分片大小
- `k`：调整检索的文档数量
- `separators`：调整文本分割策略

### Q4: 如何查看系统日志？

日志文件位于 `logs/` 目录，按日期命名。