# LLM API Gateway：基于FastAPI和LangGraph的生产级AI代理微服务

> 一个基于FastAPI和LangGraph构建的生产就绪型LLM API微服务，集成Anthropic Claude API，提供结构化多轮对话能力，内置OpenTelemetry可观测性支持，支持Docker容器化部署。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-05-31T21:45:42.000Z
- 最近活动: 2026-05-31T21:51:59.948Z
- 热度: 163.9
- 关键词: FastAPI, LangGraph, LLM, API网关, Anthropic Claude, OpenTelemetry, Docker, 微服务, AI代理, 可观测性
- 页面链接: https://www.zingnex.cn/forum/thread/llm-api-gateway-fastapilanggraphai
- Canonical: https://www.zingnex.cn/forum/thread/llm-api-gateway-fastapilanggraphai
- Markdown 来源: ingested_event

---

## 原作者与来源

- **原作者/维护者：** vvasylkovskyi
- **来源平台：** GitHub
- **原始标题：** llm-api
- **原始链接：** <https://github.com/vvasylkovskyi/llm-api>
- **发布时间：** 2026年5月

---

## 项目概述

LLM API Gateway是一个基于FastAPI和LangGraph构建的生产就绪型微服务，专为运行由Anthropic Claude API驱动的AI代理和工作流而设计。该项目不仅提供了一个功能完整的对话式AI代理网关，更展示了如何构建和部署具备可观测性的现代化LLM API服务。

项目的核心架构围绕LangGraph状态化代理图展开，通过FastAPI服务器暴露RESTful接口，支持多轮对话、可配置系统提示词和消息历史管理。同时，项目内置了OpenTelemetry链路追踪和指标收集能力，为生产环境运维提供了必要的可观测性保障。

---

## 核心特性

### 1. LangGraph代理引擎

项目采用LangGraph构建状态化代理图，具备以下能力：
- **状态管理** - 维护跨多轮对话的上下文状态
- **可配置系统提示词** - 支持自定义代理行为和角色设定
- **消息历史追踪** - 自动管理对话历史，支持长上下文窗口
- **Claude Haiku集成** - 基于Anthropic的claude-haiku-4-5-20251001模型

### 2. FastAPI服务端

基于FastAPI框架构建的RESTful API服务：
- **自动文档生成** - 访问`/docs`即可获得交互式API文档
- **类型安全** - 利用Python类型提示实现请求/响应验证
- **高性能** - 异步处理，支持高并发请求
- **标准化接口** - 所有路由以`/v1`为前缀

### 3. 可观测性体系

项目内置了完整的可观测性解决方案：
- **链路追踪** - 通过Arize Phoenix实现OpenTelemetry链路追踪，自动埋点LangChain和FastAPI
- **指标收集** - 通过Grafana Alloy以OTLP gRPC协议导出FastAPI指标，每15秒上报一次
- **可视化** - 支持将追踪数据和指标接入主流可观测性平台

### 4. 容器化与CI/CD

项目提供了完整的DevOps支持：
- **Docker容器化** - 包含Dockerfile和docker-compose.yaml，支持一键部署
- **GitHub Actions** - 包含在自托管Mac runner上的自动化构建和发布流程
- **Docker Hub集成** - 支持自动构建并发布到Docker Hub

---

## 技术架构

### 系统架构图

```
┌─────────────┐
│   Client    │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  FastAPI    │
│   Server    │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  LangGraph  │
│   Agent     │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  Anthropic  │
│ Claude API  │
└─────────────┘
```

### 可观测性栈

```
┌─────────────────┐     ┌─────────────────┐
│  Arize Phoenix  │     │ Grafana Alloy   │
│  (链路追踪)      │     │ (指标收集)       │
│  OTLP HTTP      │     │ OTLP gRPC       │
└─────────────────┘     └─────────────────┘
```

---

## 快速开始

### 环境要求

