Spring AI Gateway实战：统一管理多模型接入的AI网关搭建指南

做AI应用最烦的事之一，就是接多家大模型。你刚把供应商A的对话接口调通，老板又说要对比另一家的效果；线上密钥不小心泄露，急急忙忙改配置；月底账单出来，才发现某个业务线烧钱烧得离谱……这些问题如果让每个业务端直接去对接大模型API，根本管不住。所以我上个月在负责的模拟项目X里，用Spring AI做了一层统一网关：所有AI请求先打到网关，由它负责路由、鉴权、限流、缓存这些脏活累活。这篇文章就从零记录我搭建这套Spring AI Gateway的完整过程，包括设计取舍、核心代码，以及踩过的一堆坑，适合正在做AI应用集成、想统一管理多模型接入的Java开发者参考。

1. 为什么要做AI网关：设计思路与场景拆解

1.1 直接调大模型API的四大痛点

先说没有网关的时候，业务方是怎么接大模型的。以我的经验，每个业务线的同学拿到一个API Key之后，就在自己的服务里写一遍HTTP调用、配一遍超时重试、处理一遍流式返回。表面上看挺自由，其实麻烦全在后面。

第一个痛点是多供应商适配。你今天接了供应商A，明天产品经理说要对比供应商B的效果，你得重新读一遍对方的接口文档、重写一次客户端代码。同一个Prompt在不同厂商那里，参数名不一样，限制不一样，返回结构也不一样。业务侧改起来又慢又容易出错。

第二个痛点是密钥管理失控。API Key散落在各个服务里，有的直接写死在配置文件里，甚至提交到代码仓库。一旦泄露，成本飙升不说，还可能被恶意刷量。集中式管理密钥是刚需，但很多人一开始意识不到。

第三个痛点是成本与配额不可观测。没有网关层，你就没法统一统计每个业务线调了多少Token、花了多少钱。大模型账单是按Token计的，不同模型价格差很多，业务侧如果都有权限选择贵价模型，月底财务那边脸色不会好看。

第四个痛点是上下文与会话难以治理。对话型AI应用通常要带历史消息，业务侧各自为政的话，有的把整段历史塞进请求，有的完全不传，导致模型经常“失忆”。会话窗口怎么截断、按什么策略清理，也需要一个统一的地方来管。

这四个痛点叠加在一起，就形成一个明确结论：不管项目大小，只要你在认真做AI应用，迟早需要一层统一网关。

1.2 AI网关与传统API网关的差异

很多人一听“网关”，第一反应是Spring Cloud Gateway那套路由转发。确实，AI网关也是一个统一入口，但和传统API网关相比，有几个显著区别。

传统网关面对的是短连接、无状态、同步的REST请求，核心是路由、鉴权、限流这三板斧。AI网关面对的是大模型调用，响应时间动辄几秒到几十秒，而且同样一个Prompt，今天答的和明天答的可能不一样。这意味着AI网关不仅要管请求怎么走，还要考虑模型怎么选、上下文怎么带、成本怎么控。

另一个关键差异是流式输出。现在主流的大模型应用基本都走SSE（Server-Sent Events）流式返回，用户看到一个字一个字往外蹦，体验才好。但流式请求在网关层做转发时，连接要保持很长时间，反向代理的缓冲策略、超时配置稍有不对，就会吞掉中间的数据块或者直接掐断连接。

还有一点是有状态性。传统API请求是独立的，而AI对话天然有上下文。网关层必须决定会话ID怎么生成、历史消息存哪里、多长截断，这对传统网关来说完全是新问题。

1.3 为什么选择Spring AI

选型的时候我也考虑过自己封装HTTP客户端、或者直接用现成的各类SDK。后来对比下来，Spring AI最打动我的一点是：它把多厂商的差异收敛到了同一套API后面。

