智扫通 · SweepLink

一个面向扫地机器人与扫拖一体机器人的中文智能客服 Demo。项目使用 LangChain/LangGraph 组织 ReAct Agent，通过 DashScope 调用通义千问模型，并结合本地 Chroma 知识库回答选购、使用、维护和故障排查问题。

当前仓库定位为学习与作品展示项目，不是生产级客服系统。天气、位置、用户身份和个人报告数据均为本地模拟数据。

功能

• 基于本地 PDF/TXT 资料的 RAG 检索与总结（两阶段检索：Embedding 粗排 + Reranker 精排）
• 支持多轮对话的 Streamlit 聊天界面
• ReAct 工具调用与调用日志
• 模拟天气、位置、用户身份和月度使用报告
• 向量资料 MD5 去重，可重复执行知识库初始化
• 模型与向量服务延迟初始化，避免导入模块时访问外部服务

工作流程

flowchart LR
    U[用户] --> UI[Streamlit]
    UI --> A[ReAct Agent]
    A --> Q[通义千问]
    A --> T[业务工具]
    T --> R[RAG Service]
    R --> C[(本地 Chroma)]
    T --> D[脱敏样例数据]

Loading

环境要求

• Python 3.11（推荐 3.11.9）
• 一个可用的 DashScope API Key

本地运行

git clone <你的仓库地址>
cd <仓库目录>

python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

cp .env.example .env

编辑 .env，填入真实密钥：

DASHSCOPE_API_KEY=你的密钥

首次运行前构建本地知识库：

python -m rag.vector_store

该命令会调用 DashScope 嵌入模型并产生少量 API 用量。生成的数据库与导入状态位于 rag/chroma_db/，不会提交到 Git。

启动应用：

streamlit run app.py

浏览器通常会自动打开 http://localhost:8501。

开发与测试

python -m pip install -r requirements-dev.txt
ruff check .
pytest

测试通过 Mock 隔离模型和向量数据库，不需要真实 API Key，也不会产生外部 API 调用。GitHub Actions 会在 Python 3.11 下自动执行相同检查。

项目结构

agent/       Agent、工具与中间件
config/      模型、提示词、知识库配置
data/        可公开的领域资料和脱敏样例数据
model/       DashScope 模型工厂
prompts/     主对话、RAG 与报告提示词
rag/         文档导入、Chroma 检索与总结服务
tests/       离线单元测试
utils/       配置、文件、日志和路径工具
app.py       Streamlit 入口

配置

• config/rag.yml：聊天模型与嵌入模型名称
• config/chroma.yml：分块、检索数量、Reranker 精排、数据目录和持久化目录
• config/agent.yml：模拟外部数据路径
• config/prompts.yml：提示词文件路径

数据与隐私

知识文件及样例数据的用途和授权边界见 DATA_SOURCES.md。.env、运行日志、虚拟环境、本地 Chroma 数据库、编辑器配置和 Python 缓存均已被 .gitignore 排除。

已知限制

• 天气、位置和用户 ID 工具返回模拟结果，不应作为真实业务数据使用。
• CSV 外部数据仅用于演示；生产环境应替换为经过认证和授权的服务。
• 本地 Chroma 适合单机演示，不包含多实例同步、备份和迁移机制。
• 尚未实现登录、权限控制、速率限制、内容审计和生产监控。
• 模型回答可能存在错误；设备安全、维修和购买决策应以厂商资料为准。

License

代码采用 MIT License。数据文件不自动适用 MIT License，详见 DATA_SOURCES.md。