当前位置：首页 > news >正文

APISIX ＞ ai-proxy 插件 - 指南

news 2026/5/12 15:38:05

文章目录

APISIX ai-proxy 插件介绍
- 核心功能
- 架构组成
- 支持的 AI Provider
- 实现原理
- - 1. 驱动工厂模式
  - 2. 插件生命周期
  - 3. 请求处理流程
  - 4. 响应处理
- 关键特性
- - 认证处理
  - 流式支持
  - 负载均衡 (ai-proxy-multi)
  - 健康检查
  - 日志与指标
- 配置示例
- - 单 Provider (ai-proxy)
  - 多 Provider (ai-proxy-multi)
- 错误处理

APISIX ai-proxy 插件介绍

核心功能

ai-proxy 是 APISIX 的 AI 代理插件，用于将请求转发到各种 AI 大模型服务（如 OpenAI、DeepSeek、Azure OpenAI 等）。

架构组成

apisix/plugins/
├── ai-proxy.lua              # 单 Provider 插件入口
├── ai-proxy-multi.lua        # 多 Provider (负载均衡)
├── ai-proxy/
│   ├── schema.lua            # 配置 Schema
│   └── base.lua              # 共享的请求处理逻辑
└── ai-drivers/├── openai-base.lua       # 基类，所有驱动继承它├── openai.lua            # OpenAI 驱动├── deepseek.lua          # DeepSeek 驱动├── azure-openai.lua      # Azure OpenAI 驱动└── sse.lua               # SSE 流式响应解析

支持的 AI Provider

Provider	驱动文件	默认 Endpoint
OpenAI	`openai.lua`	`https://api.openai.com/v1/chat/completions`
DeepSeek	`deepseek.lua`	`https://api.deepseek.com/chat/completions`
Azure OpenAI	`azure-openai.lua`	自定义 endpoint
AIMLAPI	`aimlapi.lua`	`https://api.aimlapi.com/chat/completions`
OpenAI-Compatible	`openai-compatible.lua`	可配置

实现原理

1. 驱动工厂模式

所有 AI Provider 驱动都继承 openai-base.lua 基类：

-- deepseek.lua 示例
return require("apisix.plugins.ai-drivers.openai-base").new({
host = "api.deepseek.com",
path = "/chat/completions",
port = 443
})

2. 插件生命周期

local _M = {
version = 0.5,
priority = 1040,
name = "ai-proxy",
schema = schema.ai_proxy_schema,
}
function _M.check_schema(conf)   -- 校验配置
function _M.access(conf, ctx)    -- 设置上下文，选择 AI 实例
function _M.before_proxy(conf, ctx) -- 请求转换
function _M.log(conf, ctx)       -- 日志记录

3. 请求处理流程

User Request↓
access() → 设置 ctx.picked_ai_instance↓
before_proxy() → base.before_proxy()↓
校验请求 (JSON content-type, 解析 body)↓
构建带认证的请求头/参数↓
合并 model options 到请求体↓
POST 到 AI provider endpoint↓
读取响应 (SSE 流式 或 JSON)↓
提取 token usage 和响应内容↓
设置 context variables 用于日志↓
返回响应给客户端↓
log() → 记录 summary/payload

4. 响应处理

支持两种响应格式：

SSE 流式 (text/event-stream): 逐行解析 SSE 事件，提取 token usage
JSON: 标准非流式响应，直接解析

-- Token 统计
ctx.ai_token_usage = {
prompt_tokens = data.usage.prompt_tokens or 0,
completion_tokens = data.usage.completion_tokens or 0,
total_tokens = data.usage.total_tokens or 0,
}

关键特性

认证处理

Header 认证: auth.header - 如 {"authorization": "Bearer <token>"}
Query 认证: auth.query - 如 {"apikey": "<token>"}

流式支持

检测请求中的 stream: true
自动添加 stream_options: { include_usage: true } 用于 token 统计
使用 sse.lua 解析 SSE 事件

负载均衡 (ai-proxy-multi)

Roundrobin: 轮询选择
Consistent Hash (chash): 一致性哈希，同一客户端路由到同一 provider
优先级: 优先使用高优先级实例，失败后 fallback

健康检查

集成 APISIX 健康检查机制
支持主动健康检查配置
自动 fallback 到健康实例

日志与指标

Summary 日志: model, duration, token counts
Payload 日志: 完整请求/响应体
Context 变量 (可用于 access log):
- llm_model
- llm_prompt_tokens
- llm_completion_tokens
- llm_time_to_first_token
- llm_response_text

配置示例

单 Provider (ai-proxy)

{
"provider": "openai",
"auth": {
"header": {
"authorization": "Bearer sk-xxx"
}
},
"options": {
"model": "gpt-4",
"temperature": 0.7,
"stream": true
},
"timeout": 30000,
"ssl_verify": true,
"logging": {
"summaries": true,
"payloads": false
}
}

多 Provider (ai-proxy-multi)

{
"instances": [
{
"name": "openai-primary",
"provider": "openai",
"weight": 10,
"priority": 0,
"auth": { "header": { "authorization": "Bearer sk-xxx" } },
"options": { "model": "gpt-4" }
},
{
"name": "deepseek-backup",
"provider": "deepseek",
"weight": 5,
"priority": 1,
"auth": { "header": { "authorization": "Bearer ds-xxx" } },
"options": { "model": "deepseek-chat" }
}
],
"balancer": {
"algorithm": "roundrobin"
},
"fallback_strategy": "instance_health_and_rate_limiting"
}