- Python 3.12+
- [uv](https://docs.astral.sh/uv/) 包管理器（推荐）
- Docker（用于容器化部署）
- Anthropic API密钥

### 本地开发

#### 安装依赖

```bash
make install
```

#### 配置环境变量

创建`.env`文件，包含以下变量：

```bash
ANTHROPIC_API_KEY=your-api-key-here

# 可选 - 启用OpenTelemetry埋点
ENABLE_INSTRUMENTATION=false
ALLOY_HOST=localhost
PHOENIX_COLLECTOR_ENDPOINT=http://localhost:4318/v1/traces
PHOENIX_API_KEY=your-phoenix-api-key
SERVICE_NAME=llm-api
```

#### 运行服务

```bash
make run
```

服务将在`http://localhost:10000`启动。

---

## API接口说明

### 健康检查

```
GET /v1/health-check/
```

返回服务健康状态。

### 运行代理

```
POST /v1/agent/run
Content-Type: application/json

{
  "messages": [
    { "role": "user", "content": "Your message here" }
  ]
}
```

**请求示例：**

```bash
curl --location 'http://localhost:10000/v1/agent/run' \
--header 'Content-Type: application/json' \
--data '{
  "messages": [
    { "role": "user", "content": "Hello, how are you?" }
  ]
}'
```

**响应示例：**

```json
{
  "status": "OK",
  "response": "I'm doing well, thank you for asking! How can I assist you today?"
}
```

---

## Docker部署

### 使用Docker Compose

```bash
docker compose up
```

### 手动构建镜像

```bash
docker build -f Dockerfile -t llm-api:local .
```

### 运行容器

```bash
docker run -d --name llm-api \
  -p 10000:10000 \
  -e ANTHROPIC_API_KEY=your-api-key \
  llm-api:local
```

---

## CI/CD工作流

项目包含GitHub Actions工作流，实现以下自动化流程：

1. **Docker镜像构建** - 在自托管Mac runner上构建镜像
2. **发布到Docker Hub** - 自动推送构建好的镜像
3. **Docker Compose部署** - 支持通过docker-compose进行部署

工作流定义位于`.github/workflows/build-on-mac.yml`。

### 所需密钥

在GitHub仓库中设置以下Secrets：

- `DOCKER_USERNAME` - Docker Hub用户名
- `DOCKER_PASSWORD` - Docker Hub密码或访问令牌
- `ANTHROPIC_API_KEY` - Anthropic API密钥

---

## 项目结构

```
llm-api/
├── llm_api/              # 核心Python包
│   ├── agent/            # LangGraph代理实现
│   ├── server/           # FastAPI服务器
│   └── instrumentation/  # 可观测性埋点
├── .github/workflows/    # CI/CD配置
├── Dockerfile            # 容器镜像定义
├── docker-compose.yaml   # 编排配置
├── pyproject.toml        # Python项目配置
├── uv.lock              # 依赖锁定文件
└── Makefile             # 常用命令快捷方式
```

---

## 技术亮点与最佳实践

### 1. 现代化Python工具链

项目采用[uv](https://docs.astral.sh/uv/)作为包管理器，这是Rust编写的超高速Python包管理工具，相比传统pip具有显著的性能优势。

### 2. 异步架构设计

FastAPI原生支持异步处理，结合LangGraph的异步能力，确保服务能够高效处理并发请求。

### 3. 可观测性优先

项目在设计之初就考虑了可观测性需求，而非事后补丁。通过OpenTelemetry标准，实现了与主流可观测性平台的无缝集成。

### 4. 生产就绪配置

从环境变量管理、健康检查端点到Docker容器化，项目包含了生产部署所需的各项配置。

---

## 应用场景

该微服务架构适用于多种AI代理应用场景：

### 1. 对话式AI助手

作为企业内部的智能问答系统后端，支持多轮对话和上下文理解。

### 2. 工作流自动化

集成到业务流程中，通过API调用触发AI代理执行特定任务。

### 3. 多代理编排

作为更大规模多代理系统中的一个节点，通过标准化API与其他服务通信。

### 4. 开发测试环境

为AI应用开发提供标准化的代理服务接口，便于前后端分离开发。

---

## 总结

LLM API Gateway项目展示了一个现代化、生产就绪的AI代理服务应该如何构建。它不仅提供了功能完整的对话式AI能力，更在可观测性、容器化、CI/CD等方面给出了优秀的实践范例。

对于希望将LangGraph和Claude API集成到自己应用中的开发者来说，这是一个极佳的参考实现。项目的代码结构清晰、文档完善、配置灵活，既可以直接部署使用，也可以作为学习现代AI服务架构的教材。