在Spring AI的体系里，ChatClient是门面，底层的ChatModel可以随时换成不同供应商的实现，业务代码几乎不用动。而且它天然融入Spring Boot生态，配置加载、自动装配、Starter机制都是现成的，和公司内部常用的Spring技术栈无缝衔接。

更重要的是，Spring AI还提供了Prompt模板、结构化输出、工具调用、对话记忆这些高层抽象。这些能力在网关场景里非常有用，比如我可以让网关自动给请求体里的对话历史做截断、按JSON Schema解析模型的输出，不用自己造轮子。虽然它有学习成本，但比起从零把各家SDK揉一起，性价比高太多了。

2. Spring AI基础与项目脚手架搭建

2.1 核心概念先搞明白

开始写代码之前，有必要把Spring AI的几个核心概念理清楚，不然看示例代码会一头雾水。

• ChatModel：底层模型抽象的接口，不同厂商的适配器都实现它，负责把Prompt发给模型服务、拿到响应。
• ChatClient：面向开发者的高层门面，构建Prompt、调用模型、解析输出都在这一层，支持链式调用。
• Prompt：一次完整请求的封装，里面包含一个或多个Message（System、User、Assistant），以及模型参数Options。
• Message：消息体，分为SystemMessage、UserMessage、AssistantMessage，对应着聊天里不同的角色。
• StreamingChatClient：流式接口，返回Flux类型的数据流，用于SSE推送。

一句话总结：ChatClient负责“好用”，ChatModel负责“能通”，Prompt和Message是两者之间传递的数据载体。网关层主要编程对象就是这三个。

2.2 环境准备与Maven依赖配置

我的环境是JDK 17、Spring Boot 3.3.x，用Maven管理依赖。Spring AI的BOM需要单独引入，否则版本不好对齐。

<dependencyManagement> <dependencies> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-bom</artifactId> <version>1.0.0</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement>

实际业务依赖就简单了，基础部分只需要两个Starter，一个Spring Web做接口暴露，一个Spring AI的Core模块。

<dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-starter-model-core</artifactId> </dependency> <!-- 如果网关本身要做Redis限流、缓存，再加这些 --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-data-redis</artifactId> </dependency> </dependencies>

版本号这块我要特别说一句：Spring AI的版本迭代非常快，不同版本API有调整。我写这篇文章时用的是1.0.0系，你如果遇到某个方法找不到，优先看自己版本对应的文档，别盯着老教程硬抄。

2.3 第一个最小可用的ChatClient调用

在网关里，一个最基础的调用长这样：

@Service public class ChatGatewayService { private final ChatClient chatClient; public ChatGatewayService(ChatClient.Builder builder) { this.chatClient = builder.build(); } public String simpleCompletion(String userMessage) { return chatClient.prompt() .user(userMessage) .call() .content(); } }

先把功能跑通，再谈网关治理。这个阶段没有任何路由和限流，就是一个能对外提供对话能力的普通服务。配置文件中只需要声明模型提供方的基本信息，因为要把供应商抽象开，我在配置文件里做了多模型注册：

spring: ai: chat: provider-a: base-url: https://api.provider-a.example.com api-key: ${PROVIDER_A_API_KEY} model: model-a-large provider-b: base-url: https://api.provider-b.example.com api-key: ${PROVIDER_B_API_KEY} model: model-b-pro

需要说明的是，不同厂商的Starter配置前缀不太一样，上面是个偏通用的写法。真实落地时，你去引入对应厂商的Spring AI Starter，配置项会跟着变。关键思路是：网关不直接依赖某一个厂商，而是通过依赖注入把多个ChatModel注册成Bean，后续路由时按需挑选。

2.4 多模型Bean的注册方式

为了让网关能动态切换模型，我定义了两个ChatModel的Bean，并用一个Map把所有模型装起来。

