a6-plugin-ai-proxy

概览

ai-proxy 插件将 Apache APISIX变为 AI 网关。它以 OpenAI 兼容格式将请求代理到模型服务提供方，并处理身份验证、端点路由和响应流式传输。客户端发送标准聊天补全请求；插件会转换请求并转发给已配置的模型服务提供方。

适用场景

代理聊天完成或嵌入请求到任何支持的 LLM 提供者
在网关集中 API 密钥, 而不是向客户端分发
为 LLM 调用增加可观测性，包括 Token 数和延迟
与 ai-prompt-template、ai-prompt-decorator 或内容审核插件组合，构建完整的 AI 网关处理链

支持的服务提供方

服务提供方	值	默认端点
OpenAI	`openai`	`https://api.openai.com/v1/chat/completions`
DeepSeek	`deepseek`	`https://api.deepseek.com/chat/completions`
Azure OpenAI	`azure-openai`	通过 `override.endpoint` 自定义
Anthropic	`anthropic`	`https://api.anthropic.com/v1/chat/completions`
AIMLAPI	`aimlapi`	`https://api.aimlapi.com/v1/chat/completions`
OpenRouter	`openrouter`	`https://openrouter.ai/api/v1/chat/completions`
Gemini	`gemini`	`https://generativelanguage.googleapis.com/v1beta/openai/chat/completions`
Vertex AI	`vertex-ai`	`https://aiplatform.googleapis.com`
OpenAI 兼容	`openai-compatible`	通过 `override.endpoint` 自定义

插件配置参考

字段	类型	是否必填	默认值	说明
`provider`	string	是	—	9 个受支持提供方之一
`auth`	object	是	—	认证配置（见下文）
`options`	object	否	—	模型和生成参数
`options.model`	string	否	—	模型名称（提供方相关）
`options.temperature`	number	否	—	采样温度
`options.top_p`	number	否	—	核采样
`options.max_tokens`	integer	否	—	生成的最大 Token 数
`options.stream`	boolean	否	`false`	启用 SSE 流式传输
`override`	object	否	—	覆盖默认端点
`override.endpoint`	string	否	—	提供方 API 的完整 URL
`provider_conf`	object	否	—	提供方特定配置（Vertex AI）
`provider_conf.project_id`	string	否	—	GCP project ID（Vertex AI）
`provider_conf.region`	string	否	—	GCP 区域（Vertex AI）
`logging`	object	否	—	日志选项
`logging.summaries`	boolean	否	`false`	记录模型、耗时和 Token
`logging.payloads`	boolean	否	`false`	记录请求/响应体
`timeout`	integer	否	`30000`	请求超时时间（毫秒）
`keepalive`	boolean	否	`true`	保持连接
`keepalive_timeout`	integer	否	`60000`	Keepalive 超时时间（毫秒）
`keepalive_pool`	integer	否	`30`	Keepalive 连接池大小
`ssl_verify`	boolean	否	`true`	校验 SSL 证书

按服务提供方配置身份认证

OpenAI / DeepSeek / Anthropic / AIMLAPI / OpenRouter

{
  "auth": {
    "header": {
      "Authorization": "Bearer sk-your-api-key"
    }
  }
}

Azure OpenAI

{
  "auth": {
    "header": {
      "api-key": "your-azure-key"
    }
  },
  "override": {
    "endpoint": "https://YOUR-RESOURCE.openai.azure.com/openai/deployments/gpt-4/chat/completions?api-version=2024-02-15-preview"
  }
}

Gemini

{
  "auth": {
    "header": {
      "Authorization": "Bearer your-gemini-key"
    }
  }
}

Vertex AI (GCP 服务账户)

{
  "auth": {
    "gcp": {
      "service_account_json": "{ ... }",
      "max_ttl": 3600,
      "expire_early_secs": 60
    }
  },
  "provider_conf": {
    "project_id": "your-project-id",
    "region": "us-central1"
  }
}

