MAI Gateway 落地实践把 AI 网关用在 RAG 场景里到底是不是叠床架屋这是我们立项时被产品和技术两头追问最多的一句话。当时团队要做的是一个面向企业内部资料的知识库问答系统RAG 方案自然成了首选但在模型调用层我们发现随着接入的底层模型越来越多、调用来源越来越杂单纯把向量检索做得再漂亮也掩盖不了入口失控的混乱。因此我们引入了 MAI Gateway 作为统一的 AI 网关层让所有模型请求都从这一个口子进出而 RAG 检索链路则挂在网关背后作为一组普通的“后端服务”。这篇文章不是讲 RAG 算法的原理课也不是 MAI Gateway 的官方文档翻译。我想用真实的落地过程说清楚三件事AI 网关在 RAG 里到底解决什么问题网关和检索链路之间怎么配合以及在配置网关时哪些参数值得反复调、哪些坑我们替大家踩过了。如果你正准备给团队知识库、客服机器人或者文档问答系统做 RAG又担心模型调用层管不住这篇应该能帮你省几周时间。1. 为什么 RAG 需要一层 AI 网关1.1 RAG 链路里最容易被忽视的瓶颈很多人对 RAG 的第一印象是“向量检索 大模型生成”。于是精力全放在文档切分、Embedding 选型、向量库调优上这当然没错但实际把系统放上生产环境之后最先出问题的往往不是检索质量而是模型调用这一层。举个例子我们的知识库里有几千份技术文档用户提问后系统先做向量检索把 Top 5 片段拼进 Prompt再送给大模型生成答案。看起来链路清晰但一旦用户量上来问题就来了——不同用户用的客户端版本不同有的走网页、有的走 IM 机器人、有的走 API模型那边有主模型、备用模型、Embedding 模型团队里不同项目组还各自申请了不同的 API Key。结果就是调用入口混乱、计费对不上、某个模型限流了也不知道该在哪个环节重试。这就是需要 AI 网关的核心原因。MAI Gateway 做的事情本质上是“统一入口 调度控制”所有上游请求先到网关网关决定转给哪个模型、是否需要缓存、是否限流、是否重试然后统一返回。检索链路本身不关心你用的是 OpenAI 还是本地 Ollama它只要一个稳定的、格式统一的模型调用接口。1.2 网关作为“统一入口”的价值用生活化的比喻网关就像一个公司前台。来访者不需要知道谁坐在哪个工位只要到前台说“我要找技术部”前台就能帮你转接、记录访客、控制同一时间最多进多少人。如果没有前台所有人都直接往办公区里冲里面的人不仅烦而且工作节奏会被完全打乱。落到 RAG 场景MAI Gateway 的价值可以拆成四点协议统一团队里任何服务都只需要对接一个 OpenAI 兼容格式的接口网关后端可以接不同厂商、不同协议的模型甚至本地部署的模型。流量控制知识库问答的请求往往有突发性比如早晚高峰。网关层做限流、排队、熔断能避免底层模型被打爆尤其当底层模型是共享服务时。成本与审计每个请求经过网关时都能记录 token 消耗、链路耗时、调用来源。知道哪个用户烧了多少 token这在做成本分摊时极其重要。灰度与切流当我们要从模型 A 切到模型 B 时只需要在网关改一个路由策略而不是让每个上游服务都发一轮变更。这些能力单独看都不算新鲜但组合在一起正好补上了 RAG 项目里最容易粗放管理的“模型调用”环节。2. 项目背景与整体方案设计2.1 业务场景知识库问答的痛点我们做的系统叫“内部资料智能问答”主要面向公司几千名员工覆盖产品文档、技术规范、项目复盘等非公开资料。用户自然语言提问系统返回回答并附上引用来源。听起来和一些公开 RAG Demo 差不多但内部场景有几个特殊约束资料权限敏感技术和财务文档不能公开回答也必须限定在资料范围内不能靠模型“自由发挥”。检索质量要求高公司内部问法五花八门比如“服务器内存不够怎么办”“上线流程是什么”这些问题的答案往往散在多份文档里单靠关键词检索很难命中。模型稳定性要求高系统在工作时间高频使用模型服务一旦抖动直接影响一批同事的工作效率。最初团队用 LangChain 搭了一版原型检索用向量库生成用外部模型 API。效果尚可但一到联调阶段就发现问题外部 API 偶尔连接超时、返回结构不统一、每天调用量上去了还要挨个去找服务商要配额。这些问题逼迫我们把“模型接入”这件事提级处理。2.2 架构选型MAI Gateway 与 RAG 的集成方式在选型阶段我们比较了几种方案。第一是完全自己封装一个模型调用 SDK看着灵活但每个语言都要维护一套团队成本太高第二是直接用某个云厂商的模型平台方便但绑定太深且内部资料要过第三方安全上过不了第三才是自建或自托管一套 AI 网关对外统一模型接口对内可接各种模型后端。我们最终选择自托管 MAI Gateway。选定它的原因很实际它支持 OpenAI 格式的接口能配置多后端负载均衡有稳定的缓存、重试、限流能力并且可以部署在自有环境里。与 RAG 的集成方式也简单——RAG 服务不再直连模型而是把所有生成和 Embedding 请求统一发给网关卡。整体架构大体如下用户提问 → API 网关/业务服务 → 知识库检索模块切分、向量检索、重排→ 拼装 Prompt → MAI Gateway → 模型后端主模型 / 备用 / Embedding这条链路里MAI Gateway 的作用是“最后的统一出口”。无论上游是哪个业务方都通过网关卡拿模型结果网关帮我们挡掉了多模型兼容问题也把调用的可观测性数据集中收拢。3. 真实落地案例与关键参数解析3.1 检索层改造向量库、重排与命中率从原型到生产检索层经历了一次重要改造。第一版只做了向量检索chunk 固定 500 字Top 5 直接拼 Prompt上线后发现“rag hit rate”也就是命中率只有五成出头经常出现“答案在资料里但检索不到”的情况。后来我们加了几个关键改进。切分策略调整从固定字符切分改为按标题结构切分。技术文档通常有清晰的一级/二级/三级章节按语义边界切分后一个 chunk 更大概率包含一个完整主题。切分长度设为 300 到 800 字之间重叠 50 字避免关键信息被硬生生截断。混合检索只用向量检索容易丢专有名词比如“压测”“限流”“CAP 定理”向量召回有时不如关键词精确。我们改成“向量召回 BM25 关键词召回 重排”的方案先两路各召回 Top 20再用一个轻量级重排序模型统一打分综合后取 Top 5。这样 hit rate 从五成多提到了七成半左右。Embedding 模型选择Embedding 模型的领域适配非常重要。通用 Embedding 对专业领域术语的区分度不够后来我们选用了一个在中文技术资料上表现更好的领域模型在内部文档数据集上做了一点微调最终在验证集上的 Recall5 提升了接近 8 个百分点。这一步做得值。3.2 网关层配置路由、限流、缓存、重试MAI Gateway 在项目里的核心配置主要围绕四块路由、限流、缓存、重试。路由策略我们配置了主模型和备模型两个上游。默认流量全部走主模型当主模型连续报错或超时比例超过阈值时网关自动把流量切到备模型。这个功能在 RAG 场景下特别实用因为 RAG 的一次问答通常涉及 Embedding 调用和生成调用如果生成模型挂了整个问答体验直接归零。限流内部用户高峰期会集中提问Pineline 上并发经常瞬间冲到 100。在网关层设置“每秒最大请求数”和“单用户每分钟最大请求数”超出的排队或返回友好提示。这一层能有效避免底层模型被挤爆也保证了高优先级用户优先获得资源。缓存知识库问题和问题之间重复度不低尤其像“报销流程”“服务器申请”这类高频问题。MAI Gateway 支持对相同请求做语义缓存命中后直接返回之前的结果。我们的实测中缓存命中后响应时间从 2 秒以上降到 200 毫秒以内效果非常明显。注意这里不能只看文本完全一致我们后来做了问题归一化处理把一些常见表述映射到统一问法缓存命中率才真正上去。重试模型调用偶尔会超时或者返回 5xx。直接在业务代码里重试容易造成重复计费而且重试策略很难统一。放网关后我们把超时时间设为 30 秒失败后最多重试 2 次且只在“可重试”的异常类型上触发幂等性由网关保证。这样上游服务不需要关心重试逻辑代码清爽很多。下面是我们当时压测的一组对比数据可以比较直观地看到网关不只是在“拦截”还在帮 RAG 链路兜底场景无网关模式接入网关模式高峰期平均响应时间约 3.8 秒受模型波动影响约 2.1 秒缓存命中后低于 0.5 秒生成接口调用失败率局部可达 12%降到了约 1%上游需要处理模型差异每个业务方都要适配只需统一对接网关token 成本统计手工汇总误差大网关自动分账账单级精度4. 实操过程与核心环节实现4.1 环境搭建与基础配置MAI Gateway 的部署本身并不复杂一台 2C4G 的虚拟机就能跑起来作为测试环境。我们采用 Docker Compose 部署配置里包含数据库用于保存路由规则和调用日志、网关核心服务、以及一个简单的管理后台。生产环境则加了高可用相当于至少两个网关实例挂同一个数据库前面再加一层负载均衡。基础配置里最需要注意的是“模型供应商”的定义。MAI Gateway 里我们分别配置了Chat 模型供应商主模型地址、API Key、超时时间、模型名称映射。Embedding 模型供应商路径/v1/embeddings默认模型名。备模型供应商用于自动切换。这里有个小技巧所有模型名称统一在网关层做映射。上游业务只需要调用gpt-4o这个名字网关内部可以把它转给本地模型或者外部兼容模型。未来换模型时业务代码不用改只要改网关映射表。这对 RAG 这种“模型选型容易变”的系统来说帮助极大。4.2 本地 RAG 实验Ollama 简易知识库在正式接入生产模型之前我们先用本地模型跑通了一版“零成本” RAG。这一版完全是给团队验证流程用的也是我对想做 RAG 新手的一个建议别一上来就买各种付费服务先用本地工具把链路摸熟。本地配置大概是这样的部署 Ollama拉取一个 7B 级别的问答模型和一个 Embedding 模型。文档切分后用本地 Embedding 模型生成向量存入向量数据库。检索模块负责查询、重排然后组装 Prompt。最后把 Prompt 请求发给 MAI Gateway网关转发给 Ollama。这套方案在几十份文档的小规模测试里完全可用回答质量虽然不如生产级大模型但是“RAG 链路”本身被验证了包括切分、检索、拼 Prompt、网关转发、限流、重试所有环节都真实地跑了一遍。这么做还有一个很大的好处团队新同学上手时不需要申请任何外部账号在本地就能把整个流程模拟一遍降低了不少教学成本。而且 Ollama 这种本地模型配合 MAI Gateway 的小实验也能帮你发现一些“只在真实调用链路上才会暴露”的问题比如请求格式、鉴权头、并发控制等。4.3 从本地到生产网关策略如何调整本地实验能跑通不等于生产环境能扛住。从本地模型切到生产模型时我们对网关做了几类调整。第一类调整是并发和限流。内部的用户量和模型响应时间我们做了估算假设 500 个活跃用户每个用户高峰时段可能产生 20 个问题每个问题有 1 次 Embedding 调用和 1 次生成调用那么大致高峰 QPS 在几十到一百量级。我们把网关的单实例并发上限设在 200超过之后排队处理避免线程被拖死。第二类调整是缓存策略。生产环境里我们开启了语义缓存但设定了 30 分钟过期。知识库内容更新后缓存会在合理时间内自动失效不会返回过期信息。第三类调整是安全。网关管理后台的登录必须走企业内部的 SSO外部访问一律禁止。所有 API Key 都存储在网关的密钥配置中心不上传代码仓库。RAG 系统本身还加了一层权限过滤用户只允许检索其有权限查看的文档切片这个权限判断发生在 RAG 服务内部网关层不参与。生产环境上线后的第一个月我们发现整条链路确实稳定了很多。曾经模型厂商发公告要调整接口版本我们只在网关层改了一行映射所有业务方无感知这在以前简直不敢想。5. 常见问题与排查技巧实录5.1 命中率低、响应慢怎么排查先说命中率。如果你的 RAG 出现“答案找不到”的问题先别怀疑模型八成是检索没召回。我通常按下面几步排查先看 Top 5 结果的相似度分数如果普遍低于 0.3那基本可以判断是检索质量问题不是生成问题。再看切分粒度。整篇文档切成一个 chunk 肯定不行切得太碎又会丢失上下文。500~800 字是常用区间但还要结合文档结构调整。然后看是否需要混合检索。纯向量召回对领域专有名词不友好加一层 BM25 关键词召回通常能明显改善。最后看重排模型。Top 20 粗召回之后如果不重排很可能把最相关的片段排到第五名之外。响应慢的问题则按“链路时间”拆解用户感知慢先看网关日志里模型调用耗时模型调用耗时正常那就看检索耗时检索耗时正常再检查网络、代理、客户端。MAI Gateway 会记录每个阶段的耗时这让我们定位性能问题变得很简单。5.2 网关配置的典型坑鉴权、超时、并发配网关期间我们踩过几个不太容易发现的坑分享出来给大家避雷。坑一上游模型供应商的鉴权方式不一致。有的服务商要求Authorization: Bearer key有的要求自定义 header还有的在 Body 里传 key。MAI Gateway 虽然做了适配但你需要为每个供应商单独确认鉴权方式否则会出现“本地调通生产不通”的诡异问题。我们的经验是接入新的模型供应商时先手动 curl 一次原生的 API确认最朴素的调用能通再配置到网关上。坑二超时时间设得太短。RAG 生成阶段模型需要读完整段 Prompt 并生成较长回答通常比普通的单轮闲聊耗时更长。如果你把网关超时设成 10 秒生成稍长一点就会超时。我们最后把生成接口超时调到 60 秒Embedding 接口调到 15 秒才算稳定。坑三重试时没有考虑“不可重试错误”。比如因为 Prompt 内容违规被模型服务商拒绝这种请求重试再多次也没用只会增加成本。所以在网关重试配置里要把 4xx 错误排除只对 5xx 和网络超时做重试。教训来自于某次事故一个恶意用户反复触发内容检查失败网关连续重试token 费用哗哗涨最后查日志才发现是误配置。5.3 问题速查表问题现象可能原因排查方向回答引用不正确检索结果排序问题检查重排模型和检索阈值尝试降低 top-k 阈值回答内容答非所问切分粒度不合理检查 chunk 是否跨标题、重叠是否过多模型调用频繁超时生成模型响应时间过长调大网关 timeout或切换效率更高的模型token 成本异常增长缓存命中率低/重试策略错误查看网关日志确认缓存命中率减少无效重试高峰期间响应缓慢限流策略不匹配调整网关并发数与排队机制必要时扩容网关实例嵌入请求失败导致整条链路不可用Embedding 模型服务不稳定给 Embedding 也配置备用路由或做本地模型兜底5.4 关于 RAG 与网关联动的一些经验在项目里待得越久越体会到 RAG 并不是“一个检索算法”那么简单它是一个系统。检索模块、提示词构建、模型路由、权限控制、缓存策略、成本统计任何一个环节掉链子最终用户体验都会打折扣。MAI Gateway 在我们这里承担的是“模型侧基础设施”的职责让 RAG 团队可以更专注地优化检索质量和答案质量而不是天天和模型供应商吵架。我特别想强调“可观测性”带来的好处。以前没有网关时我们只能看到业务日志里“模型调用失败”这种模糊记录。现在网关于每一类请求都有耗时、成功率和 token 消耗统计很多问题一眼就能看出是哪一段的锅。比如某次整体响应变慢从网关统计图里发现是 Embedding 服务的 p99 延迟突增于是迅速定位到向量库连接数不足而不是盲目去调大模型。6. 关于 RAG 和网关的几点个人体会做这个项目之前我也觉得 RAG 和 AI 网关是两回事一个管“怎么找知识”一个管“怎么调模型”。但实际跑完一遍之后我的看法彻底变了。RAG 系统的边界其实不是“检索 生成”就完了而是从用户提问到答案返回的一整条链路。只要这条链路上有任何不可控因素整个系统的体验就会变得脆弱。而 AI 网关恰恰能把这段链条里的“模型服务不确定性”收拢起来让 RAG 工程师不用天天盯着上游服务状态。我个人觉得最适合先用 AI 网关加持 RAG 的团队有三种一是模型供应商不固定随时可能切换或灰度二是团队内部有多个业务方共用同一个知识库问答服务需要统一鉴权和审计三是问答请求有较强的高峰期特征需要限流和缓存来控制成本与稳定性。如果你的项目有这三个特征之一那就别犹豫直接在 RAG 前面加一层网关。如果只是个小 Demo什么都不用加本地 Ollama 直接跑就完了。这个项目实践下来MAI Gateway 最大的价值不是“多一层保障”这么简单而在于帮助整个 RAG 链路变得更可控、更可维护、更可解释。最后再分享一个小技巧上线后别急着把网关的日志自动清理尤其是 retry 信息和路由切换记录。有一次我们排查一个偶发答案错误查了一天都没头绪最后翻到网关日志里某次请求被自动切到了备用模型而备用模型的返回值格式和主模型略有不同导致 RAG 解析层处理出错。说白了网关确实帮我们挡住了很多麻烦但前提是你得知道它做了什么操作。保留日志、定期抽查是让网关长期稳定发挥作用的隐形保障。