AI Agent - 智能助手系统

一个基于 LangGraph + FastAPI 的智能对话助手，支持多模型切换、RAG 知识库检索、文件处理和网页抓取等功能。

---

🎯 核心功能

面向用户的功能

• 💬 智能对话：支持多轮对话，自动记忆上下文
• 🌤️ 天气查询：实时获取各地天气信息
• 📄 文档处理：读取 TXT、PDF、Excel 等格式文件
• 🌐 网页抓取：提取网页正文内容
• 🔍 知识库检索（RAG）：基于向量数据库的智能问答
• 🔄 多模型切换：前端可选择不同大语言模型

技术特性

• ✅ 持久化记忆：PostgreSQL 存储对话历史，重启不丢失
• ✅ 高可用架构：模型自动降级，确保服务稳定
• ✅ 前后端分离：FastAPI 后端 + Streamlit 前端
• ✅ Docker 部署：一键启动所有服务
• ✅ 远程服务架构：PostgreSQL 和 Qdrant 部署在远程服务器

---

🏗️ 技术架构

技术栈

层级	技术选型	说明
LLM 服务	智谱 AI API / llama.cpp (Gemma-4 GGUF)	云端 API 或本地推理
Embedding	llama.cpp (embeddinggemma-300M GGUF)	本地向量嵌入服务
Agent 框架	LangGraph + LangChain	工作流编排
向量数据库	Qdrant	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│  │
│  │ - Memory   │  │
│  └────────────┘  │
└────────┬─────────┘
         │
    ┌────┴────────────────────┐
    ↓                         ↓
┌──────────────┐    ┌──────────────┐
│  PostgreSQL  │    │   Qdrant     │
│ (远程服务器)  │    │ (远程服务器)  │
│  115.190...  │    │  115.190...  │
└──────────────┘    └──────────────┘

项目结构

Agent1/
├── app/
│   ├── __init__.py
│   ├── config.py              # 配置管理
│   ├── state.py               # 状态定义
│   ├── prompts.py             # 提示模板
│   ├── logger.py              # 日志工具
│   ├── tools.py               # 工具函数定义
│   ├── memory/
│   │   ├── __init__.py
│   │   └── mem0_client.py     # Mem0 客户端封装
│   ├── nodes/
│   │   ├── __init__.py
│   │   ├── router.py          # 路由决策
│   │   ├── llm_call.py        # LLM 调用节点
│   │   ├── tool_call.py       # 工具执行节点
│   │   ├── retrieve_memory.py # 记忆检索节点
│   │   └── summarize.py       # 记忆存储节点
│   ├── graph_builder.py       # LangGraph 图构建器
│   ├── agent.py               # Agent 服务核心
│   └── backend.py             # FastAPI 后端应用
├── frontend/
│   └── app.py                 # Streamlit 前端界面
├── docker/
│   ├── 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.docker .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://127.0.0.1:8501
#   - 后端 API: http://127.0.0.1:8001

方式二：本地开发模式

# 1. 安装依赖
pip install -r requirement.txt

# 2. 配置环境变量
cp .env.docker .env
# 编辑 .env，根据本地/远程环境调整配置

# 3. 启动后端
python app/backend.py

# 4. 启动前端（新终端）
cd frontend && streamlit run app.py

---

📖 使用指南

基础对话

直接在聊天框输入问题即可：

你好，请介绍一下自己
今天北京天气怎么样？
帮我总结一下 a.txt 的内容

工具调用示例

功能	示例提问
🌤️ 天气查询	"上海今天天气如何？"
📄 读取文本	"读取 a.txt 的内容"
📑 解析 PDF	"总结 b.pdf 的主要内容"
📊 Excel 数据	"显示 c.xlsx 的数据"
🌐 网页抓取	"抓取 https://example.com 的内容"
🔍 长期记忆	"记住我喜欢吃川菜" → "我有什么饮食偏好？"

多模型切换

1. 在左侧边栏选择模型：

   • 智谱 GLM-4：在线服务，速度快
   • 本地 Gemma-4：本地部署，隐私性好

2. 可随时切换，甚至在同一会话中

3. 点击 "🔄 新会话" 清空当前对话

---

🔧 开发指南

添加新工具

在 app/tools.py 中添加新的 @tool 装饰函数：

@tool
def my_new_tool(param: str) -> str:
    """
    工具描述（会显示给 LLM）
    
    Args:
        param: 参数说明
        
    Returns:
        返回值说明
    """
    # 实现逻辑
    return result

工具会自动注册到 AVAILABLE_TOOLS 列表中。

添加新模型

在 app/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：服务编排（Backend + Frontend，连接远程数据库）
• Dockerfile.backend：后端镜像构建
• Dockerfile.frontend：前端镜像构建
• .gitea/workflows/deploy.yml：CI/CD 自动化部署

详见 QUICKSTART.md 的 Docker 部署章节。

