扫地机器人智能助手

基于 LangChain Agent（ReAct 模式）+ RAG 检索增强 + FastAPI 流式接口 + Next.js 前端 的扫地 / 扫拖一体机器人智能客服系统。

用户可以通过 Web 聊天界面，获取扫地机器人的个人使用情况报告、月度使用报告、保养建议、故障排查与选购指南等专业回答。Agent 在回答时会自动调用工具（如检索知识库、获取用户信息、拉取外部使用记录），前端以流式方式实时展示思考过程、工具调用过程和最终回答。

核心功能

• 智能对话客服：基于 ReAct 思考循环（思考 → 行动 → 观察 → 再思考），回答扫地机器人相关知识
• 个人使用报告生成：按固定流程（获取用户 ID → 获取月份 → 注入报告上下文 → 拉取外部使用记录）生成个性化使用报告与保养建议，并自动切换专属报告提示词
• RAG 知识库检索：对产品介绍、使用指南、常见问题、选购指南等文档进行向量化存储，回答时检索相关参考资料
• 外部数据集成：从 record.csv 读取指定用户在指定月份的使用记录（清洁效率、耗材状态、同期对比）
• Web 聊天界面：流式（SSE）输出、Markdown 渲染、思考过程与工具调用过程可视化展示

技术栈

端	技术
后端	Python 3.14、LangChain 1.x、LangGraph、ChromaDB、DashScope（通义千问 qwen3-max / text-embedding-v4）、FastAPI、Uvicorn
前端	Next.js 16（App Router）、React 19、TypeScript、Tailwind CSS v4、react-markdown
数据	本地向量库（ChromaDB）、外部使用记录 CSV

项目结构

LLM学习/
├── Agent/                        # Python 后端
│   ├── agent/
│   │   ├── react_agent.py        # ReAct Agent 定义与流式执行
│   │   └── tools/
│   │       ├── agent_tools.py    # 工具定义（RAG / 天气 / 用户信息 / 外部数据等）
│   │       └── middleware.py     # 中间件（工具监控、日志、报告提示词切换）
│   ├── rag/
│   │   ├── rag_service.py        # RAG 检索 + 生成服务
│   │   └── vector_store.py       # ChromaDB 向量库封装
│   ├── model/
│   │   └── factory.py            # 大模型 / 向量模型工厂
│   ├── config/                   # 配置（agent.yml / rag.yml / chroma.yml / prompts.yml）
│   ├── prompts/                  # 提示词（主提示词 / RAG 提示词 / 报告提示词）
│   ├── utils/                    # 配置加载、日志、路径等工具
│   ├── api_server.py             # FastAPI 接口（SSE 流式聊天）
│   └── requirements.txt          # 后端依赖
├── web/                          # Next.js 前端
│   └── app/
│       ├── page.tsx              # 聊天主界面（流式渲染、工具过程展示）
│       ├── layout.tsx            # 根布局
│       └── api/chat/route.ts     # 后端代理路由（转发到 FastAPI）
├── data/                         # 知识库文档与外部数据
│   ├── external/record.csv       # 用户使用记录（外部数据源）
│   ├── 扫地机器人_产品介绍.txt
│   ├── 扫地机器人_使用指南.pdf
│   ├── 扫地机器人_常见问题.txt
│   └── 扫地机器人_选购指南.pdf
└── .env                          # API Key 等环境变量（DASHSCOPE_API_KEY）

快速开始

1. 后端

# 进入后端目录
cd Agent

# 创建并激活虚拟环境（Python 3.14）
python -m venv .venv
.venv\Scripts\activate        # Windows

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

# 配置 API Key：在项目根目录 .env 中填写
# DASHSCOPE_API_KEY=sk-xxxx

# 启动 API 服务（默认 http://127.0.0.1:8000）
python api_server.py

首次运行会自动把 data/ 下的知识库文档向量化写入 ChromaDB（持久化目录见 config/chroma.yml）。

2. 前端

# 进入前端目录
cd web

# 安装依赖
npm install

# 启动开发服务器（默认 http://localhost:3000）
npm run dev

浏览器打开 http://localhost:3000 即可开始对话。

3. 验证

• 后端健康检查：http://127.0.0.1:8000/
• 前端页面：http://localhost:3000
• 前端会将 /api/chat 请求代理到后端 http://127.0.0.1:8000/api/chat，也可通过环境变量 BACKEND_URL 修改后端地址

使用示例

打开前端页面后，可以直接尝试：

• 生成我的使用报告
• 获取我的使用情况
• 扫地机器人保养建议
• 小户型适合哪种扫地机器人
• 扫地机异响怎么排查

Agent 会在回答中自动调用相关工具，前端会实时展示工具调用过程与最终回答。

API 说明

POST /api/chat

流式聊天接口，返回 SSE（Server-Sent Events）格式。

请求体：

{ "query": "生成我的使用报告" }

响应事件（data: <json>，每个事件以空行分隔）：

type	说明
reasoning	模型调用工具前的思考 / 说明文本
tool	工具调用过程，status 为 start / done，done 时附带结果摘要
token	最终回答的文本内容
done	流式输出结束
error	出错信息

配置说明

文件	说明
Agent/config/agent.yml	模型名与外部数据路径
Agent/config/rag.yml	RAG 模型、知识库数据路径、切分参数
Agent/config/chroma.yml	向量库集合名、持久化目录、检索数量 k、文件类型过滤
Agent/config/prompts.yml	提示词文件路径
.env	DASHSCOPE_API_KEY 等密钥

说明

本项目为学习 / 演示用途，天气与用户信息等工具返回的数据为模拟数据，接入真实系统时请替换为真实服务实现。