AI Agent - 智能助手系统
基于 LangGraph + FastAPI 的智能对话助手，支持多模型切换、RAG 检索、联网搜索、子图系统等。
目录
核心功能
对话能力
| 功能 | 说明 |
|---|---|
| 智能对话 | 多轮对话，自动记忆上下文 |
| 多模型切换 | 前端可选择不同 LLM |
| 流式响应 | SSE 流式输出，打字机效果 |
| 持久化记忆 | PostgreSQL 存储对话历史 |
工具系统
| 工具 | 说明 |
|---|---|
| RAG 检索 | 知识库检索，带置信度评估 |
| 联网搜索 | DuckDuckGo 免费搜索 |
| 通讯录 | 联系人管理、邮件处理 |
| 词典 | 翻译、术语提取、生词本 |
| 资讯分析 | 新闻检索、关键词提取 |
技术特性
- 模块化架构：清晰的代码分层，易于扩展
- 模型降级：多模型自动降级，保证高可用
- 子图系统：独立的工作流模块，按需调用
- 格式化输出：统一的 Markdown 格式化，支持模板
快速开始
环境要求
- Python 3.10+
- PostgreSQL（远程或本地）
- Qdrant 向量数据库（远程或本地）
安装依赖
cd backend
pip install -r requirements.txt
配置环境变量
cp .env.example .env
# 编辑 .env 填写必要的配置
启动服务
cd backend
python -m app.backend
# 服务运行在 http://localhost:8079
项目结构
backend/app/
├── agent/ # Agent 服务层
│ ├── agent_service.py # 主服务
│ ├── service_config.py # 配置构建
│ ├── stream_handler.py # 流式处理
│ ├── stream_context.py # 流式上下文
│ ├── history.py # 历史查询
│ └── prompts.py # 提示词
│
├── main_graph/ # 主图（LangGraph 工作流）
│ ├── main_graph_builder.py # 图构建器
│ ├── state.py # 状态定义
│ └── nodes/ # 节点实现
│ ├── agent.py # 推理节点
│ ├── tools.py # 工具执行
│ ├── finalize.py # 后处理
│ ├── memory_trigger.py # 记忆触发
│ ├── retrieve_memory.py # 记忆检索
│ └── summarize.py # 记忆摘要
│
├── tools/ # 工具定义
│ ├── rag.py # RAG 检索工具
│ ├── web_search.py # 联网搜索工具
│ └── subgraph.py # 子图调用工具
│
├── subgraphs/ # 子图模块
│ ├── contact/ # 通讯录子图
│ ├── dictionary/ # 词典子图
│ └── news_analysis/ # 资讯分析子图
│
├── core/ # 核心工具
│ ├── formatter.py # 格式化工具
│ ├── stream_finalizer.py # 流式格式化
│ ├── web_search.py # 搜索工具类
│ ├── visualization.py # 可视化图表
│ └── human_review.py # 人工审核
│
├── rag/ # RAG 检索系统
│ ├── pipeline.py # 检索流水线
│ ├── retriever.py # 检索器
│ ├── rerank.py # 重排
│ ├── fusion.py # 结果融合
│ └── query_transform.py # 查询改写
│
├── model_services/ # 模型服务层
│ ├── chat_services.py # 对话服务
│ ├── embedding_services.py # 嵌入服务
│ └── rerank_services.py # 重排服务
│
├── memory/ # 记忆系统
│ └── mem0_client.py # Mem0 客户端
│
├── templates/ # 输出模板
│ ├── error_notification.md # 错误提示
│ ├── web_search_result.md # 搜索结果
│ ├── knowledge_summary.md # 知识总结
│ └── conversation_summary.md # 对话摘要
│
├── middleware/ # 中间件
│ └── response_formatter.py # 响应格式化
│
├── db/ # 数据库
│ ├── models.py # 数据模型
│ └── init_db.py # 初始化
│
├── mcp/ # MCP 协议
│ ├── mcp_client.py # MCP 客户端
│ ├── mcp_manager.py # MCP 管理器
│ └── adapters/ # 适配器
│
├── config.py # 配置管理
├── logger.py # 日志工具
└── backend.py # FastAPI 应用
API 接口
对话接口
同步对话
POST /chat
Content-Type: application/json
{
"message": "你好",
"thread_id": "可选的会话ID",
"model": "local",
"user_id": "default_user"
}
响应：
{
"reply": "你好！有什么可以帮助你的？",
"thread_id": "生成的会话ID",
"model_used": "local",
"input_tokens": 100,
"output_tokens": 50,
"total_tokens": 150,
"elapsed_time": 1.23
}
流式对话
POST /chat/stream
Content-Type: application/json
{
"message": "你好",
"model": "local"
}
响应为 SSE 流式数据：
data: {"type": "llm_token", "node": "agent", "token": "你"}
data: {"type": "llm_token", "node": "agent", "token": "好"}
data: {"type": "done", "model_used": "local"}
data: [DONE]
历史接口
GET /threads?user_id=xxx&limit=10
GET /thread/{thread_id}/messages
GET /thread/{thread_id}/summary
审核接口
GET /reviews/pending
POST /reviews/{review_id}/approve
POST /reviews/{review_id}/reject
配置说明
环境变量
| 变量 | 说明 | 示例 |
|---|---|---|
DB_URI |
PostgreSQL 连接串 | postgresql://user:pass@host:5432/db |
QDRANT_URL |
Qdrant 地址 | http://localhost:6333 |
VLLM_BASE_URL |
本地 LLM 地址 | http://localhost:8000/v1 |
DEEPSEEK_API_KEY |
DeepSeek API Key | sk-xxx |
ZHIPUAI_API_KEY |
智谱 API Key | xxx |
模板定制
输出模板位于 app/templates/，可直接编辑 .md 文件调整格式：
## ⚠️ 操作失败
**错误类型**: {{ error_type }}
**错误详情**: {{ error_message }}
### 💡 建议操作
{{ suggestions }}
格式化输出
项目提供统一的格式化工具：
from backend.app.core import get_formatter
fmt = get_formatter()
# 渲染错误模板
error_out = fmt.render_error(
error_type="超时",
error_message="连接超时",
suggestions=["重试", "切换模型"]
)
# 渲染自定义模板
output = fmt.render("my_template", key="value")
# 流式结束后追加格式化内容
from backend.app.core import create_finalizer
finalizer = create_finalizer()
finalizer.add_table([{"姓名": "张三"}])
append_content = finalizer.build_append()