@Configuration public class ChatModelConfig { @Bean public ChatModel providerAChatModel(ProviderAProperties props) { return new ProviderAChatModel(props); } @Bean public ChatModel providerBChatModel(ProviderBProperties props) { return new ProviderBChatModel(props); } @Bean public Map<String, ChatModel> chatModelRegistry( ChatModel providerAChatModel, ChatModel providerBChatModel) { Map<String, ChatModel> registry = new HashMap<>(); registry.put("provider-a", providerAChatModel); registry.put("provider-b", providerBChatModel); return registry; } }

这里的好处是路由策略可以完全通过Key操作，想切换到哪个模型就取哪个Bean。后面做多模型降级、按业务线配比，都是基于这个注册表展开的。

3. 网关核心设计：路由、鉴权与上下文

3.1 统一入口路由设计

网关对外暴露的接口一定要稳定，不能让调用方跟着后端模型调整而改代码。我的做法是只暴露一个统一的对话端点，路径规划成两档：

• POST /v1/chat/completions：非流式，返回完整的JSON。
• POST /v1/chat/stream：流式，返回SSE事件流。

内部再根据请求头里的X-Business-Line或者请求体里的model字段做路由。这样业务方只需要对接一次，后面网关内部怎么调整、换哪家模型，对他们完全透明。

请求体我设计成类似业界常见的格式，保持长期稳定：

{ "businessLine": "customer-service", "sessionId": "sess-12345", "messages": [ {"role": "system", "content": "你是电商客服助手"}, {"role": "user", "content": "我想退一件衣服"} ], "temperature": 0.7 }

注意我把businessLine、sessionId单独拎出来，而不是让业务方直接指定模型名。目的是什么？把模型选择权收回到网关。业务方只需要说清楚自己是什么业务、想要什么效果，网关根据策略决定用贵模型还是便宜模型。这样做成本可控，也方便后续做模型灰度。

3.2 密钥安全管理

密钥管理是网关的核心职责。所有模型提供方的密钥统一放在网关这里，通过环境变量或者配置中心注入，不进代码仓库。网关给每一个内部客户端分配一个访问令牌，业务方调用网关时，只需要带自己的访问令牌，完全不接触底层厂商密钥。

我这里做了一个简单的Token校验逻辑：

@Component public class AccessTokenFilter implements Filter { private final Map<String, String> clientTokens = Map.of( "customer-service", "token-xxxx-cs", "data-analysis", "token-xxxx-da" ); @Override public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException { HttpServletRequest req = (HttpServletRequest) request; String token = req.getHeader("X-Client-Token"); if (token == null || !clientTokens.containsValue(token)) { response.setStatus(401); return; } chain.doFilter(request, response); } }

生产环境肯定不能这么简单，至少要上JWT或者对接公司已有的OAuth体系，但思路是一样的：网关隔离底层的密钥，客户端只认网关发的令牌。这样做之后，就算某个业务方的代码仓库泄露了，最多泄露网关访问令牌，底层模型密钥依然安全。

3.3 会话管理与上下文截断

对话应用绕不开上下文。我的网关用Redis存会话历史，Key的设计是sessionId，Value是一个消息列表。每次请求进来，网关先从Redis取历史，拼接上用户新发来的消息，作为完整的Prompt发给模型。拿到模型回复后，再把用户消息和模型回复追加进Redis。

这里有个细节很容易被忽略：上下文不能无限长。大模型都有Token窗口限制，超出上限不仅报错，还会导致响应变慢、成本飙升。我参考常见实践设计了一个简单的截断策略：

• 计算当前历史消息的估算Token数，一个汉字大概按1.5个Token算。
• 超过窗口的60%时，从最早的消息开始丢弃，保留最近的消息。
• System消息永远保留，不参与截断。

public List<Message> buildMessagesWithTruncation(String sessionId, String userMessage, int maxTokens) { List<Message> history = sessionStore.get(sessionId); List<Message> messages = new ArrayList<>(history); messages.add(new UserMessage(userMessage)); int totalTokens = estimateTokens(messages); while (totalTokens > maxTokens && messages.size() > 1) { messages.remove(1); totalTokens = estimateTokens(messages); } return messages; }