---

⚙️ 环境配置

配置文件说明

项目采用三层环境配置文件体系：

文件	用途	是否提交 Git
.env.example	配置模板	✅ 是
.env	实际使用的配置	❌ 否（已忽略）
.env.docker	Docker 部署模板	✅ 是

使用方法：

• 本地开发：cp .env.example .env，修改为 127.0.0.1 相关地址
• Docker 部署：cp .env.docker .env，使用远程服务器地址

必需的环境变量

变量名	说明	本地开发示例	Docker 部署示例
QDRANT_URL	Qdrant 向量数据库地址	http://127.0.0.1:6333	http://your-server:6333
QDRANT_COLLECTION_NAME	Qdrant 集合名称	mem0_user_memories	your_collection_name
VLLM_BASE_URL	LLM 服务地址（本地）	http://127.0.0.1:8081/v1	http://your-server:8081/v1
LLAMACPP_EMBEDDING_URL	Embedding 服务地址（本地）	http://127.0.0.1:8082/v1	http://your-server:8082/v1
VLLM_BASE_URL	LLM 服务地址（Docker）	http://host.docker.internal:18000/v1	http://your-server:18000/v1
LLAMACPP_EMBEDDING_URL	Embedding 服务地址（Docker）	http://host.docker.internal:18001/v1	http://your-server:18001/v1
LLAMACPP_API_KEY	llama.cpp API 密钥	your-llamacpp-api-key	your-real-api-key
ZHIPUAI_API_KEY	智谱AI API密钥	your-zhipuai-api-key	your-real-api-key
DEEPSEEK_API_KEY	DeepSeek API密钥	your-deepseek-api-key	your-real-api-key
VLLM_BASE_URL	vLLM 服务地址	http://127.0.0.1:8081/v1	http://your-server:8081/v1
LOG_LEVEL	日志级别	INFO	DEBUG/INFO/WARNING/ERROR
ENABLE_GRAPH_TRACE	是否启用图流转追踪	true	true/false
MEMORY_SUMMARIZE_INTERVAL	对话摘要生成间隔	10	5/10/15

配置示例

本地开发 (.env)

ZHIPUAI_API_KEY=your_api_key_here
DEEPSEEK_API_KEY=your_deepseek_api_key_here
LLAMACPP_API_KEY=token-abc123
VLLM_BASE_URL=http://127.0.0.1:8081/v1
LLAMACPP_EMBEDDING_URL=http://127.0.0.1:8082/v1  # 本地开发
# 或
LLAMACPP_EMBEDDING_URL=http://host.docker.internal:18001/v1  # Docker容器访问宿主机
QDRANT_URL=http://115.190.121.151:6333
DB_URI=postgresql://postgres:huang1998@115.190.121.151:5432/langgraph_db?sslmode=disable
API_URL=http://127.0.0.1:8083/chat

Docker 部署 (.env.docker)

ZHIPUAI_API_KEY=your_api_key_here
DEEPSEEK_API_KEY=your_deepseek_api_key_here
LLAMACPP_API_KEY=token-abc123
VLLM_BASE_URL=http://127.0.0.1:8081/v1
LLAMACPP_EMBEDDING_URL=http://127.0.0.1:8082/v1  # 本地开发
# 或
LLAMACPP_EMBEDDING_URL=http://host.docker.internal:18001/v1  # Docker容器访问宿主机
QDRANT_URL=http://115.190.121.151:6333
DB_URI=postgresql://postgres:huang1998@115.190.121.151:5432/langgraph_db?sslmode=disable
# API_URL 在 docker-compose.yml 中配置为 http://backend:8083/chat

注意事项

• ⚠️ 不要硬编码敏感信息：所有 API Key 必须通过环境变量配置
• ⚠️ 远程服务依赖：确保可以访问远程 PostgreSQL (115.190.121.151:5432) 和 Qdrant (115.190.121.151:6333)
• ⚠️ 修改后重启：修改 .env 后，Docker 部署需要执行 docker compose down && docker compose up -d --build

---

🐛 故障排查

常见问题

Q: 无法连接远程数据库？

# 测试 PostgreSQL
psql -h 115.190.121.151 -U postgres -d langgraph_db -c "SELECT version();"

# 测试 Qdrant
curl http://115.190.121.151:6333/collections

Q: 后端启动失败？

• 确认端口 8001 未被占用
• 检查 .env 中的 API Key 是否正确
• 查看启动日志确认模型初始化成功

Q: 模型切换后无响应？

• 检查所选模型的配置是否正确
• 确认 vLLM 容器是否运行（如使用本地模型）
• 尝试切换到另一个模型

更多问题排查请查看 QUICKSTART.md

---

📝 许可证

本项目采用 MIT 许可证。详见 LICENSE 文件。

🤝 贡献

欢迎提交 Issue 和 Pull Request！