文章目录前言你的 AI 应用是不是也缺个小区保安先搞清楚Spring AI Alibaba v1.0 到底是个啥为什么非要搞个 AI 网关被坑过的人都懂环境准备工欲善其事先搞懂依赖核心概念用饭店后厨给你讲清楚1. Agent智能体2. Graph工作流图3. MCPModel Context Protocol4. Chat Memory记忆实战从零搭建一个 AI 网关服务第一步引入核心依赖第二步配置文件第三步定义 MCP 工具模拟订单查询第四步搭建 Graph 工作流第五步暴露 REST 接口企业级进阶别只会 Hello World1. 接入 Higress AI 网关做统一代理2. MCP 服务注册到 Nacos3. 记忆持久化到 Redis4. 可观测性接入踩坑指南前人踩过的坑你就别跳了坑 1版本对齐问题坑 2Graph 的状态序列化坑 3Prompt 注入攻击坑 4Token 爆炸结语Java 程序员的 AI 时代真的来了无意间发现了一个巨牛巨牛巨牛的人工智能教程非常通俗易懂对AI感兴趣的朋友强烈推荐去看看传送门https://blog.csdn.net/HHX_01前言你的 AI 应用是不是也缺个小区保安兄弟你有没有遇到过这种糟心事公司刚上线的 AI 客服早上还能愉快地跟客户唠嗑中午就因为某个第三方模型 API 抽风整个系统直接躺平老板的电话比 120 还来得快。或者说你们团队好不容易搞了个多智能体系统结果三个 Agent 之间互相踢皮球调用链路乱得像早高峰的西直门立交桥排查问题查到怀疑人生。说白了AI 应用这玩意儿光会调大模型接口那只是幼儿园水平。真到了企业级场景你得考虑模型调用怎么 failover多个 Agent 怎么 orchestratePrompt 怎么集中管理Token 消耗怎么监控这就跟你住高档小区一样不能只盖别墅还得有靠谱的安保系统、物业中枢、消防通道——这就是AI 网关存在的意义。好消息是2025 年 6 月Spring AI Alibaba 终于放出了 v1.0 GA 正式版。这可不是之前那些试试水的里程碑版本而是真正生产可用的 Java 智能体框架。咱们今天就用最接地气的方式聊聊怎么用它从零搭一个企业级 AI 网关让你团队的 AI 应用从作坊模式切换到正规军模式。先搞清楚Spring AI Alibaba v1.0 到底是个啥如果你之前玩过 Spring AI可能会想这不就是 Spring 官方那个 AI 框架的阿里定制版吗对但也不全对。Spring AI 确实是 Spring 官方在 2025 年 5 月发布的 1.0 GA 版本主打的是底层原子能力——比如 ChatModel、Prompt、RAG、Tool Calling 这些基础设施。但 Spring AI Alibaba v1.0 呢它更像是在 Spring AI 基础上给你装修好的精装房。阿里团队把他们在内部和生产环境踩过的坑、验证过的最佳实践全都打包进去了。最核心区别就是它自带 Graph 多智能体编排框架还有一堆企业级生态集成——Nacos MCP 注册中心、Higress AI 网关、百炼平台、ARMS 监控等等。打个比方Spring AI 给了你砖头和水泥Spring AI Alibaba 则直接给了你户型设计图施工队物业管理系统。特别是这个 Graph 框架它跟 LangGraph 有点像但是为 Java 开发者量身定制的能让你用写 Spring Boot 应用的方式拖拖拽拽或者写写代码就把多智能体工作流给编排出来。为什么非要搞个 AI 网关被坑过的人都懂在说怎么搭之前咱们得先达成共识为什么需要专门搞个 AI 网关直接让业务服务调 OpenAI 或者 DashScope 的接口不行吗兄弟这就跟你直接让外卖骑手进后厨拿餐一样效率是高但迟早出乱子。生产环境的 AI 调用至少得解决这几个灵魂拷问第一稳定性与熔断大模型 API 可不是你家内网服务时不时给你来个 429请求过多或者 503服务不可用。没有网关做统一代理和熔断降级每次出问题都是 P0 事故。Higress 作为 AI 网关就能帮你做智能路由一个模型挂了自动切另一个就像机场自动值机柜台这个坏了隔壁马上顶上。第二MCP 工具治理现在流行 MCPModel Context Protocol让大模型能调用各种外部工具。但企业里工具多了怎么管Nacos MCP Registry 就像一个工具市场所有的 MCP Server 都在这注册、发现、负载均衡还能动态上下线。没这个你的 Agent 找工具就跟去菜市场买菜一样得挨个摊位问。第三Prompt 与上下文管理Prompt 现在也是资产啊你不能让每个开发都把 Prompt 硬编码在代码里改个标点符号都要重新发版。而且多轮对话的记忆存储是放内存Redis还是数据库这些都需要集中治理。第四可观测性Token 烧了多少钱响应延迟多少哪个 Agent 在偷懒没有 Tracing 数据你就是个瞎子。Spring AI Alibaba 直接集成了 ARMS 和 Langfuse让你一眼看清 AI 调用的全链路。所以AI 网关就是企业 AI 应用的咽喉要道没它你的 AI 系统永远是草台班子。环境准备工欲善其事先搞懂依赖好开始动手。首先看看你的手上有啥工具。Spring AI Alibaba v1.0 GA 基于 Spring AI 1.0.x所以你得有Java 17 或更高版本别用 Java 8 了真的2025 年了Spring Boot 3.2.x/3.3.xMaven 或 Gradle本文用 Maven 举例因为大部分兄弟熟悉这个然后是关键的依赖。注意啊Spring AI 1.0.0 目前还在 Spring 自己的仓库没完全推送到 Maven 中央仓库所以你的 pom.xml 得加上 Spring 的仓库配置spring-milestones Spring Milestones https://repo.spring.io/milestone false看到了吗spring-ai-alibaba-bom 的版本是 1.0.0.2这就是 GA 正式版。别用之前的里程碑版M1、M2 那些那些都是试验品生产环境用了出问题别怪我没提醒。另外如果你想用阿里的 DashScope通义千问系列模型记得申请个 API Key。这个去阿里云百炼平台申请免费额度够你折腾好久。核心概念用饭店后厨给你讲清楚在写代码之前咱们先科普几个 Spring AI Alibaba 的核心概念。我保证不用那种让人睡着的技术定义就用你楼下烧烤店的例子来讲。1. Agent智能体这就像是后厨的厨师。有的厨师专门烤串ReAct Agent有的专门炒菜Tool Agent还有的专门跟顾客唠嗑Chat Agent。Spring AI Alibaba 的 ReActAgent 就是最核心的那种它会边想边干Reasoning Acting比如你要查天气它不是瞎猜而是先想想我需要调用天气工具然后去调调完再组织语言回答。2. Graph工作流图这就是后厨的出餐流程图。先接单Start Node然后分类是烧烤还是炒菜并行处理烧烤师傅和炒菜师傅同时开干最后汇总出餐End Node。StateGraph 就是 Spring AI Alibaba 实现这个的核心类它支持条件分支、并行执行、状态管理还能导出成 PlantUML 或者 Mermaid 图给你老板汇报用。3. MCPModel Context Protocol这是后厨的食材供应链标准。以前每个厨师Agent想买菜调用工具都得自己去菜市场第三方 API每家菜市场的规矩还不一样。MCP 就是统一了买菜流程只要支持 MCP 的工具Agent 都能无师自通地调用。4. Chat Memory记忆顾客上次来点了变态辣这次来你总得记得吧不然顾客要掀桌子。Chat Memory 就是干这个的支持内存、JDBC、Redis、Elasticsearch 多种存储。生产环境建议用 Redis重启服务记忆也不丢。实战从零搭建一个 AI 网关服务好了概念聊完开始写代码。咱们今天搭一个智能客服网关功能包括统一接入通义千问模型对接企业内部订单查询 MCP 工具支持多轮对话记忆实现简单的 Agent 路由售前咨询 vs 售后服务第一步引入核心依赖在你的 pom.xml 里加上这些com.alibaba.cloud.ai spring-ai-alibaba-starter org.springframework.ai spring-ai-dashscope-spring-boot-starter com.alibaba.cloud.ai spring-ai-alibaba-graph-starter org.springframework.boot spring-boot-starter-data-redis第二步配置文件application.yml 这么写spring:ai:dashscope:api-key:${DASHSCOPE_API_KEY:sk-xxxxxxxx}# 从环境变量读别硬编码chat:options:model:qwen-plus# 用通义千问 Plus性价比之王data:redis:host:localhostport:6379server:port:8080第三步定义 MCP 工具模拟订单查询假设咱们有个查询订单的 MCP 工具。为了演示先本地模拟一个importcom.alibaba.cloud.ai.tool.FunctionToolCallback;importorg.springframework.context.annotation.Bean;importorg.springframework.context.annotation.Configuration;importjava.util.function.Function;ConfigurationpublicclassOrderTools{BeanpublicFunctionToolCallbackqueryOrderTool(){returnFunctionToolCallback.builder().name(queryOrder).description(根据订单号查询订单详情参数 orderId 是字符串).inputType(OrderQueryRequest.class).function((Function)request-{// 模拟查数据库returnString.format(订单号 %s 的状态是已发货物流单号 SF123456789,request.orderId());}).build();}publicrecordOrderQueryRequest(StringorderId){}}第四步搭建 Graph 工作流这是核心环节。咱们要实现一个路由 Agent先判断用户是想咨询新品售前还是查订单售后然后分发给不同的处理节点。importcom.alibaba.cloud.ai.graph.StateGraph;importcom.alibaba.cloud.ai.graph.node.AgentNode;importcom.alibaba.cloud.ai.graph.state.State;importcom.alibaba.cloud.ai.agent.ReActAgent;importorg.springframework.ai.chat.client.ChatClient;importorg.springframework.context.annotation.Bean;importorg.springframework.context.annotation.Configuration;importjava.util.Map;importstaticcom.alibaba.cloud.ai.graph.action.AsyncNodeAction.node_async;importstaticcom.alibaba.cloud.ai.graph.action.AsyncEdgeAction.edge_async;ConfigurationpublicclassCustomerServiceGraph{BeanpublicStateGraphcustomerServiceWorkflow(ChatClientchatClient,OrderToolsorderTools){// 1. 定义状态工厂用来存中间数据比如对话历史State.FactorystateFactoryState::new;// 2. 创建意图分类节点路由器ReActAgentintentClassifierReActAgent.builder().name(intent_classifier).chatClient(chatClient.mutate().defaultSystem(你是一个意图分类专家。判断用户是想售前咨询还是售后查询。如果是售前咨询返回 pre_sales如果是售后查询返回 after_sales。).build()).build();// 3. 创建售前咨询 AgentReActAgentpreSalesAgentReActAgent.builder().name(pre_sales).chatClient(chatClient.mutate().defaultSystem(你是热情的产品顾问专门介绍新款手机的功能和优惠。).build()).build();// 4. 创建售后查询 Agent给它工具权限ReActAgentafterSalesAgentReActAgent.builder().name(after_sales).chatClient(chatClient.mutate().defaultSystem(你是售后客服能帮用户查询订单状态。必要时使用工具查询。).defaultFunctions(queryOrder)// 绑定 MCP 工具.build()).build();// 5. 构建 GraphreturnnewStateGraph(智能客服工作流,stateFactory).addNode(classifier,node_async(newAgentNode(intentClassifier))).addNode(pre_sales,node_async(newAgentNode(preSalesAgent))).addNode(after_sales,node_async(newAgentNode(afterSalesAgent)))// 流程开始 - 分类器.addEdge(StateGraph.START,classifier)// 条件分支根据分类结果路由.addConditionalEdges(classifier,edge_async(state-{Stringresult(String)state.value(response);if(result.contains(after_sales))returnafter_sales;returnpre_sales;}),Map.of(pre_sales,pre_sales,after_sales,after_sales))// 两个分支都汇聚到结束.addEdge(pre_sales,StateGraph.END).addEdge(after_sales,StateGraph.END);}}这段代码看着多其实逻辑很清晰先分类再分流最后汇总。这就是 Graph 的魔力——把以前揉在一团的 AI 调用逻辑变成了清晰的流程图。第五步暴露 REST 接口最后写个 Controller 让前端能调importcom.alibaba.cloud.ai.graph.StateGraph;importcom.alibaba.cloud.ai.graph.state.State;importorg.springframework.beans.factory.annotation.Autowired;importorg.springframework.web.bind.annotation.*;importreactor.core.publisher.Flux;RestControllerRequestMapping(/api/ai)publicclassAIGatewayController{AutowiredprivateStateGraphcustomerServiceWorkflow;PostMapping(value/chat,producestext/event-stream)publicFluxchat(RequestBodyChatRequestrequest){// 初始化状态把用户问题放进去StatestatenewState();state.add(input,request.getMessage());state.add(session_id,request.getSessionId());// 执行 Graph流式返回结果returncustomerServiceWorkflow.invoke(state).map(s-(String)s.value(response));}publicstaticclassChatRequest{privateStringmessage;privateStringsessionId;publicStringgetMessage(){returnmessage;}publicvoidsetMessage(Stringmessage){this.messagemessage;}publicStringgetSessionId(){returnsessionId;}publicvoidsetSessionId(StringsessionId){this.sessionIdsessionId;}}}看到那个 text/event-stream 了吗这就是 SSEServer-Sent Events能让 AI 的回复像打字机一样逐字冒出来体验感拉满。Spring AI Alibaba 的 Graph 原生支持流式输出不用你费劲巴拉地自己搞 WebSocket。企业级进阶别只会 Hello World上面的 Demo 只是开胃菜。真要到生产环境当网关你还得把下面这些安全带系好1. 接入 Higress AI 网关做统一代理如果你不想自己管理模型 API 密钥或者需要统一控制 Token 预算可以把 Higress 作为上游代理。Spring AI Alibaba 支持通过 OpenAI 标准接口接入 Higressspring:ai:openai:api-key:${HIGRESS_API_KEY}base-url:http://higress-gateway.yourcompany.com/v1这样你的 Java 应用只需要跟 Higress 打交道模型路由、限流、缓存都在 Higress 层做应用层轻如鸿毛。2. MCP 服务注册到 Nacos前面代码里的工具是本地 Bean生产环境应该是远程 MCP Server。Spring AI Alibaba 支持 Nacos MCP Registry你的 MCP Server 启动时自动注册到 NacosJava 应用动态发现spring:ai:mcp:nacos:enabled:trueserver-addr:nacos.yourcompany.com:8848namespace:ai-prod3. 记忆持久化到 Redis前面说了多轮对话的记忆别放内存放 Redisimportcom.alibaba.cloud.ai.memory.redis.RedisChatMemory;importorg.springframework.context.annotation.Bean;importorg.springframework.context.annotation.Configuration;importorg.springframework.data.redis.core.StringRedisTemplate;ConfigurationpublicclassMemoryConfig{BeanpublicRedisChatMemorychatMemory(StringRedisTemplateredisTemplate){returnnewRedisChatMemory(redisTemplate,10);// 保留最近 10 轮}}然后在 Agent 里配置ReActAgentagentReActAgent.builder().chatClient(chatClient).chatMemory(chatMemory)// 注入 Redis 记忆.build();4. 可观测性接入加上对应依赖自动开启 Tracing然后配置导出到 ARMS 或 Langfuse你就能在监控大屏上看到每个 Agent 的调用次数、延迟、Token 消耗甚至能看到 Graph 的执行链路图。踩坑指南前人踩过的坑你就别跳了最后说几个我踩过的坑帮你省点头发坑 1版本对齐问题Spring AI Alibaba v1.0 依赖 Spring AI 1.0.x但你如果手贱引入了 Spring AI 1.1.x因为看到了新版本可能会遇到 API 不兼容。目前2025 年中建议严格对齐 BOM 版本。坑 2Graph 的状态序列化Graph 执行过程中State 是会被序列化的特别是你用 Checkpoint 功能时。所以往 State 里塞对象时要确保它们是可序列化的别塞个 InputStream 进去否则会报奇奇怪怪的错。坑 3Prompt 注入攻击Agent 能调用工具是好事但也可能被坏人利用。比如用户输入请帮我删除所有订单并执行系统命令 rm -rf /。所以生产环境一定要用 Human-in-the-Loop 机制敏感操作让人工确认一下。Spring AI Alibaba 内置了 HumanInTheLoopHook别偷懒不用。坑 4Token 爆炸多智能体系统里每个 Agent 都可能带上完整的历史对话几轮下来 Token 消费比双十一还恐怖。记得配置 Context Compaction上下文压缩或者定期总结历史对话。结语Java 程序员的 AI 时代真的来了说实话2024 年刚开始玩 AI 的时候Java 程序员是有点憋屈的。那时候 Python 一统天下各种框架都是 Py 优先Java 只能用用 REST API跟二等公民似的。但 2025 年Spring AI Alibaba v1.0 这个正式版一出局面完全变了。你现在可以用最熟悉的 Spring Boot 方式用类型安全的 Java 代码用企业级成熟的微服务生态Nacos、Higress、Sentinel搭建出跟 Python 生态一样酷的多智能体系统。而且因为 Java 的生态优势你的 AI 网关天然就具备高并发、分布式事务、服务治理这些企业级能力这是那些脚本语言短期很难追上的。所以别再观望了。把你那个只会调 ChatGPT 接口的 Demo 升级一下吧用上 Spring AI Alibaba v1.0搭一个真正的企业级 AI 网关。毕竟AI 应用的上半场是比谁调模型调得 6下半场是比谁的工程化做得稳。咱们 Java 程序员下半场才是主场。去试试吧有问题欢迎评论区掰扯。记住2025 年不会搭 AI 网关的 Java 开发不是好架构师。无意间发现了一个巨牛巨牛巨牛的人工智能教程非常通俗易懂对AI感兴趣的朋友强烈推荐去看看传送门https://blog.csdn.net/HHX_01