envoyproxy/ai-gateway · 上手攻略

仓库：envoyproxy/ai-gateway
链接：https://github.com/envoyproxy/ai-gateway
分类：llm-infra
作者：Tom
更新：2026-07-30

一、是什么

envoyproxy/ai-gateway 是 Envoy 生态下的 AI 网关项目，基于 Envoy Gateway 扩展，专门处理应用客户端到生成式 AI（GenAI）服务的流量。它的本质是一个 Kubernetes 原生的 LLM 流量管理平面，提供路由、认证、限流、弹性Failover等企业级能力。

Envoy 是 CNCF 旗下久经生产验证的代理，Mozilla、Netflix、Airbnb 等公司均在用。ai-gateway 把这套成熟的基础设施能力带入 LLM 领域，而非重新发明轮子。

二、解决什么问题

企业在接入 LLM 时面临几个典型挑战：

多提供商混合使用：OpenAI、Azure OpenAI、Anthropic、AWS Bedrock、Google Gemini……每家 API 格式不同，客户端维护成本高。
企业安全合规：需要统一认证、细粒度授权、API Key 管理、审计日志。
成本与用量控制：缺乏统一限流导致费用不可预期。
自托管模型接入：想把开源模型（vLLM、TGI 等）也纳入统一管理。
可观测性：需要清晰的流量、性能、成本数据。

ai-gateway 通过两层网关架构解决这些问题，在 Envoy 的稳定性和可扩展性基础上，提供云原生 LLM 接入体验。

三、架构：两层网关

Tier-1 Gateway（第一层入口）

集中式入口，负责： - 认证：统一鉴权（API Key、JWT 等） - 顶层路由：按请求特征分发到 Tier-2 或直接到外部 Provider - 全局限流：跨所有后端 Provider 的统一速率控制

Tier-2 Gateway（第二层入口）

自托管模型集群的接入层，提供： - 细粒度访问控制：对特定模型/端点的精细权限管理 - Endpoint Picker：LLM 推理优化（负载均衡/路由策略） - 与 Tier-1 联动：接收来自 Tier-1 的请求，转发到内部模型集群

这种分层设计让外部流量和内部模型服务隔离管理，各司其职。

四、快速安装

前置要求

Kubernetes 集群（1.24+）
Helm 3.x
Envoy Gateway 已安装（或通过 Helm 安装）

安装步骤

# 添加 Helm 仓库
helm repo add envoy-ai-gateway https://envoyproxy.github.io/ai-gateway
helm repo update

# 安装（最简配置）
helm install ai-gateway envoy-ai-gateway/ai-gateway \
  --namespace ai-gateway --create-namespace

# 或使用自定义配置
helm install ai-gateway envoy-ai-gateway/ai-gateway \
  --namespace ai-gateway \
  --set provider.openai.apiKeySecretName=openai-key

安装后确认 Pod 状态：

kubectl get pods -n ai-gateway

五、核心用法

5.1 配置一个 Provider（以 OpenAI 为例）

# ai-gateway-config.yaml
apiVersion: ai-gateway.envoyproxy.io/v1alpha1
kind: Provider
metadata:
  name: openai
  namespace: ai-gateway
spec:
  type: openai
  openai:
    apiKeySecretRef:
      name: openai-api-key
      namespace: ai-gateway

kubectl apply -f ai-gateway-config.yaml

5.2 配置路由规则

apiVersion: gateway.envoyproxy.io/v1alpha2
kind: HTTPRoute
metadata:
  name: llm-route
  namespace: ai-gateway
spec:
  parentRefs:
    - name: ai-gateway
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /v1/chat
      backendRefs:
        - name: ai-gateway
          port: 8000

5.3 认证配置（API Key）

apiVersion: ai-gateway.envoyproxy.io/v1alpha1
kind: AuthPolicy
metadata:
  name: require-api-key
  namespace: ai-gateway
spec:
  rules:
    - match:
        - path: /v1/
      requires:
        apiKey:
          header: X-API-Key
          credentialSecretRef:
            name: api-key

5.4 限流配置

apiVersion: ai-gateway.envoyproxy.io/v1alpha1
kind: RateLimit
metadata:
  name: global-rate-limit
  namespace: ai-gateway
spec:
  global:
    requestsPerUnit: 100
    unit: Minute

5.5 访问 LLM（客户端请求）

配置完成后，应用侧无需感知后端有多复杂，发送请求到网关即可：

# 通过 ai-gateway 访问 OpenAI
curl -X POST https://your-gateway-host/v1/chat/completions \
  -H "Authorization: Bearer $USER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

六、支持的 Provider（截至 2026-07）

OpenAI
Azure OpenAI
Google Gemini
Vertex AI
AWS Bedrock
Mistral
Cohere
Groq
Together AI
DeepInfra
DeepSeek
腾讯 Hunyuan
SambaNova
Grok (xAI)
Tetrate Agent Router Service (TARS)
Anthropic

七、典型适用场景

企业 AI 网关：统一管理所有 LLM 流量，身份认证 + 细粒度授权 + 全局限流，一套系统覆盖全部 Provider。
多云/混合云 LLM 接入：Tier-2 专门接自托管模型，Tier-1 处理外部 Provider，企业内部只需维护一个端点。
安全合规要求严格的环境：必须在自有基础设施内处理所有 AI 请求，通过 Envoy 的成熟安全模型保障。
需要 Failover 能力的场景：某个外部 Provider 不可用时，自动切换到备用方案，对应用透明。

八、坑与注意

学习曲线较陡：Envoy 生态本身有一定门槛（xDS 协议、Gateway API CRD），建议先熟悉 Envoy Gateway 再上手 ai-gateway。
自托管模型需要 Tier-2 配置：如果只接入外部 Provider，Tier-2 可以跳过；如果接 vLLM/TGI 等自托管集群，需要正确配置 Tier-2 的 endpoint picker。
CRD 版本迭代快：文档中的 API 版本（如 v1alpha1）可能在未来升级，注意查阅当前版本对应的 CRD 定义。
Helm Chart 版本与 GitHub Release 同步：建议直接用 GitHub Release 页面下载指定版本，而非 always-latest。
文档质量：作为新兴项目，部分进阶配置（如自定义 Provider 适配器）文档覆盖尚不完整，遇到问题建议直接看 GitHub Issues 或加入 Slack 频道。

九、与同类对比

特性	ai-gateway	Portkey AI	OpenRouter	LiteLLM
部署形态	自托管（Kubernetes）	SaaS / 自托管	SaaS	自托管
依托基础	Envoy Proxy	自建	自建	自建
Tier-2 自托管支持	✅ 两层架构	❌	❌	❌
企业认证/授权	✅	✅	基础	❌
全局限流	✅	✅	基础	需自己实现
CNCF 生态	✅	❌	❌	❌
多租户	✅	✅	✅	需自己实现

十、一句话推荐结论

适合已用或计划用 Kubernetes、需要在企业基础设施内统一管理多路 LLM 流量（外部 Provider + 自托管模型）的团队——Envoy 生态背书，生产级稳定性，ai-gateway 是目前最值得考虑的开源方案。

来源：GitHub README、aigateway.envoyproxy.io/docs、Envoy Slack 社区

注意：Helm 安装步骤和 CRD 示例基于 2026-07 当前文档；API 版本（v1alpha1/v1alpha2）在未来版本中可能变化，请以 GitHub 最新文档为准。