service_account_json也可以通过GCP_SERVICE_ACCOUNT 环境变量

自定义OpenAI兼容API

{
  "auth": {
    "header": {
      "Authorization": "Bearer your-token"
    }
  },
  "override": {
    "endpoint": "https://your-custom-llm.com/v1/chat/completions"
  }
}

分步操作：路由到 OpenAI

1. 创建启用 ai-proxy 的路由

a6 route create -f - <<'EOF'
{
  "id": "openai-chat",
  "uri": "/v1/chat/completions",
  "methods": ["POST"],
  "plugins": {
    "ai-proxy": {
      "provider": "openai",
      "auth": {
        "header": {
          "Authorization": "Bearer sk-your-openai-key"
        }
      },
      "options": {
        "model": "gpt-4",
        "temperature": 0.7,
        "max_tokens": 1024
      }
    }
  }
}
EOF

2. 发出请求

curl http://127.0.0.1:9080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "What is 1+1?"}
    ]
  }'

网关添加身份认证信息并将请求转发到 OpenAI，客户端无需接触提供商 API Key。

常见模式

流式响应

{
  "plugins": {
    "ai-proxy": {
      "provider": "openai",
      "auth": {
        "header": {
          "Authorization": "Bearer sk-your-key"
        }
      },
      "options": {
        "model": "gpt-4",
        "stream": true
      }
    }
  }
}

客户端通过 Server-Sent Events（SSE）接收响应。在流式模式下获取 Token 用量时，请在请求正文中设置 stream_options.include_usage: true。

Azure OpenAI

{
  "plugins": {
    "ai-proxy": {
      "provider": "azure-openai",
      "auth": {
        "header": {
          "api-key": "your-azure-key"
        }
      },
      "options": {
        "model": "gpt-4"
      },
      "override": {
        "endpoint": "https://myresource.openai.azure.com/openai/deployments/gpt-4/chat/completions?api-version=2024-02-15-preview"
      },
      "timeout": 60000
    }
  }
}

嵌入终结点

a6 route create -f - <<'EOF'
{
  "id": "embeddings",
  "uri": "/v1/embeddings",
  "methods": ["POST"],
  "plugins": {
    "ai-proxy": {
      "provider": "openai",
      "auth": {
        "header": {
          "Authorization": "Bearer sk-your-key"
        }
      },
      "options": {
        "model": "text-embedding-3-small"
      },
      "override": {
        "endpoint": "https://api.openai.com/v1/embeddings"
      }
    }
  }
}
EOF

启用日志

{
  "plugins": {
    "ai-proxy": {
      "provider": "openai",
      "auth": {
        "header": {
          "Authorization": "Bearer sk-your-key"
        }
      },
      "options": {
        "model": "gpt-4"
      },
      "logging": {
        "summaries": true,
        "payloads": false
      }
    }
  }
}

具有多条路由的模型路由

插件本身不会按模型路由。请创建多条路由，并使用 vars 匹配请求正文中的模型字段：

# Route requests for gpt-4 to OpenAI
a6 route create -f - <<'EOF'
{
  "id": "openai-gpt4",
  "uri": "/v1/chat/completions",
  "methods": ["POST"],
  "vars": [["post_arg.model", "==", "gpt-4"]],
  "plugins": {
    "ai-proxy": {
      "provider": "openai",
      "auth": { "header": { "Authorization": "Bearer sk-openai-key" } },
      "options": { "model": "gpt-4" }
    }
  }
}
EOF

# Route requests for deepseek-chat to DeepSeek
a6 route create -f - <<'EOF'
{
  "id": "deepseek-chat",
  "uri": "/v1/chat/completions",
  "methods": ["POST"],
  "vars": [["post_arg.model", "==", "deepseek-chat"]],
  "plugins": {
    "ai-proxy": {
      "provider": "deepseek",
      "auth": { "header": { "Authorization": "Bearer sk-deepseek-key" } },
      "options": { "model": "deepseek-chat" }
    }
  }
}
EOF

