AI Agent - 智能助手系统
一个基于 LangGraph + FastAPI 的智能对话助手，支持多模型切换、RAG 知识库检索、文件处理和网页抓取等功能。
🎯 核心功能
面向用户的功能
- 💬 智能对话：支持多轮对话，自动记忆上下文
- 🌤️ 天气查询：实时获取各地天气信息
- 📄 文档处理：读取 TXT、PDF、Excel 等格式文件
- 🌐 网页抓取：提取网页正文内容
- 🔍 知识库检索（RAG）：基于向量数据库的智能问答
- 🔄 多模型切换：前端可选择不同大语言模型
技术特性
- ✅ 持久化记忆：PostgreSQL 存储对话历史，重启不丢失
- ✅ 高可用架构：模型自动降级，确保服务稳定
- ✅ 前后端分离：FastAPI 后端 + Streamlit 前端
- ✅ Docker 部署：一键启动所有服务
🏗️ 技术架构
技术栈
| 层级 | 技术选型 | 说明 |
|---|---|---|
| LLM 服务 | 智谱 AI API / vLLM (Gemma-4) | 云端 API 或本地推理 |
| Embedding | 智谱 Embedding API | 向量嵌入（无需 PyTorch） |
| Agent 框架 | LangGraph + LangChain | 工作流编排 |
| 向量数据库 | ChromaDB / pgvector | RAG 知识检索 |
| 后端框架 | FastAPI + Uvicorn | RESTful API + WebSocket |
| 前端框架 | Streamlit | 交互式 Web 界面 |
| 数据库 | PostgreSQL 16 | 对话记忆持久化 |
| 容器化 | Docker + Docker Compose | 服务编排 |
架构图
┌──────────────┐
│ 用户浏览器 │ Streamlit 前端 (8501)
└──────┬───────┘
│ HTTP/WebSocket
↓
┌──────────────────┐
│ FastAPI 后端 │ 端口 8001
│ ┌────────────┐ │
│ │ AIAgent │ │ 多模型管理
│ └─────┬──────┘ │
│ │ │
│ ┌─────▼──────┐ │
│ │LangGraph │ │ 工作流引擎
│ │ StateGraph │ │
│ └─────┬──────┘ │
│ │ │
│ ┌─────▼──────┐ │
│ │ Tools │ │ 工具集合
│ │ - Weather │ │
│ │ - File IO │ │
│ │ - Web Scrap│ │
│ │ - RAG │ │
│ └────────────┘ │
└────────┬─────────┘
│
┌────┴────┐
↓ ↓
┌────────┐ ┌──────────┐
│PostgreSQL│ │ChromaDB │
│(记忆存储)│ │(向量检索)│
└────────┘ └──────────┘
项目结构
Agent1/
├── agent.py # Agent 服务核心（多模型管理）
├── graph_builder.py # LangGraph 状态图构建器
├── tools.py # 工具函数定义（@tool 装饰器）
├── backend.py # FastAPI 后端应用
├── frontend.py # Streamlit 前端界面
├── rag_example.py # RAG 实现示例（无 PyTorch）
├── docker-compose.yml # Docker 服务编排
├── Dockerfile.backend # 后端镜像构建
├── Dockerfile.frontend # 前端镜像构建
├── requirement.txt # Python 依赖
├── .env # 环境变量配置
└── user_docs/ # 用户文档目录
├── a.txt
├── b.pdf
└── c.xlsx
🚀 快速开始
详细启动指南请查看 QUICKSTART.md
方式一：Docker Compose（推荐）
# 1. 配置环境变量
cp .env.example .env
# 编辑 .env 文件，填入真实的 API Key
# 2. 启动所有服务
docker compose -f docker/docker-compose.yml up -d --build
# 3. 访问应用
# 如果配置了 Nginx 反向代理：http://your-domain.com 或 http://your-server-ip
# 如果未配置 Nginx（直接访问）：
# - 前端: http://localhost:8501
# - 后端 API: http://localhost:8001
方式二：本地开发模式
# 1. 启动 PostgreSQL
docker run -d --name postgres-langgraph \
-e POSTGRES_PASSWORD=mysecretpassword \
-e POSTGRES_DB=langgraph_db \
-p 5432:5432 postgres:16
# 2. 安装依赖
pip install -r requirement.txt
# 3. 启动后端
python backend.py
# 4. 启动前端（新终端）
streamlit run frontend.py
📖 使用指南
基础对话
直接在聊天框输入问题即可：
你好，请介绍一下自己
今天北京天气怎么样？
帮我总结一下 a.txt 的内容
工具调用示例
| 功能 | 示例提问 |
|---|---|
| 🌤️ 天气查询 | "上海今天天气如何？" |
| 📄 读取文本 | "读取 a.txt 的内容" |
| 📑 解析 PDF | "总结 b.pdf 的主要内容" |
| 📊 Excel 数据 | "显示 c.xlsx 的数据" |
| 🌐 网页抓取 | "抓取 https://example.com 的内容" |
| 🔍 知识库检索 | "根据知识库回答：XXX" |
多模型切换
-
在左侧边栏选择模型：
- 智谱 GLM-4：在线服务，速度快
- 本地 Gemma-4：本地部署，隐私性好
-
可随时切换，甚至在同一会话中
-
点击 "🔄 新会话" 清空当前对话
🔧 开发指南
添加新工具
在 tools.py 中添加新的 @tool 装饰函数：
@tool
def my_new_tool(param: str) -> str:
"""
工具描述（会显示给 LLM）
Args:
param: 参数说明
Returns:
返回值说明
"""
# 实现逻辑
return result
工具会自动注册到 AVAILABLE_TOOLS 列表中。
添加新模型
在 agent.py 的 initialize() 方法中添加模型配置：
model_configs = {
"zhipu": self._create_zhipu_llm,
"local": self._create_local_llm,
"new_model": self._create_new_model_llm, # 添加新模型
}
Docker 部署
项目包含完整的 Docker 配置：
- docker-compose.yml：服务编排（PostgreSQL + Backend + Frontend）
- Dockerfile.backend：后端镜像构建
- Dockerfile.frontend：前端镜像构建
- .gitea/workflows/deploy.yml：CI/CD 自动化部署
详见 QUICKSTART.md 的 Docker 部署章节。
⚙️ 环境配置
必需的环境变量
在 .env 文件中配置：
# 智谱 AI API Key（必需）
ZHIPUAI_API_KEY=your_api_key_here
# vLLM 本地模型 Token（可选）
VLLM_LOCAL_KEY=token-abc123
数据库配置
默认使用 PostgreSQL，连接字符串：
postgresql://postgres:mysecretpassword@localhost:5432/langgraph_db
注意：
- 本地开发模式：使用
localhost或127.0.0.1 - Docker Compose 部署：后端容器内应使用服务名
postgres（通过环境变量DB_URI自动配置）
如使用 Docker Compose，数据库会在内部网络中自动配置。
🐛 故障排查
常见问题
Q: 无法连接 PostgreSQL？
# 检查容器状态
docker ps | grep postgres
# 查看日志
docker logs postgres-langgraph
Q: 后端启动失败？
- 确认端口 8001 未被占用
- 检查
.env中的 API Key 是否正确 - 查看启动日志确认模型初始化成功
Q: 模型切换后无响应？
- 检查所选模型的配置是否正确
- 确认 vLLM 容器是否运行（如使用本地模型）
- 尝试切换到另一个模型
更多问题排查请查看 QUICKSTART.md
📝 许可证
本项目采用 MIT 许可证。详见 LICENSE 文件。
🤝 贡献
欢迎提交 Issue 和 Pull Request！