CLASSIFIED: OPEN DOSSIER
AI Gateway 文档
2026-01-23 Innora Team
# AI Gateway
AI Gateway 是 InnoFlow 的企业级智能 AI 网关，提供多模型路由、成本优化、熔断保护等能力。
## 核心特性
| 特性 | 说明 |
|------|------|
| **多模型支持** | z.ai GLM-4.7 / 智谱 AI GLM-4 / OpenAI 兼容 |
| **智能路由** | 基于任务复杂度自动选择最优模型 |
| **熔断机制** | 自动故障检测与转移 (CLOSED → OPEN → HALF_OPEN) |
| **成本追踪** | Per-workflow / Per-agent Token 消耗统计 |
| **三层缓存** | L1 内存 + L2 Redis + L3 语义向量 |
| **地域感知** | 中国/国际自动路由策略 |
## 架构设计
```
AI 请求
↓
复杂度评估器 (LOW/MEDIUM/HIGH/CRITICAL)
↓
模型路由器 ────┬─── 中国路由
↓ ↓
国际路由 智谱 AI (合规)
↓
z.ai GLM-4.7 (性价比)
↓
熔断器
↓
成本追踪器
↓
响应 + 成本报告
```
## 成本对比
| 模型 | 输入成本 | 输出成本 | 典型请求成本 | vs GPT-4 节省 |
|------|----------|----------|--------------|--------------|
| z.ai GLM-4.7 | $0.40/M | $1.50/M | $0.02 | **98.7%** |
| 智谱 GLM-4 | ¥0.10/M | ¥0.10/M | $0.006 | **99.6%** |
| OpenAI GPT-4o | $5.00/M | $15.00/M | $0.10 | - |
## 路由策略
| 复杂度 | 中国路由 | 国际路由 | 适用场景 |
|--------|----------|----------|----------|
| LOW | 智谱 GLM-4 | z.ai GLM-4.5-Air | 简单问答、格式化 |
| MEDIUM | 智谱 GLM-4 | z.ai GLM-4.6 | 内容生成、总结 |
| HIGH | z.ai GLM-4.7 | z.ai GLM-4.7 | 复杂推理、分析 |
| CRITICAL | z.ai GLM-4.7 | z.ai GLM-4.7 | 关键决策、代码生成 |
## 快速开始
### 安装
```bash
pnpm add @zhiliu/ai-gateway
```
### 基本使用
```typescript
import { AIGateway } from '@zhiliu/ai-gateway';
const gateway = new AIGateway();
const response = await gateway.executeAgent({
messages: [
{ role: 'system', content: '你是一个专业的助手。' },
{ role: 'user', content: '帮我分析这份报告...' },
],
model: 'glm-4.7',
metadata: {
workflowId: 'workflow-123',
agentId: 'agent-456',
region: 'CN', // 'CN' | 'INTL'
language: 'zh', // 'zh' | 'en'
},
});
console.log(response.content);
console.log('Token 消耗:', response.usage);
console.log('成本:', response.usage.totalCost);
```
### 获取成本报告
```typescript
const costReport = await gateway.getCostReport('workflow-123');
console.log(costReport);
// {
// workflowId: 'workflow-123',
// totalTokens: 15420,
// totalCost: 0.0234,
// breakdown: {
// inputTokens: 12300,
// outputTokens: 3120,
// cachedTokens: 2500
// }
// }
```
## API 端点
| 端点 | 说明 |
|------|------|
| `POST /v1/chat/completions` | 聊天补全 (OpenAI 兼容) |
| `GET /health` | 健康检查 |
| `GET /ready` | 就绪检查 |
| `GET /cost/:workflowId` | 获取成本报告 |
### 健康检查
```bash
curl http://localhost:50051/health
# {"status": "healthy", "providers": {"zai": "up", "zhipu": "up"}}
```
### 聊天补全
```bash
curl -X POST http://localhost:50051/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"model": "glm-4.7",
"messages": [
{"role": "user", "content": "Hello!"}
]
}'
```
## 配置
### 环境变量
```bash
# z.ai (国际)
ZAI_API_KEY=your_api_key
ZAI_BASE_URL=https://api.z.ai/api/paas/v4
ZAI_TIMEOUT=60000
ZAI_MAX_RETRIES=3
# 智谱 AI (中国)
ZHIPU_API_KEY=your_api_key
ZHIPU_BASE_URL=https://api.z.ai/api/paas/v4
ZHIPU_TIMEOUT=60000
ZHIPU_MAX_RETRIES=3
# 缓存配置
REDIS_URL=redis://localhost:6379
CACHE_TTL_SECONDS=3600
```
## 熔断器
AI Gateway 内置熔断器，自动处理服务故障：
| 状态 | 说明 | 行为 |
|------|------|------|
| CLOSED | 正常运行 | 请求正常转发 |
| OPEN | 服务故障 | 直接返回备用响应或切换模型 |
| HALF_OPEN | 探测恢复 | 允许少量请求测试服务状态 |
**熔断配置：**
```typescript
const gateway = new AIGateway({
circuitBreaker: {
failureThreshold: 5, // 5 次失败触发熔断
recoveryTimeout: 30000, // 30 秒后进入 HALF_OPEN
successThreshold: 3, // 3 次成功后恢复
}
});
```
## 缓存策略
三层缓存系统显著降低 Token 消耗：
| 层级 | 存储 | TTL | 用途 |
|------|------|-----|------|
| L1 | 内存 | 5min | 热点请求 |
| L2 | Redis | 1h | 通用缓存 |
| L3 | 向量数据库 | 24h | 语义相似查询 |
## gRPC 接口
AI Gateway 同时提供 gRPC 接口：
```protobuf
service AIGateway {
rpc Chat(ChatRequest) returns (ChatResponse);
rpc GetCost(CostRequest) returns (CostResponse);
rpc HealthCheck(Empty) returns (HealthResponse);
}
```
**gRPC 端点:** `ai-gateway:50051`
---
## 下一步
- [Pieces 插件文档](/docs/innoflow/pieces) - 各插件详细说明
- [API 概览](/docs/innoflow/overview) - API 总览
- [Webhook 配置](/docs/innoflow/webhooks) - Webhook 触发器