APISIX ＞ AI 网关实现 - 实践

文章目录

• • APISIX的AI 网关实现
  • • AI 插件列表
    • AI 请求处理流程
    • LLM 提供商驱动
    • 核心能力
    • Token 限流策略
    • Prometheus 指标
    • ai-request-rewrite 插件详解
    • 双 LLM 架构
    • ai-proxy 的 Provider 和 Model 选择
    • ai-proxy-multi 多实例负载均衡
  • 配置 LLM 接口实战
  • • 1. 创建路由
    • 2. 客户端调用
    • 3. 关键配置说明
    • 4. Docker 网络配置
    • 5. 常见问题排查

APISIX的AI 网关实现

APISIX 通过 AI 插件生态系统实现了向 AI 网关的转型。

AI 插件列表

插件	优先级	功能
ai-proxy	1040	核心 LLM 代理，支持 OpenAI、DeepSeek、Azure 等
ai-proxy-multi	1041	多 LLM 提供商负载均衡和故障转移
ai-rag	1060	RAG 检索增强生成
ai-prompt-template	1071	预定义提示词模板
ai-prompt-decorator	1072	添加系统提示词（前置/后置）
ai-prompt-guard	1072	提示词安全校验（正则白名单/黑名单）
ai-request-rewrite	1073	请求重写（认证、模型选择）
ai-rate-limiting	-	基于 Token 的限流
ai-aws-content-moderation	-	AWS 内容审核

AI 请求处理流程

客户端请求↓
ai-prompt-template → 应用提示词模板↓
ai-prompt-decorator → 添加系统提示词↓
ai-prompt-guard → 提示词安全校验↓
ai-rag → 检索增强（向量搜索 + 上下文注入）↓
ai-proxy → 转换为 LLM 提供商格式，发送请求↓
LLM 提供商（OpenAI/DeepSeek/Azure...）↓
ai-rate-limiting → Token 限流↓
返回客户端

LLM 提供商驱动

位于 apisix/plugins/ai-drivers/：

• openai.lua - OpenAI
• azure-openai.lua - Azure OpenAI
• deepseek.lua - DeepSeek
• openai-compatible.lua - 通用 OpenAI 兼容 API

核心能力

• 提供商抽象 - 统一接口对接多个 LLM
• 流式响应 - SSE 支持实时 Token 流
• 多提供商故障转移 - 自动切换备用 LLM
• Token 计量 - 跟踪 prompt_tokens、completion_tokens
• 安全防护 - 提示词校验、内容审核

Token 限流策略

ai-rate-limiting 支持三种限流维度：

• total_tokens - 总 Token
• prompt_tokens - 输入 Token
• completion_tokens - 输出 Token

Prometheus 指标

• llm_latency - LLM 响应延迟
• llm_prompt_tokens - 输入 Token 计数
• llm_completion_tokens - 输出 Token 计数
• llm_active_connections - 活跃连接数

ai-request-rewrite 插件详解

该插件用 LLM 来重写客户端请求，将原始请求体发送给 LLM，根据配置的 prompt 进行转换，然后用 LLM 响应替换原始请求。

配置 Schema：

{
prompt = "string",           -- 必填，指导 LLM 如何重写请求的提示词
provider = "openai|deepseek|aimlapi|openai-compatible",  -- 必填
auth = {                     -- 必填，认证信息
header = { ["Authorization"] = "Bearer xxx" },
query = { ["api-key"] = "xxx" }
},
options = { model = "gpt-3.5-turbo" },  -- 模型选项
timeout = 30000,             -- 超时（毫秒）
ssl_verify = true,
override = { endpoint = "https://..." }  -- openai-compatible 必填
}

工作流程：

1. access 阶段获取客户端请求体↓
2. 构造 LLM 请求：{ messages: [{ role: "system", content: conf.prompt },{ role: "user", content: 原始请求体 }]}↓
3. 调用 ai-driver 发送请求到 LLM↓
4. 解析 LLM 响应，提取 choices[0].message.content↓
5. 返回重写后的请求给下游

使用场景：

• 请求格式转换
• 请求增强（补充缺失字段）
• 请求规范化
• 智能路由预处理

双 LLM 架构

ai-request-rewrite 和 ai-proxy 可以配置不同的 LLM：

客户端请求↓
┌─────────────────────────────────────┐
│ ai-request-rewrite                  │
│ 调用 LLM-A（如 GPT-3.5）重写请求     │
└─────────────────────────────────────┘↓
重写后的请求↓
┌─────────────────────────────────────┐
│ ai-proxy                            │
│ 调用 LLM-B（如 GPT-4）处理业务请求   │
└─────────────────────────────────────┘↓
最终响应