这个方法不算精致，但胜在简单可靠。实际项目里可以用更精确的Token工具做截断，但核心原则都是一样的：优先保留System消息和最近的对话内容。

4. 网关核心实战：限流、缓存、降级与流式输出

4.1 限流策略的落地实现

AI请求比普通API请求更容易被打爆。大模型接口响应慢，如果并发一高，连接池和线程池都会迅速耗尽。而大模型API本身也有速率限制，超过QPS直接返回429，所以网关必须前置限流。

我用的是令牌桶算法，每个客户端维度一个桶。实现上直接基于Guava的RateLimiter封装了一层：

@Component public class AiRequestRateLimiter { private final Map<String, RateLimiter> limiterMap = new ConcurrentHashMap<>(); public boolean tryAcquire(String clientId, double qps) { RateLimiter limiter = limiterMap.computeIfAbsent(clientId, key -> RateLimiter.create(qps)); return limiter.tryAcquire(); } }

使用的时候，在Controller入口先检查，拿不到令牌就返回429和明确提示。QPS不能随便拍脑袋定，要结合模型提供方的配额和自己的机器规格。我这边给客服业务线配了10 QPS，数据分析线配了2 QPS，运营做报表拉数据的请求可以低一点，因为都是离线任务，慢一点没关系。

限流还有一个容易被忽略的维度：成本限流。即使QPS不高，某些贵价模型的单次调用成本很高，一天累计开销吓人。我额外做了一个每日Token预算的简单计数器，用一个定时任务每分钟把消费数据累加进Redis，超过当天预算就自动把该业务线切到备用便宜模型。这种做法在真实场景里能帮你省下不少钱。

4.2 响应缓存设计

AI响应能不能缓存？答案是可以，但缓存范围要控制好。像客服场景里的常见FAQ、政策解释这类问题，模型答案基本稳定，没必要每次重新调用烧钱。我选择对幂等、可重复的请求做缓存。

缓存Key的生成用请求参数的Hash。这里注意，不要让温度参数参与缓存判断，因为同一个问题，温度不同答案就不一样。我的策略是temperature=0的请求才允许走缓存，因为这类请求结果最稳定。

public ChatResponse handleCompletion(GatewayChatRequest request) { String cacheKey = "ai:cache:" + request.getBusinessLine() + ":" + md5(request.getMessages()); ChatResponse cached = cacheService.get(cacheKey, ChatResponse.class); if (cached != null) { return cached; } ChatResponse response = callModel(request); if (request.getTemperature() == 0) { cacheService.set(cacheKey, response, Duration.ofHours(1)); } return response; }

缓存时间长短要看业务。客服FAQ我设的是1小时，产品文档问答因为内容更新不频繁，设了24小时。有一点要提醒：大模型幻觉问题决定了缓存不是百分百安全，关键的法律、医疗建议类业务不建议开缓存，省这点钱不值得。

4.3 降级与熔断

模型供应商也是会出状况的。我遇到过供应商A的接口连续5分钟超时，如果网关不做降级，所有依赖它的业务线全部瘫痪。后来我引入了一个简单的熔断器：用线程安全计数器统计最近1分钟内调用失败率，超过30%就打开熔断开关，后续请求自动切换到备选模型。

public ChatModel selectModel(String businessLine) { String primary = routeRule.getPrimary(businessLine); if (circuitBreaker.isOpen(businessLine)) { return registry.get(routeRule.getFallback(businessLine)); } return registry.get(primary); }

熔断开关打开后不能无限期生效，我设置了一个半开状态：每30秒放少量测试请求到主模型，如果恢复成功就关闭熔断，否则保持打开。这套逻辑不复杂，但确实能救命。有一回供应商A在凌晨发版出了故障，网关自动把所有生产流量切到备模型，业务侧几乎无感知，第二天同事看监控才发现前半夜有抖动。

4.4 流式输出的网关转发细节

