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 对专业领域术语的区分度不够，后来我们选用了一个在中文技术资料上表现更好的领域模型，在内部文档数据集上做了一点微调，最终在验证集上的 Recall@5 提升了接近 8 个百分点。这一步做得值。

3.2 网关层配置：路由、限流、缓存、重试

MAI Gateway 在项目里的核心配置主要围绕四块：路由、限流、缓存、重试。

路由策略：我们配置了主模型和备模型两个上游。默认流量全部走主模型，当主模型连续报错或超时比例超过阈值时，网关自动把流量切到备模型。这个功能在 RAG 场景下特别实用，因为 RAG 的一次问答通常涉及 Embedding 调用和生成调用，如果生成模型挂了，整个问答体验直接归零。

限流：内部用户高峰期会集中提问，Pineline 上并发经常瞬间冲到 100+。在网关层设置“每秒最大请求数”和“单用户每分钟最大请求数”，超出的排队或返回友好提示。这一层能有效避免底层模型被挤爆，也保证了高优先级用户优先获得资源。

缓存：知识库问题和问题之间重复度不低，尤其像“报销流程”“服务器申请”这类高频问题。MAI Gateway 支持对相同请求做语义缓存，命中后直接返回之前的结果。我们的实测中，缓存命中后响应时间从 2 秒以上降到 200 毫秒以内，效果非常明显。注意这里不能只看文本完全一致，我们后来做了问题归一化处理，把一些常见表述映射到统一问法，缓存命中率才真正上去。

重试：模型调用偶尔会超时或者返回 5xx。直接在业务代码里重试容易造成重复计费，而且重试策略很难统一。放网关后，我们把超时时间设为 30 秒，失败后最多重试 2 次，且只在“可重试”的异常类型上触发，幂等性由网关保证。这样上游服务不需要关心重试逻辑，代码清爽很多。

下面是我们当时压测的一组对比数据，可以比较直观地看到网关不只是在“拦截”，还在帮 RAG 链路兜底：

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 问题速查表

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 解析层处理出错。说白了，网关确实帮我们挡住了很多麻烦，但前提是你得知道它做了什么操作。保留日志、定期抽查，是让网关长期稳定发挥作用的隐形保障。