使用ai-proxy-multi进行负载平衡

对于跨提供商的负载平衡、故障转移和基于优先级的路由，改用ai-proxy-multi：

{
  "plugins": {
    "ai-proxy-multi": {
      "balancer": {
        "algorithm": "roundrobin"
      },
      "fallback_strategy": ["rate_limiting", "http_429", "http_5xx"],
      "instances": [
        {
          "name": "openai-primary",
          "provider": "openai",
          "priority": 1,
          "weight": 8,
          "auth": {
            "header": { "Authorization": "Bearer sk-openai-key" }
          },
          "options": { "model": "gpt-4" }
        },
        {
          "name": "deepseek-backup",
          "provider": "deepseek",
          "priority": 0,
          "weight": 2,
          "auth": {
            "header": { "Authorization": "Bearer sk-deepseek-key" }
          },
          "options": { "model": "deepseek-chat" }
        }
      ]
    }
  }
}

访问日志变量

变量	说明
`$request_type`	`traditional_http`、`ai_chat` 或 `ai_stream`
`$llm_time_to_first_token`	首个 Token 返回耗时（毫秒）
`$llm_model`	提供方实际使用的模型
`$request_llm_model`	客户端请求的模型
`$llm_prompt_tokens`	提示词 Token 数量
`$llm_completion_tokens`	补全 Token 数量

配置同步示例

version: "1"
routes:
  - id: openai-chat
    uri: /v1/chat/completions
    methods:
      - POST
    plugins:
      ai-proxy:
        provider: openai
        auth:
          header:
            Authorization: Bearer sk-your-openai-key
        options:
          model: gpt-4
          max_tokens: 1024
          temperature: 0.7
        logging:
          summaries: true

故障排查

症状	原因	解决方法
502 Bad Gateway	端点或提供商配置错误	确认 `provider` 与目标 API 一致；使用 Azure 或自定义端点时检查 `override.endpoint`
上游返回 401	API Key 无效	检查 `auth.header`，并确认密钥对该提供商有效
请求超时	LLM 响应缓慢	增大 `timeout`（默认 30,000 毫秒），或使用流式响应
流式响应中没有 Token 用量	缺少流式用量选项	客户端应发送 `stream_options.include_usage: true`
Azure 返回 404	URL 缺少 API 版本	在 `override.endpoint` 中加入 `?api-version=YYYY-MM-DD-preview`
Vertex AI 认证失败	服务账号 JSON 无效	通过 `auth.gcp.service_account_json` 或 `GCP_SERVICE_ACCOUNT` 环境变量配置

本文根据 api7/a6 仓库中的 a6-plugin-ai-proxy/SKILL.md 生成。可在 AI Agent Skills 页面浏览全部 Skill。

概览​

适用场景​

支持的服务提供方​

插件配置参考​

按服务提供方配置身份认证​

OpenAI / DeepSeek / Anthropic / AIMLAPI / OpenRouter​

Azure OpenAI​

Gemini​

Vertex AI (GCP 服务账户)​

自定义OpenAI兼容API​

分步操作：路由到 OpenAI​

1. 创建启用 ai-proxy 的路由​

2. 发出请求​

常见模式​

流式响应​

Azure OpenAI​

嵌入终结点​

启用日志​

具有多条路由的模型路由​

使用ai-proxy-multi进行负载平衡​

访问日志变量​

配置同步示例​

故障排查​

概览

适用场景

支持的服务提供方

插件配置参考

按服务提供方配置身份认证

OpenAI / DeepSeek / Anthropic / AIMLAPI / OpenRouter

Azure OpenAI

Gemini

Vertex AI (GCP 服务账户)

自定义OpenAI兼容API

分步操作：路由到 OpenAI

1. 创建启用 ai-proxy 的路由

2. 发出请求

常见模式

流式响应

Azure OpenAI

嵌入终结点

启用日志

具有多条路由的模型路由

使用ai-proxy-multi进行负载平衡

访问日志变量

配置同步示例

故障排查