路由到 LLM 提供商
简介
Envoy AI Gateway 可以将外部 LLM 提供商置于一个兼容 OpenAI 的端点之后。它会使用 BackendSecurityPolicy 注入每个提供商的上游凭证,并按模型名称进行路由,同时在提供商之间进行故障切换。消费者只需调用单一的内部地址,而无需持有提供商密钥,因此网关会成为公共云 LLM 流量的受控出站点,并且会对外部模型应用与自托管模型相同的身份、配额和计量策略。
用例
- 公开托管模型,例如来自 OpenAI、AWS Bedrock、Azure OpenAI、GCP Vertex AI 或 Anthropic 的模型,而无需分发提供商密钥。
- 将不同的模型名称路由到同一端点后面的不同提供商。
- 当主提供商不可用时,切换到备用提供商。
前提条件
-
已安装 Envoy AI Gateway,并且已有
Gateway和AIGatewayRoute。确认相关 CRD 已存在: -
已启用 Envoy Gateway 的
BackendAPI。本指南使用kind: Backend(Envoy Gateway 扩展资源)来声明提供商上游,这要求在 EnvoyGateway 配置中设置extensionApis.enableBackend: true,仅仅存在 CRD 还不够。请先确认,如有缺失则启用:如果未设置,请将其添加到
extensionApis下,并重启控制平面: -
上游提供商凭证(将在下一节创建)已存储在路由命名空间中的
Secret里。 -
提供商端点可从集群出站访问。继续之前请先验证:
请在专用命名空间中创建 Gateway 和 AIGatewayRoute(例如 maas-system),不要放在 Envoy Gateway 控制平面命名空间 envoy-gateway-system 中。放置在控制平面命名空间中的 gateway 可能不会将 AI Gateway 请求处理 filter 和 SecurityPolicy 应用到其 listener,这会悄无声息地破坏路由和策略执行。参见 Envoy AI Gateway。
步骤
存储上游凭证
创建用于保存提供商 API key 的 Secret。对于 type: APIKey,data-map key 必须严格为 apiKey —— BackendSecurityPolicy 会按名称查找该字段,因此使用 --from-literal=key=... 会导致上游调用未通过身份验证,即使策略状态显示为 Accepted:
使用 BackendSecurityPolicy 将提供商凭证注入到目标 backend。type 字段用于选择提供商的认证方案。
type 字段支持 APIKey、AWSCredentials、AzureAPIKey、AzureCredentials、GCPCredentials 和 AnthropicAPIKey。每种类型都需要匹配的凭证块以及匹配的 Secret data key 集合:
当上游认证方案配置错误时,上游通常会返回 401/403。当 Secret 的 key 配置错误时(例如使用 key: 而不是 apiKey:),故障模式更难识别:BackendSecurityPolicy 仍然会报告 Accepted=True,但控制器日志会显示 failed to get backend auth from backend security policy. Skipping this backend. ... error: secret <name> does not contain key apiKey,并将该 backend 从路由中移除,因此对该 backend 的请求会超时,而不是返回一个明确的 401。引入新凭证时,请跟踪控制器日志:
定义提供商 backend
有两个资源协同工作:Backend(Envoy Gateway)告诉数据平面要访问的网络端点,而 AIServiceBackend(Envoy AI Gateway)则告诉 AI filter 要转换成的提供商 schema。
先将上游端点声明为 Backend:
然后注册一个引用该 Backend 的 AIServiceBackend,把提供商添加进去:
schema.name:网关必须使用的上游协议。常见值包括:OpenAI、AWSBedrock、AzureOpenAI、GCPVertexAI、Anthropic。网关会先将传入的兼容 OpenAI 请求转码为该 schema,然后再转发。backendRef:必须指向一个Backend(group 为gateway.envoyproxy.io),而不是Service—— AI filter 依赖Backend来处理面向公共端点的 FQDN 和 TLS。
确认这两个资源都已完成 reconcile:
按模型路由并设置回退
在一条 AIGatewayRoute 规则中引用多个 backend,并设置 priority,这样网关就可以从主提供商故障切换到备用提供商:
matches.headers[x-ai-eg-model]:AI filter 会从请求体中解析model字段,并将其写入该 header 用于路由。因此,请求中的"model":"gpt-4o"就会到达这个匹配条件——调用方无需手动设置 header。priority:Envoy 使用按优先级的故障切换。只要 priority-0 组仍有足够的健康端点,它就会承载所有流量;只有当 priority-0 降级后,priority-1 组才会接收流量——这由 Envoy 的 overprovisioning factor 和 panic threshold 决定,而不是“每个 priority-0 端点都必须下线”这种严格条件。该priority字段会覆盖Backend级别的fallback设置。故障切换是自动的,但需要秒级时间,而不是毫秒级;不要将其用于尾延迟预算。
验证
向网关发送一个兼容 OpenAI 的请求,并确认它已到达提供商、客户端的 Authorization header 已被 BSP 注入的 key 替换,并且返回了包含 token usage 的有效响应:
成功响应(带有 usage 对象的 200 OK)表示上游凭证已正确注入且路由已成功解析。若要检查实际命中的上游请求,可以在 EnvoyProxy 资源上启用 Envoy 的 access log,或者临时将流量路由到一个调试 echo backend;上游请求中的 Authorization header 应当携带来自 openai-key Secret 的值,而不是上面客户端传入的伪造值。
如需演练故障切换,可将主 Backend 指向一个不可达主机(hostname: invalid.example.invalid)几秒钟,以模拟主提供商中断,并观察流量切换到备用提供商;响应体中的 model 字段会反映新的提供商。