在 GitHub 上能涨到 37K Star 的 AI 网关项目确实不多。早年大家聊 API 网关说的还是 Spring Cloud Gateway、Kong、APISIX 那一套主要管 REST 接口的转发和治理。到了大模型时代手里的资源从接口变成了各种模型服务问题也从“路由转发”变成了“如何统一管理几十个模型入口”。这个项目正是基于这个背景火起来的——它把 OpenAI、Anthropic、国产模型、本地 Ollama 统一收敛到一个 API 入口还内置了限流、密钥托管、缓存、可观测性10 人以下团队可以免费用托管版本开源版走 Apache 2.0 协议。不管你是刚把 AI 接入业务的小团队还是在公司做 AI 中台的工程师都值得把它列入选型清单。这篇文章我就讲讲它到底解决了什么、怎么部署以及我在实际落地时踩过的坑。1. 为什么会有 AI 网关模型多了问题也多了1.1 团队接入多个大模型后最先崩掉的是什么先说一个我朋友公司的例子。他们 12 个人的研发团队做了个企业知识库问答产品一开始只接了一家大模型代码写得很顺手前端直接把 API Key 塞到调用里后端只做一层转发。后来为了降成本和提升效果又接了两家国产模型还试了开源模型私有化部署。问题一下就来了。第一个炸掉的是密钥管理。每个人的本地环境、测试环境、生产环境里散落着各种模型的 Key有人直接推到 Git 仓库里第二天就收到了账单告警别人盗刷了好几百美元。第二个炸掉的是接口格式。OpenAI 的/v1/chat/completions和 Anthropic 的/v1/messages参数结构完全不同国产模型很多又是 OpenAI 兼容但细节差异很大切换模型的时候业务代码跟着改一遍测试用例也得重写。第三个炸掉的是成本核算。月底看到总账单不知道哪个业务线用了多少 token没法分摊成本更没法判断哪些调用是浪费的。这不是个小团队特有的困境。哪怕你是个人开发者只要同时玩过 OpenAI、Claude 和本地模型一定体会过这种碎片化带来的痛苦。AI 网关的出现就是要把这些杂事收敛起来让业务只关心一件事给我一个统一的 API我要发请求拿结果。1.2 AI 网关到底在解决哪几件事你可以把 AI 网关理解成公司里的行政前台统一订餐。以前每个人自己点外卖口味难统一、预算难控制、账单乱糟糟有了行政订餐后大家把需求报到一个入口行政去比价、控预算、做统计月底一拉报表清清楚楚。AI 网关做的事情基本一样协议转换不同厂商的模型 API 格式五花八门网关把它们统一成一种格式通常大家默认 OpenAI 兼容格式业务侧只对接一种协议。密钥管理和安全Key 集中在网关里保管客户端拿到的只是网关下发的临时凭证即使泄露也可以独立吊销不影响上游模型账户。流量治理限流、配额、熔断、重试都能在网关层统一做。比如模型供应商账号 QPS 上限是 100网关可以按业务线拆分额度避免一个业务把整个账号打爆。成本控制按模型、按业务线、按调用者统计 token 消耗做预算预警。月底不再是一笔糊涂账。可观测性所有模型的请求日志、延迟、错误率、token 消耗都集中在一个指标体系里出问题能快速定位是模型问题还是网关问题。高可用一个模型挂了或限流了网关可以自动切换到备用模型业务几乎无感知。生活化一点说没有 AI 网关的时候你的代码直接对上 N 个模型供应商任何一家的 SDK 升级、参数调整、服务波动都会传导到业务层。有了网关上游变化被隔离在一个组件里团队内部只需要维护一套接口协议。1.3 为什么 37K Star社区验证过的“真需求”Star 数当然不是评判项目的唯一标准但一个基础组件能到 37K 级别通常说明它踩中了大量用户的共同痛点。这个项目之所以涨得快我分析有三个原因。时机好。大模型应用从 2024 年开始爆发式增长企业从“用一个模型玩玩”快速过渡到“在生产环境同时接三四个模型”网关类需求集中释放。技术选型对。它底层基于 Envoy 数据面性能不是问题又用 Go 做了控制面插件机制支持 Wasm 扩展既能当 Kubernetes Ingress 用也能当独立网关部署适用面宽。开发策略务实。开源版用 Apache 2.0 协议允许自由使用修改同时提供了云托管版本10 人以下团队免费把上手门槛降得很低。市面上也有其他方案比如自己写一层 Python 代理对接模型服务前期确实简单但模型协议适配、限流、监控这些都要自己造轮子模型从 2 个变 10 个时维护成本直线上升。云厂商托管网关方便可如果你用多家云或者有私有化需求容易绑定生态。相比之下这类开源 AI 网关在灵活性、可控性、社区支持上更均衡适合有基本研发能力的团队直接上手。2. 核心能力拆解网关的关键模块2.1 统一入口与协议转换我最早关注这个项目是被“协议转换”能力吸引的。很多团队用 OpenAI 的 SDK 把代码写完了想换成更便宜或效果更好的其他模型SDK 本身不兼容改代码又伤筋动骨。AI 网关提供了一层转换层比如你业务侧一直用/v1/chat/completions发请求网关收到后转换成目标模型对应的格式再转发给上游。模型切换对业务代码透明你只需要在网关配置里把路由调一下。实际配置时通常基于 CRDKubernetes 自定义资源或者控制台来声明模型供应商。大致结构如下apiVersion: networking.higress.io/v1 kind: ModelRouter metadata: name: openai-router spec: provider: type: openai url: https://api.openai.com/v1 token: ${OPENAI_API_KEY} models: - name: gpt-4o enabled: true这个配置的意思是说网关知道有一个上游叫openai-routertoken 从环境变量读取对外暴露的模型名是gpt-4o。业务侧调用统一网关地址即可不用关心上游细节。如果换成国产模型只需要把 provider 类型和 url 换掉业务代码一行不动。我在测试过程中发现协议转换最怕的是“表面兼容但实际语义有差异”。比如有的模型虽然声称支持 OpenAI 格式但 temperature 的取值范围、response_format 的处理细节可能不同。建议切模型后一定要用同一组测试用例回归一遍别只验证“能通”就上线。2.2 路由成本优先还是可用性优先等模型接入多了路由策略就成了关键环节。你可以给同一个对外模型名配置多个上游按权重分发。比如两家模型供应商的效果相近为了容灾可以把流量按 70:30 切分一家挂了另一家能兜底。还可以做成本优先路由比如某些简单任务走便宜的模型复杂推理走旗舰模型。配置权重路由的常见写法是这样apiVersion: networking.higress.io/v1 kind: ModelRouter metadata: name: hybrid-router spec: routes: - model: gpt-4o providerRef: name: openai-primary weight: 70 - model: gpt-4o providerRef: name: azure-openai-backup weight: 30这笔配置的价值在于运维人员不需要动业务代码只需要调整权重就能控制流量分发。遇到上游全面故障时把某个上游权重改为 0流量就自动全切到另一个。我在生产环境做过一次演练整个过程不到一分钟业务方完全无感。不过路由策略别一上来就配太复杂。建议先做“主备”模式保证稳定性等数据积累多了再逐步引入权重和成本策略。复杂路由意味着更多的排查变量小团队资源有限的时候稳定优先。2.3 限流与配额管理限流这块我要多说几句因为很多人把限流想简单了以为就是“每秒最多放行多少请求”。真实场景里限流维度很多按 API Key 限、按路由限、按全局总配额限还有按 token 数限的。为什么按 token 限也很重要因为有些模型接口昂贵一个 Key 被某个测试脚本疯狂调用账单可能几分钟就爆掉。这个项目支持的限流配置大概长这样apiVersion: networking.higress.io/v1 kind: RateLimiter metadata: name: ai-gateway-limiter spec: apiKeyRules: - match: - service-A limit: qps: 10 window: 60 globalRules: - limit: qps: 100 window: 60apiKeyRules按调用者维度限流globalRules是网关全局兜底。我建议任何团队上线第一件事就把全局限流配好宁可先配松一点之后再收紧。因为很多时候不是别人恶意攻击而是自己同事写的定时任务忘了退循环调用跑了一晚上。我踩过的一个具体坑是只配了 QPS 限流没配并发限流。结果一个耗时特别长的请求占满了连接池后面的请求全部排队超时。后来增加了并发控制才解决。所以限流不要只看 QPS连接数、超时时间都要一起规划。2.4 密钥安全与多租户隔离密钥管理是很多团队选型时的隐藏刚需。没有网关时前端页面要把大模型 Key 发给后端后端再调用模型服务Key 至少在三处地方出现过泄露面非常大。有了网关模型供应商的 Key 只存在于网关配置里客户端访问的是网关生成的独立凭证权限由网关控制即使被泄露也只影响网关到上游的这一条通道可以快速吊销。对于多业务线共用同一个网关的场景多租户隔离就显得重要。A 业务线的 Key 不能查 B 业务线的调用记录B 业务线的配额也不能被 A 业务线挤占。项目一般通过 API Key 和命名空间来做隔离。具体到配置你可以给每个业务线创建独立的凭证并绑定对应的限流策略和路由白名单。这里提醒一点不要在网关层明文保存任何上游密钥建议通过环境变量、K8s Secret 或云厂商的密钥管理服务注入。这个项目官方文档也强调了这个最佳实践我还是亲眼见过有人把 Key 直接写进配置文件里然后提交到仓库安全意识不能省。2.5 可观测性与成本核算最后一个是可观测性。模型类应用的排障链路比普通接口长客户端到网关是一段网关到上游模型又是一段任何一段出问题都可能导致响应异常。这个项目内置了指标暴露能力可以接入 Prometheus Grafana 做可视化监控也能把访问日志打到 Elasticsearch、SLS 这类日志系统。我比较关心的指标是这几个指标作用请求量QPS看整体流量趋势活动上线或功能发布后立刻能看到变化延迟P50/P95/P99判断模型供应商的稳定性如果 P95 持续拉高要考虑切换供应商错误率4xx 和 5xx 分开统计5xx 上升说明上游大概率出问题了Token 消耗按模型、业务线分维度统计成本归因就靠它缓存命中率如果开了语义缓存或结果缓存命中率直接影响成本成本核算这块我特别有感触。以前没有网关月底云账单来了只能看到某个模型 service 花了一万块但不知道是哪个业务花的、哪个功能花的。现在网关里按 API Key 打了维度标签成本报表可以拆到具体业务线财务对账轻松很多。如果团队预算敏感建议每周定时导一次 token 消耗报表设置预算预警通知。3. 从零部署10 人团队免费落地的完整流程3.1 部署前的准备硬件、环境、域名规划先明确一个概念AI 网关本身不做模型推理它只负责转发和治理所以资源消耗比推理服务小得多。我实测下来的参考配置是 2 核 4G 内存就能跑得很稳如果请求量特别大再考虑升配。系统环境建议直接用 Linux Docker生产环境走 Kubernetes 更合适但本文我们先从 Docker Compose 方式讲起适合小团队快速验证。还有一个容易忽略的点域名规划。如果不做外部访问本地 localhost 就够了。但如果要让公司内多个业务线使用建议规划一个独立域名比如ai-gateway.example.com并且准备好 HTTPS 证书。因为模型调用会涉及密钥传输明文 HTTP 在企业内网都不建议用更别说暴露到公网。关于 10 人团队免费这个事我需要说明白开源版本走 Apache 2.0 协议本身没有任何团队人数限制你可以自己搭建、自用甚至商用。官方的云托管版本确实提供了 10 人以下团队免费额度目的是降低小团队的使用门槛。如果你只是想内部自用下载开源版自己部署是最直接的方式如果你想省去运维成本可以先用托管版免费额度体验再决定要不要自建。3.2 快速启动Docker Compose 三分钟跑起来部署这个项目我用的方式是官方提供的 Docker Compose 配置。先把仓库克隆下来或者直接写一个精简的 compose 文件。以下是我整理后的启动方式services: higress: image: higress-registry.cn-hangzhou.cr.aliyuncs.com/public/higress:latest container_name: higress restart: always ports: - 80:8080 - 443:8443 environment: - gateway: istiohigress - default_domainhigress.local networks: - higress networks: higress: driver: bridge这里镜像地址建议以官方 README 为准不同版本可能有变化。启动命令很简单docker compose up -d等容器状态变成 healthy 之后访问http://localhost就能看到网关控制台。我首次启动时等了大概三十秒主要时间花在拉取镜像和初始化配置上。如果你的服务器在国内可能需要配置镜像加速这块属于常规操作不再展开。启动之后第一步要修改默认的管理员密码然后绑定你的域名和证书。如果只是本地测试可以跳过证书步骤直接用 IP 或者改 hosts 访问。3.3 接入第一个模型OpenAI 兼容接口网关起来了接下来要做的第一件事就是接一个真实模型。这里以 OpenAI 兼容接口为例因为国内大部分模型的 API 都声明兼容 OpenAI 格式接一个之后其他模型就是照葫芦画瓢。在控制台里创建一个模型供应商填写信息大致如下供应商名称openai或你的自定义名接口地址https://api.openai.com/v1API Key你的真实 Key从环境变量或者密钥管理服务读取模型列表gpt-4o、gpt-4o-mini等需要暴露给业务方的模型如果是用 CRD 配置参照前面的ModelRouter示例即可。配置完成后你会得到一个新的统一访问地址类似http://[网关地址]/v1/chat/completions业务方调用这个地址时不再需要拿 OpenAI 的原始 Key而是用网关生成的 API Key 做身份认证。网关收到请求后自行完成协议转换和上游鉴权。客户端代码改动极小OpenAI SDK 的base_url指到网关地址即可。3.4 配置路由与限流模型接入成功后第二步是配置路由和限流。路由配置我建议按照业务场景来设计而不是照抄别人的模板。你可以先问自己三个问题业务方会通过哪几个模型名来调用每个模型名背后是单一供应商还是多个备用供应商不同业务线之间是否需要独立配额这三个问题想清楚后路由配置就顺了。举个例子我们内部有两个业务线线上问答和数据分析。线上问答要求响应快主要走gpt-4o-mini并配置了国产模型做备份数据分析效果要求高走gpt-4o但每天有配额上限。这些需求落到配置里就是两套ModelRouter加对应的RateLimiter。限流配置刚上线时建议“先宽后严”。比如先给每个业务线 QPS 50 的额度观察几天如果没有异常再逐步下调到合理水位。如果一上来就设得很小很容易出现业务方正常请求被误伤的情况排查起来也是心情复杂。等到运行稳定了再结合监控数据做精细调整。还有一个很重要的点重试策略。模型服务经常会有瞬时错误网关层配置重试能有效提升成功率。但重试要设置上限我一般配置最多 2 次重试并且开启“只在连接错误或者 5xx 时重试”避免重复扣费。3.5 验证可用性用一个测试脚本压一下配置完成后我习惯用一个小脚本验证整体链路是否正常。先做基础调用确认能拿到模型返回curl http://localhost/v1/chat/completions \ -H Authorization: Bearer ${GATEWAY_API_KEY} \ -H Content-Type: application/json \ -d { model: gpt-4o-mini, messages: [{role: user, content: 你好请用一句话介绍你自己}] }如果返回正常的 JSON 结果说明网关、路由、密钥链路都通了。接着做一个简单的并发测试验证限流是否生效import threading import time import requests url http://localhost/v1/chat/completions headers { Authorization: Bearer test-key, Content-Type: application/json, } payload { model: gpt-4o-mini, messages: [{role: user, content: ping}], } def call(): try: r requests.post(url, headersheaders, jsonpayload, timeout10) print(r.status_code) except Exception as e: print(error:, e) threads [threading.Thread(targetcall) for _ in range(50)] start time.time() for t in threads: t.start() for t in threads: t.join() print(elapsed:, time.time() - start)如果限流设置为 QPS 1050 个并发请求里应该只有前面 10 个左右返回 200其余返回 429。看到 429 反而证明限流规则生效了。这一步验证建议在测试环境做不要一上来就在生产环境压测。4. 常见问题与排查经验4.1 密钥没生效 / 返回 401这类问题我在测试时遇到最多。401 表示认证失败原因通常有三个网关 API Key 配错了客户端请求头没正确携带 AuthorizationKey 权限范围没有覆盖目标路由。排查思路很简单先在网关管理界面查看该 Key 的权限列表确认目标模型路由在范围内。接着用浏览器开发者工具或者 Postman 检查请求头我遇到过一次前端代码把 Bearer 拼错成 “Beraer”这类低级错误最难发现。最后可以看网关 access log里面会记录完整的认证链路状态能直接看到是“key not found”还是“permission denied”。如果配置了环境变量注入上游密钥切记修改密钥后要重启或触发配置热更新。我之前用了一个在线配置工具以为保存就生效结果上游一直报 401排查半天发现是配置没推送。容器部署的场景检查配置同步状态比改代码更优先。4.2 请求超时、模型返回 429429 是限流触发的标准状态码但要区分是哪个环节的限流。网关上配了限流上游模型服务也可能限流。定位方法很简单看网关日志里记录的 upstream response code。如果是上游返回 429那是模型供应商的配额问题需要检查上游账户额度而不是调大网关限流。另一个容易忽略的情况是慢请求占用连接。模型接口本身响应就比普通接口慢动辄几秒甚至几十秒如果网关的 upstream timeout 设置太短容易被误判为超时。这类网关一般支持配置超时时间建议根据模型实际响应分布来设置比如 P99 是 5 秒超时设置成 15 秒比较稳妥。4.3 想接本地模型Ollama需要注意什么本地模型接入网关也是常见需求。很多工具可以用 Ollama 跑开源模型。Ollama 默认提供了 OpenAI 兼容接口/v1/chat/completions所以网关侧可以直接按 OpenAI 兼容类型配置。有一点要注意本地模型没有云端模型那样的多租户配额如果你同时跑在单张显卡上多个请求并发会让推理队列瞬间拉长延迟急剧增加。我的建议是如果本地模型要同时服务多个业务线网关层限流调低一些比如 QPS 5避免推理服务被并发打满。另外本地模型的 token 统计也要关注部分开源模型的 tokenizer 和云端模型不同成本统计只能作为参考不能完全等价。4.4 日志与监控看不到调用链网关部署好后默认不一定把所有日志指标都打开了。某些项目需要显式开启 access log 和指标暴露端口。建议在部署阶段就把日志接入链路梳理清楚不要等出问题再补。我习惯的标准配置是access log 输出到标准输出按天切割归档Prometheus 指标端口单独暴露配合 Grafana 模板做面板。还有一个坑是 Kubernetes 环境下日志采集器如果只收集容器 stdout网关的访问日志可能被丢弃。建议在日志采集配置里把网关日志目录明确加进去。另外请求 ID 的透传很重要网关会生成 request id但业务方如果不在请求头里带自己的 trace id两端日志很难关联。建议业务侧在请求头加X-Trace-Id网关透传这样链路追踪才完整。4.5 常见问题速查表现象可能原因解决思路返回 401API Key 错误、权限不足、请求头拼写错误检查网关 Key 状态、权限范围、请求头格式返回 429网关限流或上游限流查看日志中的 upstream response code区分限流层级偶尔超时上游模型慢、超时时间设置短拉长超时时间配置重试观察上游延迟指标全部超时上游密钥失效、网络不通、本地推理卡死先测试上游直连再排查网关到上游链路token 统计与账单对不上Tokenizer 计算方式差异、缓存命中确认统计逻辑结合网关缓存命中率分析切换模型后效果变差协议转换中的参数语义差异跑完整回归集重点验证 temperature、top_p、格式参数最后再分享一个实际使用中的小技巧刚开始接这个网关的时候我犯过一个“过度设计”的错。为了展示团队能力第一版就配了多路由、多租户、复杂限流、全量监控告警结果上线后一半精力都在处理配置问题。后来把配置简化为“全局限流 主备路由 基础日志”系统反而稳定了团队也能专注在业务上。另外一个建议是如果你是小团队可以先试用云托管版的免费额度用真实业务跑两周确认网关的行为符合预期后再决定是否自建。自建意味着你要自己维护升级、监控、备份这些隐形成本往往被低估。跑通一个 Demo 不叫落地能稳定运行一个月才叫落地。AI 网关的选型没有什么压倒性的标准答案关键是匹配你团队当前的规模和真实痛点。如果你现在只有一个模型业务量也不大不需要网关如果同时接了三四个模型、有多个业务方接入、成本开始失控那这个 37K Star 的项目值得花一个下午好好玩一下。 AI网关实战：统一多模型接入、限流与成本控制全攻略
在 GitHub 上能涨到 37K Star 的 AI 网关项目确实不多。早年大家聊 API 网关说的还是 Spring Cloud Gateway、Kong、APISIX 那一套主要管 REST 接口的转发和治理。到了大模型时代手里的资源从接口变成了各种模型服务问题也从“路由转发”变成了“如何统一管理几十个模型入口”。这个项目正是基于这个背景火起来的——它把 OpenAI、Anthropic、国产模型、本地 Ollama 统一收敛到一个 API 入口还内置了限流、密钥托管、缓存、可观测性10 人以下团队可以免费用托管版本开源版走 Apache 2.0 协议。不管你是刚把 AI 接入业务的小团队还是在公司做 AI 中台的工程师都值得把它列入选型清单。这篇文章我就讲讲它到底解决了什么、怎么部署以及我在实际落地时踩过的坑。1. 为什么会有 AI 网关模型多了问题也多了1.1 团队接入多个大模型后最先崩掉的是什么先说一个我朋友公司的例子。他们 12 个人的研发团队做了个企业知识库问答产品一开始只接了一家大模型代码写得很顺手前端直接把 API Key 塞到调用里后端只做一层转发。后来为了降成本和提升效果又接了两家国产模型还试了开源模型私有化部署。问题一下就来了。第一个炸掉的是密钥管理。每个人的本地环境、测试环境、生产环境里散落着各种模型的 Key有人直接推到 Git 仓库里第二天就收到了账单告警别人盗刷了好几百美元。第二个炸掉的是接口格式。OpenAI 的/v1/chat/completions和 Anthropic 的/v1/messages参数结构完全不同国产模型很多又是 OpenAI 兼容但细节差异很大切换模型的时候业务代码跟着改一遍测试用例也得重写。第三个炸掉的是成本核算。月底看到总账单不知道哪个业务线用了多少 token没法分摊成本更没法判断哪些调用是浪费的。这不是个小团队特有的困境。哪怕你是个人开发者只要同时玩过 OpenAI、Claude 和本地模型一定体会过这种碎片化带来的痛苦。AI 网关的出现就是要把这些杂事收敛起来让业务只关心一件事给我一个统一的 API我要发请求拿结果。1.2 AI 网关到底在解决哪几件事你可以把 AI 网关理解成公司里的行政前台统一订餐。以前每个人自己点外卖口味难统一、预算难控制、账单乱糟糟有了行政订餐后大家把需求报到一个入口行政去比价、控预算、做统计月底一拉报表清清楚楚。AI 网关做的事情基本一样协议转换不同厂商的模型 API 格式五花八门网关把它们统一成一种格式通常大家默认 OpenAI 兼容格式业务侧只对接一种协议。密钥管理和安全Key 集中在网关里保管客户端拿到的只是网关下发的临时凭证即使泄露也可以独立吊销不影响上游模型账户。流量治理限流、配额、熔断、重试都能在网关层统一做。比如模型供应商账号 QPS 上限是 100网关可以按业务线拆分额度避免一个业务把整个账号打爆。成本控制按模型、按业务线、按调用者统计 token 消耗做预算预警。月底不再是一笔糊涂账。可观测性所有模型的请求日志、延迟、错误率、token 消耗都集中在一个指标体系里出问题能快速定位是模型问题还是网关问题。高可用一个模型挂了或限流了网关可以自动切换到备用模型业务几乎无感知。生活化一点说没有 AI 网关的时候你的代码直接对上 N 个模型供应商任何一家的 SDK 升级、参数调整、服务波动都会传导到业务层。有了网关上游变化被隔离在一个组件里团队内部只需要维护一套接口协议。1.3 为什么 37K Star社区验证过的“真需求”Star 数当然不是评判项目的唯一标准但一个基础组件能到 37K 级别通常说明它踩中了大量用户的共同痛点。这个项目之所以涨得快我分析有三个原因。时机好。大模型应用从 2024 年开始爆发式增长企业从“用一个模型玩玩”快速过渡到“在生产环境同时接三四个模型”网关类需求集中释放。技术选型对。它底层基于 Envoy 数据面性能不是问题又用 Go 做了控制面插件机制支持 Wasm 扩展既能当 Kubernetes Ingress 用也能当独立网关部署适用面宽。开发策略务实。开源版用 Apache 2.0 协议允许自由使用修改同时提供了云托管版本10 人以下团队免费把上手门槛降得很低。市面上也有其他方案比如自己写一层 Python 代理对接模型服务前期确实简单但模型协议适配、限流、监控这些都要自己造轮子模型从 2 个变 10 个时维护成本直线上升。云厂商托管网关方便可如果你用多家云或者有私有化需求容易绑定生态。相比之下这类开源 AI 网关在灵活性、可控性、社区支持上更均衡适合有基本研发能力的团队直接上手。2. 核心能力拆解网关的关键模块2.1 统一入口与协议转换我最早关注这个项目是被“协议转换”能力吸引的。很多团队用 OpenAI 的 SDK 把代码写完了想换成更便宜或效果更好的其他模型SDK 本身不兼容改代码又伤筋动骨。AI 网关提供了一层转换层比如你业务侧一直用/v1/chat/completions发请求网关收到后转换成目标模型对应的格式再转发给上游。模型切换对业务代码透明你只需要在网关配置里把路由调一下。实际配置时通常基于 CRDKubernetes 自定义资源或者控制台来声明模型供应商。大致结构如下apiVersion: networking.higress.io/v1 kind: ModelRouter metadata: name: openai-router spec: provider: type: openai url: https://api.openai.com/v1 token: ${OPENAI_API_KEY} models: - name: gpt-4o enabled: true这个配置的意思是说网关知道有一个上游叫openai-routertoken 从环境变量读取对外暴露的模型名是gpt-4o。业务侧调用统一网关地址即可不用关心上游细节。如果换成国产模型只需要把 provider 类型和 url 换掉业务代码一行不动。我在测试过程中发现协议转换最怕的是“表面兼容但实际语义有差异”。比如有的模型虽然声称支持 OpenAI 格式但 temperature 的取值范围、response_format 的处理细节可能不同。建议切模型后一定要用同一组测试用例回归一遍别只验证“能通”就上线。2.2 路由成本优先还是可用性优先等模型接入多了路由策略就成了关键环节。你可以给同一个对外模型名配置多个上游按权重分发。比如两家模型供应商的效果相近为了容灾可以把流量按 70:30 切分一家挂了另一家能兜底。还可以做成本优先路由比如某些简单任务走便宜的模型复杂推理走旗舰模型。配置权重路由的常见写法是这样apiVersion: networking.higress.io/v1 kind: ModelRouter metadata: name: hybrid-router spec: routes: - model: gpt-4o providerRef: name: openai-primary weight: 70 - model: gpt-4o providerRef: name: azure-openai-backup weight: 30这笔配置的价值在于运维人员不需要动业务代码只需要调整权重就能控制流量分发。遇到上游全面故障时把某个上游权重改为 0流量就自动全切到另一个。我在生产环境做过一次演练整个过程不到一分钟业务方完全无感。不过路由策略别一上来就配太复杂。建议先做“主备”模式保证稳定性等数据积累多了再逐步引入权重和成本策略。复杂路由意味着更多的排查变量小团队资源有限的时候稳定优先。2.3 限流与配额管理限流这块我要多说几句因为很多人把限流想简单了以为就是“每秒最多放行多少请求”。真实场景里限流维度很多按 API Key 限、按路由限、按全局总配额限还有按 token 数限的。为什么按 token 限也很重要因为有些模型接口昂贵一个 Key 被某个测试脚本疯狂调用账单可能几分钟就爆掉。这个项目支持的限流配置大概长这样apiVersion: networking.higress.io/v1 kind: RateLimiter metadata: name: ai-gateway-limiter spec: apiKeyRules: - match: - service-A limit: qps: 10 window: 60 globalRules: - limit: qps: 100 window: 60apiKeyRules按调用者维度限流globalRules是网关全局兜底。我建议任何团队上线第一件事就把全局限流配好宁可先配松一点之后再收紧。因为很多时候不是别人恶意攻击而是自己同事写的定时任务忘了退循环调用跑了一晚上。我踩过的一个具体坑是只配了 QPS 限流没配并发限流。结果一个耗时特别长的请求占满了连接池后面的请求全部排队超时。后来增加了并发控制才解决。所以限流不要只看 QPS连接数、超时时间都要一起规划。2.4 密钥安全与多租户隔离密钥管理是很多团队选型时的隐藏刚需。没有网关时前端页面要把大模型 Key 发给后端后端再调用模型服务Key 至少在三处地方出现过泄露面非常大。有了网关模型供应商的 Key 只存在于网关配置里客户端访问的是网关生成的独立凭证权限由网关控制即使被泄露也只影响网关到上游的这一条通道可以快速吊销。对于多业务线共用同一个网关的场景多租户隔离就显得重要。A 业务线的 Key 不能查 B 业务线的调用记录B 业务线的配额也不能被 A 业务线挤占。项目一般通过 API Key 和命名空间来做隔离。具体到配置你可以给每个业务线创建独立的凭证并绑定对应的限流策略和路由白名单。这里提醒一点不要在网关层明文保存任何上游密钥建议通过环境变量、K8s Secret 或云厂商的密钥管理服务注入。这个项目官方文档也强调了这个最佳实践我还是亲眼见过有人把 Key 直接写进配置文件里然后提交到仓库安全意识不能省。2.5 可观测性与成本核算最后一个是可观测性。模型类应用的排障链路比普通接口长客户端到网关是一段网关到上游模型又是一段任何一段出问题都可能导致响应异常。这个项目内置了指标暴露能力可以接入 Prometheus Grafana 做可视化监控也能把访问日志打到 Elasticsearch、SLS 这类日志系统。我比较关心的指标是这几个指标作用请求量QPS看整体流量趋势活动上线或功能发布后立刻能看到变化延迟P50/P95/P99判断模型供应商的稳定性如果 P95 持续拉高要考虑切换供应商错误率4xx 和 5xx 分开统计5xx 上升说明上游大概率出问题了Token 消耗按模型、业务线分维度统计成本归因就靠它缓存命中率如果开了语义缓存或结果缓存命中率直接影响成本成本核算这块我特别有感触。以前没有网关月底云账单来了只能看到某个模型 service 花了一万块但不知道是哪个业务花的、哪个功能花的。现在网关里按 API Key 打了维度标签成本报表可以拆到具体业务线财务对账轻松很多。如果团队预算敏感建议每周定时导一次 token 消耗报表设置预算预警通知。3. 从零部署10 人团队免费落地的完整流程3.1 部署前的准备硬件、环境、域名规划先明确一个概念AI 网关本身不做模型推理它只负责转发和治理所以资源消耗比推理服务小得多。我实测下来的参考配置是 2 核 4G 内存就能跑得很稳如果请求量特别大再考虑升配。系统环境建议直接用 Linux Docker生产环境走 Kubernetes 更合适但本文我们先从 Docker Compose 方式讲起适合小团队快速验证。还有一个容易忽略的点域名规划。如果不做外部访问本地 localhost 就够了。但如果要让公司内多个业务线使用建议规划一个独立域名比如ai-gateway.example.com并且准备好 HTTPS 证书。因为模型调用会涉及密钥传输明文 HTTP 在企业内网都不建议用更别说暴露到公网。关于 10 人团队免费这个事我需要说明白开源版本走 Apache 2.0 协议本身没有任何团队人数限制你可以自己搭建、自用甚至商用。官方的云托管版本确实提供了 10 人以下团队免费额度目的是降低小团队的使用门槛。如果你只是想内部自用下载开源版自己部署是最直接的方式如果你想省去运维成本可以先用托管版免费额度体验再决定要不要自建。3.2 快速启动Docker Compose 三分钟跑起来部署这个项目我用的方式是官方提供的 Docker Compose 配置。先把仓库克隆下来或者直接写一个精简的 compose 文件。以下是我整理后的启动方式services: higress: image: higress-registry.cn-hangzhou.cr.aliyuncs.com/public/higress:latest container_name: higress restart: always ports: - 80:8080 - 443:8443 environment: - gateway: istiohigress - default_domainhigress.local networks: - higress networks: higress: driver: bridge这里镜像地址建议以官方 README 为准不同版本可能有变化。启动命令很简单docker compose up -d等容器状态变成 healthy 之后访问http://localhost就能看到网关控制台。我首次启动时等了大概三十秒主要时间花在拉取镜像和初始化配置上。如果你的服务器在国内可能需要配置镜像加速这块属于常规操作不再展开。启动之后第一步要修改默认的管理员密码然后绑定你的域名和证书。如果只是本地测试可以跳过证书步骤直接用 IP 或者改 hosts 访问。3.3 接入第一个模型OpenAI 兼容接口网关起来了接下来要做的第一件事就是接一个真实模型。这里以 OpenAI 兼容接口为例因为国内大部分模型的 API 都声明兼容 OpenAI 格式接一个之后其他模型就是照葫芦画瓢。在控制台里创建一个模型供应商填写信息大致如下供应商名称openai或你的自定义名接口地址https://api.openai.com/v1API Key你的真实 Key从环境变量或者密钥管理服务读取模型列表gpt-4o、gpt-4o-mini等需要暴露给业务方的模型如果是用 CRD 配置参照前面的ModelRouter示例即可。配置完成后你会得到一个新的统一访问地址类似http://[网关地址]/v1/chat/completions业务方调用这个地址时不再需要拿 OpenAI 的原始 Key而是用网关生成的 API Key 做身份认证。网关收到请求后自行完成协议转换和上游鉴权。客户端代码改动极小OpenAI SDK 的base_url指到网关地址即可。3.4 配置路由与限流模型接入成功后第二步是配置路由和限流。路由配置我建议按照业务场景来设计而不是照抄别人的模板。你可以先问自己三个问题业务方会通过哪几个模型名来调用每个模型名背后是单一供应商还是多个备用供应商不同业务线之间是否需要独立配额这三个问题想清楚后路由配置就顺了。举个例子我们内部有两个业务线线上问答和数据分析。线上问答要求响应快主要走gpt-4o-mini并配置了国产模型做备份数据分析效果要求高走gpt-4o但每天有配额上限。这些需求落到配置里就是两套ModelRouter加对应的RateLimiter。限流配置刚上线时建议“先宽后严”。比如先给每个业务线 QPS 50 的额度观察几天如果没有异常再逐步下调到合理水位。如果一上来就设得很小很容易出现业务方正常请求被误伤的情况排查起来也是心情复杂。等到运行稳定了再结合监控数据做精细调整。还有一个很重要的点重试策略。模型服务经常会有瞬时错误网关层配置重试能有效提升成功率。但重试要设置上限我一般配置最多 2 次重试并且开启“只在连接错误或者 5xx 时重试”避免重复扣费。3.5 验证可用性用一个测试脚本压一下配置完成后我习惯用一个小脚本验证整体链路是否正常。先做基础调用确认能拿到模型返回curl http://localhost/v1/chat/completions \ -H Authorization: Bearer ${GATEWAY_API_KEY} \ -H Content-Type: application/json \ -d { model: gpt-4o-mini, messages: [{role: user, content: 你好请用一句话介绍你自己}] }如果返回正常的 JSON 结果说明网关、路由、密钥链路都通了。接着做一个简单的并发测试验证限流是否生效import threading import time import requests url http://localhost/v1/chat/completions headers { Authorization: Bearer test-key, Content-Type: application/json, } payload { model: gpt-4o-mini, messages: [{role: user, content: ping}], } def call(): try: r requests.post(url, headersheaders, jsonpayload, timeout10) print(r.status_code) except Exception as e: print(error:, e) threads [threading.Thread(targetcall) for _ in range(50)] start time.time() for t in threads: t.start() for t in threads: t.join() print(elapsed:, time.time() - start)如果限流设置为 QPS 1050 个并发请求里应该只有前面 10 个左右返回 200其余返回 429。看到 429 反而证明限流规则生效了。这一步验证建议在测试环境做不要一上来就在生产环境压测。4. 常见问题与排查经验4.1 密钥没生效 / 返回 401这类问题我在测试时遇到最多。401 表示认证失败原因通常有三个网关 API Key 配错了客户端请求头没正确携带 AuthorizationKey 权限范围没有覆盖目标路由。排查思路很简单先在网关管理界面查看该 Key 的权限列表确认目标模型路由在范围内。接着用浏览器开发者工具或者 Postman 检查请求头我遇到过一次前端代码把 Bearer 拼错成 “Beraer”这类低级错误最难发现。最后可以看网关 access log里面会记录完整的认证链路状态能直接看到是“key not found”还是“permission denied”。如果配置了环境变量注入上游密钥切记修改密钥后要重启或触发配置热更新。我之前用了一个在线配置工具以为保存就生效结果上游一直报 401排查半天发现是配置没推送。容器部署的场景检查配置同步状态比改代码更优先。4.2 请求超时、模型返回 429429 是限流触发的标准状态码但要区分是哪个环节的限流。网关上配了限流上游模型服务也可能限流。定位方法很简单看网关日志里记录的 upstream response code。如果是上游返回 429那是模型供应商的配额问题需要检查上游账户额度而不是调大网关限流。另一个容易忽略的情况是慢请求占用连接。模型接口本身响应就比普通接口慢动辄几秒甚至几十秒如果网关的 upstream timeout 设置太短容易被误判为超时。这类网关一般支持配置超时时间建议根据模型实际响应分布来设置比如 P99 是 5 秒超时设置成 15 秒比较稳妥。4.3 想接本地模型Ollama需要注意什么本地模型接入网关也是常见需求。很多工具可以用 Ollama 跑开源模型。Ollama 默认提供了 OpenAI 兼容接口/v1/chat/completions所以网关侧可以直接按 OpenAI 兼容类型配置。有一点要注意本地模型没有云端模型那样的多租户配额如果你同时跑在单张显卡上多个请求并发会让推理队列瞬间拉长延迟急剧增加。我的建议是如果本地模型要同时服务多个业务线网关层限流调低一些比如 QPS 5避免推理服务被并发打满。另外本地模型的 token 统计也要关注部分开源模型的 tokenizer 和云端模型不同成本统计只能作为参考不能完全等价。4.4 日志与监控看不到调用链网关部署好后默认不一定把所有日志指标都打开了。某些项目需要显式开启 access log 和指标暴露端口。建议在部署阶段就把日志接入链路梳理清楚不要等出问题再补。我习惯的标准配置是access log 输出到标准输出按天切割归档Prometheus 指标端口单独暴露配合 Grafana 模板做面板。还有一个坑是 Kubernetes 环境下日志采集器如果只收集容器 stdout网关的访问日志可能被丢弃。建议在日志采集配置里把网关日志目录明确加进去。另外请求 ID 的透传很重要网关会生成 request id但业务方如果不在请求头里带自己的 trace id两端日志很难关联。建议业务侧在请求头加X-Trace-Id网关透传这样链路追踪才完整。4.5 常见问题速查表现象可能原因解决思路返回 401API Key 错误、权限不足、请求头拼写错误检查网关 Key 状态、权限范围、请求头格式返回 429网关限流或上游限流查看日志中的 upstream response code区分限流层级偶尔超时上游模型慢、超时时间设置短拉长超时时间配置重试观察上游延迟指标全部超时上游密钥失效、网络不通、本地推理卡死先测试上游直连再排查网关到上游链路token 统计与账单对不上Tokenizer 计算方式差异、缓存命中确认统计逻辑结合网关缓存命中率分析切换模型后效果变差协议转换中的参数语义差异跑完整回归集重点验证 temperature、top_p、格式参数最后再分享一个实际使用中的小技巧刚开始接这个网关的时候我犯过一个“过度设计”的错。为了展示团队能力第一版就配了多路由、多租户、复杂限流、全量监控告警结果上线后一半精力都在处理配置问题。后来把配置简化为“全局限流 主备路由 基础日志”系统反而稳定了团队也能专注在业务上。另外一个建议是如果你是小团队可以先试用云托管版的免费额度用真实业务跑两周确认网关的行为符合预期后再决定是否自建。自建意味着你要自己维护升级、监控、备份这些隐形成本往往被低估。跑通一个 Demo 不叫落地能稳定运行一个月才叫落地。AI 网关的选型没有什么压倒性的标准答案关键是匹配你团队当前的规模和真实痛点。如果你现在只有一个模型业务量也不大不需要网关如果同时接了三四个模型、有多个业务方接入、成本开始失控那这个 37K Star 的项目值得花一个下午好好玩一下。