流式请求是网关技术含量最高的地方。Spring AI的ChatModel支持流式返回，类型是Flux，配合Spring Web的SSE输出很自然：

@PostMapping(value = "/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE) public Flux<ServerSentEvent<String>> stream(@RequestBody GatewayChatRequest request) { ChatModel model = routingService.selectModel(request.getBusinessLine()); Flux<String> contentFlux = model.stream(new Prompt(request.getMessages())) .map(chunk -> chunk.getOutput().getContent()); return contentFlux .map(content -> ServerSentEvent.<String>builder() .event("message") .data(content) .build()) .doOnError(e -> log.error("stream error", e)) .onErrorResume(e -> Flux.just( ServerSentEvent.<String>builder() .event("error") .data(e.getMessage()) .build())); }

这里有几个关键细节：

• 网关往外推SSE时，负载均衡器或反向代理不能缓冲响应体。如果你前面挂了Nginx，必须把proxy_buffering关掉，否则用户会等很久才看到第一批字。
• Web容器层要放开响应超时，Spring Boot的server.servlet.async.timeout可以根据业务情况设成60秒，但底层的TCP连接超时也要同步调整。
• 流式场景中客户端断开的检测要处理好。用户中途关掉页面，网关还傻傻等着模型把整段结果流完，浪费资源。用doOnCancel清理下游连接是必要的，我踩过一次，用户关页面后网关连接池直接被占满了。

5. 实战案例：模拟多模型智能客服网关

5.1 需求背景与整体架构

这套案例来自我实际做过的一个模拟项目X，技术栈就是上面写的Spring AI Gateway。业务场景是智能客服，需要同时支持售前咨询、售后订单、政策问答三类问询，模型选择上，售前用便宜快速的模型省钱，售后用逻辑能力强的贵模型保证准确度，政策问答对时效性要求低，可以走缓存。

整体组件就三块：网关服务、Redis、模型提供方。网关里包含路由配置、限流器、缓存服务、会话存储、熔断器。

5.2 路由规则配置

我维护了一份路由规则，集中放在配置类里，避免硬编码：

@Component public class RouteRule { public static class Rule { String primary; String fallback; double qps; int maxContextTokens; double costBudget; } private final Map<String, Rule> rules = Map.of( "pre-sales", new Rule("provider-a", "provider-b", 10, 4000, 50), "after-sales", new Rule("provider-b", "provider-a", 5, 16000, 80), "policy", new Rule("provider-a", "provider-b", 2, 2000, 20) ); public Rule get(String businessLine) { return rules.getOrDefault(businessLine, rules.get("pre-sales")); } }

这份配置的意义是让策略显性化。改模型分配、调QPS都不需要动业务代码，改完发布就行。甚至可以把规则放进配置中心，运行时动态刷新，对运维更友好。

5.3 核心Controller代码

完整的Controller逻辑分三步：鉴权、限流、分发。

@RestController @RequestMapping("/v1/chat") public class ChatGatewayController { private final AccessTokenFilter accessTokenFilter; private final AiRequestRateLimiter rateLimiter; private final RouteRule routeRule; private final ChatGatewayService gatewayService; @PostMapping("/completions") public ResponseEntity<?> completions(@RequestHeader("X-Client-Token") String token, @RequestBody GatewayChatRequest request) { if (!accessTokenFilter.valid(token)) { return ResponseEntity.status(401).body("invalid token"); } RouteRule.Rule rule = routeRule.get(request.getBusinessLine()); if (!rateLimiter.tryAcquire(request.getBusinessLine(), rule.qps)) { return ResponseEntity.status(429).body("rate limit exceeded"); } ChatResponse response = gatewayService.handleCompletion(request, rule); return ResponseEntity.ok(response); } @PostMapping(value = "/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE) public Flux<ServerSentEvent<String>> stream(@RequestHeader("X-Client-Token") String token, @RequestBody GatewayChatRequest request) { // 同样的鉴权、限流逻辑 ChatModel model = gatewayService.selectModel(request.getBusinessLine()); return model.stream(new Prompt(request.getMessages())) .map(chunk -> ServerSentEvent.<String>builder() .event("message") .data(chunk.getOutput().getContent()) .build()); } }

实际交付时我把鉴权做成了Servlet Filter，每个请求都过一遍，不用在Controller里重复写。上面的Controller代码是为了展示完整调用链。

5.4 测试与压测结果

本地测试阶段，我用一个并发脚本同时打了300个流式请求，把线程池压到极限，观察到的现象是：线程池满之后，新请求直接排队，接口响应时间从200ms飙升到5秒。后来我把线程池调大、配合限流提前拦截一部分请求，改善明显。最终线上配置的核心参数如下：

• 核心线程数：200
• 最大线程数：400
• 队列容量：1000
• 单个模型连接超时：5秒
• 读取超时：60秒

这套参数在我们的模拟压测里能稳定支撑每类业务线的流量，没有出现线程池耗尽和连接超时。真实的数字你要根据自己业务的调用量和模型响应时间重新测，没有一个参数是万能的。

6. 常见问题与排查实录

6.1 连接超时与线程池耗尽

这个坑几乎每个接大模型的项目都会遇到。模型服务响应慢是常态，如果你网关的HTTP连接超时设得短，比如只有3秒，那业务稍微复杂一点就会触发超时，导致前端看到的错误率虚高。我把连接超时和读取超时拆开处理：连接超时设5秒，读取超时设60秒。连接超时短是快速失败，别等；读取超时长是给模型充分的生成时间。

线程池这边，我的经验是别只盯着默认值。Spring Boot内嵌Tomcat默认的200线程在AI网关这种长耗时场景下很容易被占满，因为每个请求都要占用一个线程几十秒。配合限流和异步调用，一定要做压测，让数据说话。

6.2 流式SSE的编码与代理问题

SSE这块我栽过两次跟头。第一次是响应在网关和负载均衡之间被缓冲了，所有的字等到模型完整生成完才一次性吐给用户，和体验预期完全不符。第二次是客户端解析事件时没按事件流来，把所有data块拼成一个JSON字符串，解析时报错。这两个问题的排查都不难，看响应头里的Content-Type是不是text/event-stream、看网络面板里有没有分块到达，基本就能定位。

6.3 令牌桶与分布式限流的取舍

单机RateLimiter实现简单，但如果网关服务部署了多个实例，每个实例各自限流，实际放行的总量会翻倍。要真正做到按全局维度限流，得用Redis + Lua脚本做分布式令牌桶。我在早期版本偷懒直接用单机限流，后来压测发现问题，才换成了分布式方案。这里分享一个实践心得：如果你的AI网关只是内部小范围使用，单实例部署，单机限流完全够用；如果流量增长，优先上Redis限流，不要等到出问题再补。

6.4 上下文长度与Token成本估算

Token估算的精度直接影响截断效果和成本控制。我用一个比较经典的粗略公式：英文按字符数除以4，中文按字数乘以1.5。这个估算模型在中文场景下还算靠谱，误差在10%以内。如果你需要更精确的数字，建议引入厂商的Token统计工具或者通用的Tokenizer库，但要注意统计本身也占资源，别在高频接口里用太重的计算。

最后再分享一个从这套项目里沉淀下来的心得：AI网关这种中间层，最难的不是编码，而是策略设计。密钥统一在哪里管、路由按什么维度分、缓存哪些业务能开、哪些不能开，这些问题想清楚，代码反而是水到渠成的事。不要一上来就堆功能，先把你当前的业务场景理明白，哪怕只做路由和限流，能跑起来就是成功的第一步。后面真要扩展，再逐步加缓存、降级、成本控制这些能力，都来得及。我在这个项目上最大的收获就是：网关层每多管一件事，业务侧和财务侧就少挨一次打。