agent_proj/docs/PROJECT_OUTLINE.md

智扫通智能客服项目 - 项目大纲

1. 项目概述

项目名称: 智扫通智能机器人客服

项目类型: 基于 LangChain + RAG + Agent 的智能问答系统

核心功能:

• 提供扫地机器人/扫拖一体机器人的专业智能客服
• 支持 ReAct 思考框架的 Agent 自主工具调用
• 基于向量检索(RAG)的专业知识库问答
• 个性化用户报告生成

目标用户: 扫地机器人用户

---

2. 技术架构

2.1 技术栈

层级	技术/框架	用途
前端	Streamlit	Web 交互界面
AI Agent	LangChain + LangGraph	Agent 推理与工具调用
LLM	通义千问 (qwen3-max)	大语言模型
向量数据库	Chroma	知识向量存储与检索
Embedding	DashScope (text-embedding-v4)	文本向量化
配置管理	YAML	配置文件管理

2.2 系统架构图

┌─────────────────────────────────────────────────────────┐
│                     Streamlit Web UI                    │
└─────────────────────┬───────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────┐
│                    ReactAgent (Agent)                   │
│  ┌─────────────────────────────────────────────────┐    │
│  │           ReAct 思考框架                          │    │
│  │    Thought → Action → Observation → ...        │    │
│  └─────────────────────────────────────────────────┘    │
│                         │                                 │
│           ┌─────────────┼─────────────┐                   │
│           ▼             ▼             ▼                   │
│  ┌──────────────┐ ┌───────────┐ ┌──────────────┐          │
│  │ RAG工具      │ │ 天气工具   │ │ 用户信息工具  │          │
│  │ rag_summarize│ │ get_weather│ │ get_user_id │          │
│  └──────────────┘ └───────────┘ └──────────────┘          │
│                         │                                 │
│  ┌──────────────────────────────────────────────────┐    │
│  │           Middleware 中间件                       │    │
│  │  monitor_tool | log_before_model | prompt_switch│    │
│  └──────────────────────────────────────────────────┘    │
└─────────────────────┬───────────────────────────────────┘
                      │
          ┌───────────┴───────────┐
          ▼                       ▼
┌─────────────────┐      ┌─────────────────────┐
│  VectorStore    │      │   外部数据源         │
│  (Chroma DB)    │      │   (CSV 用户记录)     │
└─────────────────┘      └─────────────────────┘

---

3. 目录结构

agent_proj/
├── agent/                          # Agent 核心模块
│   ├── tools/
│   │   ├── agent_tools.py         # Agent 工具定义
│   │   └── middleware.py          # 中间件实现
│   └── react_agent.py             # ReAct Agent 封装
│
├── config/                         # 配置文件
│   ├── agent.yaml                  # Agent 配置
│   ├── chroma.yaml                 # Chroma 向量库配置
│   ├── prompts.yaml                # Prompt 路径配置
│   └── rag.yaml                    # RAG 模型配置
│
├── data/                           # 数据目录
│   ├── external/
│   │   └── records.csv            # 用户使用记录
│   └── 知识库文件 (pdf/txt)         # RAG 知识库
│
├── 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 主应用
├── 01_Agent.py                     # Agent 基础示例
├── 02_Stream.py                    # Stream 流式输出示例
├── 03_ReAct.py                     # ReAct 框架示例
└── 04_middle_ware.py               # 中间件示例

---

4. 核心模块详解

4.1 Agent 模块 (agent/)

react_agent.py

• 职责: 封装 LangChain Agent，提供流式输出能力
• 核心方法: excute_stream(query) - 流式执行用户查询

agent_tools.py

• 职责: 定义 Agent 可调用的工具
• 工具列表:
  • rag_summarize: 向量库检索专业资料
  • get_weather: 查询城市天气
  • get_user_location: 获取用户所在城市
  • get_user_id: 获取用户ID
  • get_current_month: 获取当前月份
  • fetch_external_data: 获取外部用户使用记录
  • fill_context_for_report: 触发报告生成上下文

middleware.py

• 职责: 实现 Agent 中间件
• 中间件列表:
  • monitor_tool: 工具调用监控
  • log_before_model: 模型调用前日志
  • repoet_prompt_switch: 动态提示词切换

4.2 RAG 模块 (rag/)

vector_store.py

• 职责: 向量存储与检索
• 功能:
  • 文档加载 (PDF/TXT)
  • 文本分片 (RecursiveCharacterTextSplitter)
  • 向量入库 (Chroma)
  • 相似度检索 (Retriever)

rag_service.py

• 职责: RAG 总结服务
• 流程: 用户查询 → 向量检索 → Prompt 模板 → LLM 总结 → 返回结果

4.3 模型工厂 (model/factory.py)

• ChatModelFactory: 创建通义千问聊天模型
• EmbeddingsFactory: 创建 DashScope Embedding 模型

4.4 工具模块 (utils/)

模块	功能
config_handler	YAML 配置文件加载
logger_handler	日志管理 (双写: 控制台+文件)
prompt_loader	Prompt 模板加载
file_handler	PDF/TXT 文件加载, MD5 计算
path_tool	绝对路径获取

---

5. 数据流

5.1 知识库构建流程

知识库文件 (PDF/TXT)
        │
        ▼
   文件加载器 (PyPDFLoader/TextLoader)
        │
        ▼
   文本分片 (RecursiveCharacterTextSplitter)
        │
        ▼
   向量化 (DashScope Embeddings)
        │
        ▼
   Chroma 向量库存储
        │
        ▼
   MD5 去重记录

5.2 用户问答流程

用户提问
   │
   ▼
Streamlit UI 接收
   │
   ▼
ReactAgent.excute_stream()
   │
   ▼
ReAct Agent 推理循环
   │
   ├─→ 判断是否需要调用工具
   ├─→ 选择工具 (RAG/天气/用户信息/外部数据)
   ├─→ 执行工具获取结果
   ├─→ 观察结果，更新思考
   └─→ 生成最终回答
   │
   ▼
流式输出到 UI

---

6. 配置说明

6.1 rag.yaml

chat_model_name: "qwen3-max"        # LLM 模型
embeddings_model_name: "text-embedding-v4"  # Embedding 模型

6.2 chroma.yaml

collection_name: "agent"             # 向量库集合名
persist_directory: "chroma_db"       # 持久化目录
k: 3                                  # 检索Top-K
chunk_size: 200                       # 分片大小
chunk_overlap: 20                     # 分片重叠

6.3 agent.yaml

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

---

7. 运行方式

7.1 启动 Web 应用

streamlit run app.py

7.2 知识库初始化

python -m rag.vector_store

---

8. 面试要点总结

知识点	项目中的应用
LangChain Agent	create_agent, ReAct 框架
LangGraph	中间件机制, 动态提示词
RAG	向量检索, 文档分片, Chain 组合
Chroma	向量数据库存储与检索
Streamlit	Web 前后端交互
中间件模式	工具调用监控, 动态 Prompt
设计模式	工厂模式, 配置中心化