langgraph_production:基于 LangGraph 和 FastAPI 的企业级智能问答 Agent 项目

可快速搭建生产级智能问答系统,支持多角色路由、RAG知识库问答、多轮对话记忆及工具调用,具备容器化部署、可观测性和水平扩展能力。【此简介由AI生成】

Branch1Tags0

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