配置示例：

plugins:
- name: ai-request-rewrite
config:
provider: openai
options:
model: "gpt-3.5-turbo"  # 便宜模型做重写
prompt: "规范化以下请求格式..."
- name: ai-proxy
config:
provider: openai
options:
model: "gpt-4"  # 强模型做业务处理

分开配置的好处是可以按需选择不同模型，优化成本和性能。

ai-proxy 的 Provider 和 Model 选择

Provider 选择：在路由配置中静态指定

plugins:
ai-proxy:
provider: "openai"  # 必填，枚举值
auth:
header:
Authorization: "Bearer sk-xxx"

支持的 provider：

• openai
• deepseek
• aimlapi
• openai-compatible
• azure-openai

Model 选择：有两个来源，配置优先

-- base.lua:79
local model = ai_instance.options.model or request_body.model

1. 配置优先：conf.options.model - 路由配置中指定的模型
2. 请求兜底：request_body.model - 客户端请求体中的模型

示例：

plugins:
ai-proxy:
provider: openai
options:
model: "gpt-4"  # 强制使用 gpt-4，忽略客户端请求的模型

ai-proxy-multi 多实例负载均衡

支持配置多个 LLM 实例，通过负载均衡和故障转移选择：

plugins:
ai-proxy-multi:
balancer:
algorithm: "roundrobin"  # 或 chash
instances:
- name: "openai-primary"
provider: openai
weight: 80
priority: 0
auth: { header: { Authorization: "Bearer sk-xxx" } }
options: { model: "gpt-4" }
- name: "deepseek-backup"
provider: deepseek
weight: 20
priority: 1
auth: { header: { Authorization: "Bearer xxx" } }
options: { model: "deepseek-chat" }
fallback_strategy: "http_5xx"  # 5xx 时切换到下一个实例

选择逻辑：

• weight - 权重，用于负载均衡
• priority - 优先级，用于故障转移
• fallback_strategy - 触发切换的条件（429、5xx 等）

配置 LLM 接口实战

以宿主机 Ollama（http://127.0.0.1:11434）为例，配置 APISIX 代理 LLM 接口。

1. 创建路由

curl http://127.0.0.1:9180/apisix/admin/routes/1 -X PUT \
-H "X-API-KEY: edd1c9f034335f136f87ad84b625c8f1" \
-d '{
"uri": "/v1/chat/completions",
"plugins": {
"ai-proxy": {
"provider": "openai-compatible",
"auth": {
"header": {}
},
"options": {
"model": "llama3.2"
},
"override": {
"endpoint": "http://host.docker.internal:11434/v1/chat/completions"
},
"timeout": 60000,
"ssl_verify": false
}
}
}'

2. 客户端调用

curl http://127.0.0.1:9080/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "llama3.2",
"max_tokens": 1000,
"messages": [
{"role": "system", "content": "你是一个得力助手。"},
{"role": "user", "content": "你好"}
],
"stream": false
}'

3. 关键配置说明

配置项	值	说明
provider	openai-compatible	Ollama 兼容 OpenAI API
override.endpoint	见下表	必填，LLM 服务地址
auth.header	{}	Ollama 本地无需认证
options.model	llama3.2	指定模型
ssl_verify	false	本地 HTTP 无需 SSL
timeout	60000	本地模型响应慢，建议 60 秒

4. Docker 网络配置

APISIX 在 Docker 中时，访问宿主机服务需要特殊地址：

环境	endpoint
macOS/Windows Docker	http://host.docker.internal:11434/v1/chat/completions
Linux Docker	http://172.17.0.1:11434/v1/chat/completions
本地直接运行	http://127.0.0.1:11434/v1/chat/completions

5. 常见问题排查

Admin API 认证失败：

{"description":"wrong apikey","error_msg":"failed to check token"}

• 检查 conf/config.yaml 中的 admin_key
• 默认 key：edd1c9f034335f136f87ad84b625c8f1

500 Internal Server Error：

# 查看错误日志
tail -100 logs/error.log | grep -i error

常见原因：

• Ollama 未启动
• Docker 网络不通（改用 host.docker.internal）
• ai-proxy 插件未启用

启用插件：检查 conf/config.yaml：

plugins:
- ai-proxy
- ai-prompt-decorator
# ...

重载配置：

apisix reload