可快速搭建生产级智能问答系统,支持多角色路由、RAG知识库问答、多轮对话记忆及工具调用,具备容器化部署、可观测性和水平扩展能力。【此简介由AI生成】
Access rate limit exceeded. Please log in to continue.
LangGraph Enterprise Agent
企业级 LangGraph 智能问答 Agent —— 生产级部署模板,支持多角色路由、RAG、持久化记忆、可观测性。
项目简介
本项目是一个基于 LangGraph 和 FastAPI 构建的生产级智能问答 Agent 系统,提供以下核心能力:
- ✅ 智能角色路由:根据用户问题自动切换程序员、文案、数据分析师三种专家角色
- ✅ RAG 知识库问答:上传 PDF/文档,基于向量检索增强生成
- ✅ 多轮对话记忆:使用检查点持久化,支持跨会话恢复
- ✅ 工具调用:内置计算器、代码执行、时间查询等工具
- ✅ 生产级部署:Docker 容器化、Gunicorn + Uvicorn、健康检查、结构化日志
- ✅ 可观测性:请求 ID 追踪、Prometheus 指标、结构化 JSON 日志
- ✅ 水平扩展:支持 PostgreSQL/Redis 共享状态,多实例无状态部署
技术栈
| 组件 | 技术选型 |
|---|---|
| 工作流编排 | LangGraph 0.4+ |
| Web 框架 | FastAPI + Uvicorn |
| 大模型 | OpenAI GPT / Ollama 本地模型 |
| 向量数据库 | Chroma(可替换 Qdrant/Pinecone) |
| 持久化 | SQLite / PostgreSQL / Redis |
| 容器化 | Docker + Docker Compose |
| 日志 | structlog + JSON 格式 |
| 监控 | Prometheus + 健康检查端点 |
快速开始
前置要求
- Python 3.11+
- [可选] Docker 和 Docker Compose
- [可选] OpenAI API Key(如使用 OpenAI)
本地开发运行
# 1. 克隆项目
git clone https://gitcode.com/SearchB/langgraph_production.git
cd langgraph-enterprise-agent
# 2. 创建虚拟环境
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
# 3. 安装依赖
make dev
# 4. 配置环境变量
cp .env.example .env
# 编辑 .env,填入 OPENAI_API_KEY 等敏感信息
# 5. 初始化数据库(可选,会自动创建)
python scripts/init_db.py
# 6. 启动服务
make run
运行成功后台将会出现如下日志:
make run
ENVIRONMENT=development uvicorn src.main:app --reload --host 0.0.0.0 --port 8000
INFO: Will watch for changes in these directories: ['/Users/thomas.sir/Desktop/langgraph_production']
[transformers] Disabling PyTorch because PyTorch >= 2.4 is required but found 2.2.2
[transformers] PyTorch was not found. Models won't be available and only tokenizers, configuration and file/data utilities can be used.
2026-06-06 00:16:38,089 - root - INFO - Logging configured, level=DEBUG, json_format=False
2026-06-06 00:16:38,093 - src.main - INFO - Application created: LangGraph Agent (Dev)
INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
INFO: Started reloader process [12239] using WatchFiles
[transformers] Disabling PyTorch because PyTorch >= 2.4 is required but found 2.2.2
[transformers] PyTorch was not found. Models won't be available and only tokenizers, configuration and file/data utilities can be used.
2026-06-06 00:16:40,995 - root - INFO - Logging configured, level=DEBUG, json_format=False
2026-06-06 00:16:40,999 - src.main - INFO - Application created: LangGraph Agent (Dev)
INFO: Started server process [12243]
INFO: Waiting for application startup.
2026-06-06 00:16:41,001 - src.main - INFO - Starting up...
2026-06-06 00:16:41,001 - src.main - INFO - Environment: development, Debug: True
2026-06-06 00:16:41,001 - src.memory.checkpointer - INFO - Creating checkpointer: backend=memory
2026-06-06 00:16:41,007 - src.graph.builder - INFO - Graph compiled successfully
2026-06-06 00:16:41,007 - src.main - INFO - Graph pre-compiled successfully
INFO: Application startup complete.
服务启动后,访问 http://localhost:8000/docs 查看自动生成的 API 文档。
在这个接口界面就可以对进口进行测试操作!
使用 Docker Compose 运行(推荐生产)
# 构建并启动完整服务栈(API + PostgreSQL + Redis)
make docker-up
# 查看日志
docker-compose -f docker/docker-compose.yml logs -f
# 停止服务
make docker-down
配置说明
项目使用 YAML 配置文件 + 环境变量 双重配置机制,优先级:环境变量 > YAML > 默认值。
配置文件位置
| 环境 | 配置文件 |
|---|---|
| 开发 | config/development.yaml |
| 生产 | config/production.yaml |
| 默认 | config/default.yaml |
关键配置项
# config/production.yaml 示例
llm:
provider: openai # openai / ollama
openai_model: gpt-4-turbo
temperature: 0.7
vector_store:
store_type: chroma
top_k: 5
checkpoint:
backend: postgres # memory / sqlite / postgres / redis
postgres_dsn: postgresql://user:pass@postgres:5432/langgraph
api:
workers: 4
rate_limit: "100/minute"
环境变量(敏感信息)
创建 .env 文件:
ENVIRONMENT=production
OPENAI_API_KEY=sk-xxx
DB_PASSWORD=secure_password
API 接口文档
1. 聊天接口
非流式发送消息
POST /chat/send
Content-Type: application/json
{
"thread_id": "user_123",
"message": "用 Python 写一个快速排序函数",
"stream": false
}
响应示例:
{
"thread_id": "user_123",
"answer": "```python\ndef quicksort(arr):\n ...\n```",
"sources": ["[1] 算法手册.pdf"],
"role": "coder",
"timestamp": "2025-06-06T10:00:00"
}
流式发送消息(SSE)
POST /chat/stream
Content-Type: application/json
{
"thread_id": "user_123",
"message": "解释一下什么是 RESTful API",
"stream": true
}
响应为 text/event-stream,客户端可逐字接收。
2. 文档上传
POST /documents/upload
Content-Type: multipart/form-data
file: @document.pdf
响应示例:
{
"filename": "document.pdf",
"chunk_count": 42,
"status": "success"
}
3. 健康检查
| 端点 | 用途 |
|---|---|
GET /health |
存活检查,始终返回 200 |
GET /ready |
就绪检查,验证数据库、LLM 等依赖 |
项目结构
.
├── src/
│ ├── api/ # FastAPI 路由和模型
│ │ ├── routes/ # chat, documents, health
│ │ └── schemas.py # Pydantic 模型
│ ├── core/ # 核心基础设施
│ │ ├── config.py # 配置管理
│ │ ├── logging.py # 结构化日志
│ │ ├── exceptions.py # 全局异常处理
│ │ └── middleware.py # 请求ID、CORS、限流
│ ├── graph/ # LangGraph 工作流
│ │ ├── state.py # 状态定义
│ │ ├── nodes/ # 检索、生成、路由节点
│ │ └── builder.py # 图构建器
│ ├── memory/ # 检查点持久化
│ ├── models/ # LLM 工厂
│ ├── tools/ # 工具注册表 + 内置工具
│ └── main.py # 应用入口
├── config/ # YAML 配置文件
├── requirements/ # 依赖分组(base/dev/prod)
├── docker/ # Dockerfile 和 compose
├── scripts/ # 初始化脚本
├── tests/ # 单元测试
├── .env.example
├── Makefile
└── README.md
部署指南
生产环境推荐架构
负载均衡 (Nginx)
│
├─── LangGraph API 实例 1 (Gunicorn + Uvicorn)
├─── LangGraph API 实例 2
└─── ...
│
├─── PostgreSQL (检查点 + 会话状态)
├─── Redis (可选缓存)
└─── Chroma / Qdrant (向量库)
Kubernetes 部署(示例)
apiVersion: apps/v1
kind: Deployment
metadata:
name: langgraph-agent
spec:
replicas: 3
selector:
matchLabels:
app: langgraph-agent
template:
spec:
containers:
- name: api
image: langgraph-agent:latest
env:
- name: ENVIRONMENT
value: "production"
- name: OPENAI_API_KEY
valueFrom:
secretKeyRef:
name: openai-secret
key: api-key
ports:
- containerPort: 8000
livenessProbe:
httpGet:
path: /health
port: 8000
readinessProbe:
httpGet:
path: /ready
port: 8000
监控与告警
- 日志:JSON 格式输出到 stdout,可接入 ELK / Loki
- 指标:Prometheus 端点
/metrics(默认启用) - 告警建议:
- 错误率 > 1% 持续 5 分钟
- P99 延迟 > 5 秒
- 内存使用 > 80%
常见问题
1. 如何添加新的专家角色?
在 src/graph/nodes/router.py 中修改路由提示词,在 ROLE_PROMPTS 中添加新角色及其系统提示。
2. 如何更换向量数据库?
修改 config/production.yaml 中的 vector_store.store_type,并安装对应的客户端库(如 langchain-qdrant)。
3. 如何禁用工具调用?
在 src/models/factory.py 中,创建 LLM 时不传递 bind_tools 参数。
4. 检查点数据库迁移
# 使用 Alembic(需先安装)
alembic init migrations
alembic revision --autogenerate -m "init"
alembic upgrade head
Introduction
可快速搭建生产级智能问答系统,支持多角色路由、RAG知识库问答、多轮对话记忆及工具调用,具备容器化部署、可观测性和水平扩展能力。【此简介由AI生成】
Customize your domain