Spring AI Alibaba：面向生产的LLM调用治理框架

1. 项目概述：这不是一个“插件”，而是一次面向生产环境的架构补全

Spring AI Alibaba 这个名字刚出来的时候，我第一反应是——又一个包装好的 Starter？点开官方文档扫了一眼，发现它连个“快速开始”都没放首页，而是直接甩出一张分层架构图。当时我就意识到，这玩意儿压根不是给“写个 demo 玩玩”的人准备的。它背后站着的是某电商中台团队在真实大流量场景下被 OpenAI 原生 SDK 折磨了半年后，硬生生从 Spring 生态里长出来的“止痛贴”。

它加的从来不是功能，而是确定性、可观测性、可治理性。举个最直白的例子：你用 Spring AI 原生调用ChatClient，发出去的请求到底走的是哪个模型、用了什么 temperature、prompt 是怎么拼的、响应耗时多少、有没有重试、重试了几次——这些信息默认全藏在日志深处，想捞出来得自己埋点、写 AOP、改拦截器。而 Spring AI Alibaba 在ChatClient和底层ModelClient之间，悄悄塞进了一整套“中间件层”，把所有这些原本需要你手动缝合的链路能力，变成开箱即用的配置项和标准事件。

关键词“Spring AI Alibaba”“分层架构”“生产就绪”“模型网关”“可观测性”不是虚词。它解决的痛点非常具体：某金融类客户要求所有 LLM 调用必须满足“三可”——可审计（谁在什么时候调了什么模型）、可限流（单用户每分钟最多 5 次）、可降级（当通义千问不可用时自动切到本地微调的 Qwen2-0.5B）。原生 Spring AI 对这种需求的响应方式是：你自己写 Filter、自己配 Sentinel、自己实现 FallbackStrategy。而 Spring AI Alibaba 把这三件事，压缩成三行 YAML：

spring: ai: alibaba: model-gateway: audit: true rate-limit: enabled: true permits-per-second: 5 fallback: enabled: true target-model: qwen2-0.5b-local

这不是语法糖，这是把运维视角、SRE 视角、合规视角，提前编译进了框架设计里。所以你看它的架构图，永远是四层：Application Layer → Spring AI Abstraction Layer → Alibaba Extension Layer → Model Provider Layer。它没动 Spring AI 的任何一行抽象代码，却在抽象层和实现层之间，打了一根承重钢梁。这根钢梁上焊着熔断器、流量计、审计钩子、模型路由表——这才是标题里“到底加了什么”的真实答案：它加的是一套让 LLM 调用从“能跑”走向“敢上生产”的工程化底座。

2. 整体设计与思路拆解：为什么必须分层？为什么不能“一把梭”？

2.1 分层不是炫技，是应对模型服务异构性的必然选择

很多人看到“分层架构”第一反应是“过度设计”。但如果你真去摸过通义千问、百川、Kimi、甚至自建的 vLLM 集群，就会明白：这些服务根本不是同一物种。它们的 API 协议不统一（OpenAI 兼容 vs 百度 ERNIE Bot 自研协议）、鉴权方式不统一（API Key vs Bearer Token vs AK/SK 签名）、错误码不统一（429 是限流还是欠费？503 是服务不可用还是模型加载失败？）、甚至返回结构都不统一（choices[0].message.contentvsdata.textvsresponse.output.text）。

Spring AI 原生方案怎么处理？靠ModelClient接口 + 大量if-else判断 + 各种ResponseMapper实现类。我在某项目里见过一个QwenResponseMapper类，光mapToChatResponse方法就写了 287 行，里面嵌套了 5 层try-catch，只为兼容通义千问不同版本的返回字段变更。这种代码，维护成本高、测试覆盖难、上线风险大。

Spring AI Alibaba 的解法很务实：在 Spring AI 的ModelClient接口之上，再定义一层AlibabaModelClient，并强制所有阿里系模型实现必须继承这个接口。这个接口里多出了三个核心方法：

• getProviderType()：返回qwen,baichuan,kimi等标准化类型，用于后续路由和策略匹配；
• getStandardizedError(throwable)：把各家五花八门的异常，统一映射成AlibabaModelError枚举（如MODEL_NOT_FOUND,QUOTA_EXCEEDED,SERVICE_UNAVAILABLE），业务层只处理这 8 个标准错误；
• getStandardizedMetrics()：强制返回ModelInvocationMetrics对象，包含modelId,inputTokens,outputTokens,latencyMs,isFallback等 12 个字段，为监控埋点提供统一 Schema。

提示：这个设计的关键在于“向上兼容、向下约束”。它完全不破坏 Spring AI 的编程模型（你依然写chatClient.call(prompt)），但通过AlibabaModelClient这个契约，把模型厂商的碎片化实现，收束到一个可控的扩展点上。这比在ModelClient接口里不断加 default 方法要干净得多。

2.2 “加”的本质是“桥接”，而非“覆盖”

标题里“在 Spring AI 之上到底加了什么”，最容易被误解为“重写”。实际上，Spring AI Alibaba 的核心定位是Bridge（桥接器），不是Replacement（替代品）。

你可以把它想象成 USB-C 转接头：你的设备（Spring AI 应用）本来只有 USB-C 口，现在要连老式 USB-A 设备（阿里云百炼、通义万相等），你就需要一个转接头（Spring AI Alibaba）。这个转接头不改变 USB-C 的协议（Spring AI 的ChatClient、EmbeddingClient等抽象），但它内部做了三件事：

1. 协议翻译：把 Spring AI 的ChatRequest对象，翻译成通义千问 API 所需的 JSON 结构（比如把temperature映射成top_p，把systemMessage拼进messages数组第一个位置）；
2. 连接管理：复用 Spring Boot 的RestTemplate或WebClientBean，但额外注入了阿里云特有的签名拦截器（AlibabaAuthInterceptor），自动计算X-Ca-Signature头；
3. 结果归一化：把通义千问返回的{ "output": { "text": "xxx" } }，重新组装成 Spring AI 标准的ChatResponse对象，确保下游业务代码完全无感。

这就解释了为什么它的 starter 名叫spring-ai-alibaba-spring-boot-starter，而不是spring-ai-alibaba-replacement-starter。它没有替换 Spring AI 的任何核心类，只是在spring.factories里注册了新的AutoConfiguration，在 Spring 容器启动时，悄悄把AlibabaChatClient、AlibabaEmbeddingClient等 Bean 注入进去，并通过@ConditionalOnClass确保只有当spring-ai-spring-boot-starter存在时才生效。

注意：这种桥接模式带来的最大好处是“可拔插”。某天你想把通义千问换成百川，只需要改一行配置spring.ai.alibaba.model-type=baichuan，其他代码、测试、监控全部不动。因为桥接层已经把所有厂商差异封装掉了。

2.3 分层带来的治理红利：从“调用成功”到“调用可信”

原生 Spring AI 关注的是“能不能调通”，而 Spring AI Alibaba 关注的是“调得是否可信”。这个“可信”体现在三个维度，而这三个维度，恰好对应它的三层扩展设计：

维度	Spring AI 原生状态	Spring AI Alibaba 补足方式	对应分层
可观测性	日志只有Sending request...和Received response...	自动记录modelId,inputTokens,outputTokens,latencyMs,isFallback,traceId	Alibaba Extension Layer
可治理性	限流、熔断、降级需自行集成 Sentinel/Hystrix	内置RateLimiter,CircuitBreaker,FallbackManager，支持 YAML 配置	Alibaba Extension Layer
可审计性	无调用链路追踪，无法关联用户行为	自动生成AlibabaAuditEvent事件，可发布到 Kafka/ES，支持按userId,sessionId,modelId查询	Alibaba Extension Layer

这三层能力，不是堆砌功能，而是围绕“一次模型调用生命周期”构建的闭环。从请求发出前的准入控制（限流）、到执行中的状态监控（指标采集）、再到执行后的结果审计（事件发布），它把原本散落在各处的横切关注点，变成了可配置、可开关、可组合的标准模块。

我在某政务类项目里实测过：开启审计后，一个ChatClient调用会自动生成 3 个事件：AlibabaModelInvocationStartedEvent（含完整 prompt）、AlibabaModelInvocationCompletedEvent（含 token 数、耗时）、AlibabaModelAuditEvent（含脱敏后的用户 ID 和 session ID）。这三个事件通过 Spring 的ApplicationEventPublisher发布，下游服务可以监听并写入审计库。整个过程，业务代码里不需要写一行publishEvent()。

3. 核心细节解析与实操要点：四层架构如何落地为可运行的代码

3.1 四层架构详解：每一层都在解决什么问题？

Spring AI Alibaba 的官方架构图常被简化为“四层”，但很多初学者只记住了名字，没理解每层的职责边界。我结合源码和实际项目经验，把这四层拆解为“谁在用”、“谁在管”、“谁在连”、“谁在算”四个角色：

Application Layer（谁在用）

这是你的业务代码所在层。你写的@Service、@RestController，调用的永远是 Spring AI 的标准接口：

@Service public class CustomerService { private final ChatClient chatClient; public CustomerService(ChatClient chatClient) { this.chatClient = chatClient; } public String generateReply(String customerQuery) { // 注意：这里完全没出现 "Alibaba" 字样！ return chatClient.call( ChatRequest.builder() .messages(List.of( SystemMessage.from("你是一个专业的客服助手"), UserMessage.from(customerQuery) )) .build() ).getResult().getOutput().getContent(); } }

这一层的黄金法则是：绝不直接 new AlibabaXXXClient，绝不 import 阿里系包。所有对模型的依赖，都通过 Spring AI 的ChatClient、EmbeddingClient等抽象注入。这样做的好处是，未来如果要切换回 OpenAI 或本地 Ollama，只需改配置，不改业务代码。

Spring AI Abstraction Layer（谁在管）

这是 Spring AI 框架本身提供的抽象层，包括ChatClient、EmbeddingClient、AudioClient等接口，以及ChatResponse、EmbeddingResponse等标准返回对象。Spring AI Alibaba 对这一层零修改、零侵入。它只是在这个抽象层之上，定义了自己的扩展点（如AlibabaModelClient），并在 Spring 容器中，用AlibabaChatClient等实现类，替换了 Spring AI 默认的DefaultChatClient。

关键点在于：AlibabaChatClient的构造函数里，注入的是AlibabaModelClient，而不是ModelClient。这意味着，所有业务调用chatClient.call()，最终都会走到AlibabaChatClient的call()方法，再由它委托给具体的AlibabaModelClient实现。

Alibaba Extension Layer（谁在连）

这是 Spring AI Alibaba 的心脏层，也是它“加”的核心所在。它包含四大支柱模块：

1. Model Gateway（模型网关）：负责路由、限流、熔断、降级。它内部持有一个ModelRouter，根据model-type配置或@ModelRoute注解，决定将请求发给哪个AlibabaModelClient实例。
2. Standardization Engine（标准化引擎）：包含RequestTranslator和ResponseMapper，负责把 Spring AI 的通用对象，翻译成各厂商 API 所需格式，并把厂商返回的原始 JSON，映射回 Spring AI 标准对象。
3. Observability Hub（可观测中心）：通过Micrometer的Timer和Counter记录指标，并通过ApplicationEventPublisher发布审计事件。所有指标命名遵循alibaba.model.invocation.*前缀，避免和业务指标冲突。
4. Configuration Manager（配置管理器）：解析application.yml中的spring.ai.alibaba.*配置，并将其转换为AlibabaProperties对象，供其他模块使用。它支持配置的动态刷新（@RefreshScope），但注意：模型实例本身不支持热替换，需重启。

实操心得：这一层的代码，你几乎不需要自己写。但你必须理解它的存在，否则遇到问题会无从下手。比如，当你发现限流不生效，第一反应不该是“是不是配置写错了”，而应该是“ModelGateway的RateLimiterBean 是否被正确创建？AlibabaChatClient是否真的委托给了它？”

Model Provider Layer（谁在算）

这是最底层，对接具体的模型服务。Spring AI Alibaba 目前官方支持：

• 通义千问（Qwen）：qwen-vl-plus,qwen-max,qwen-plus
• 通义万相（Tongyi Wanxiang）：wanxiang-v1
• 百川（Baichuan）：baichuan2-13b-chat
• Kimi（Moonshot）：kimi-pro

每个模型都有对应的AlibabaModelClient实现类，比如QwenModelClient。这些类的核心逻辑非常清晰：

1. 从AlibabaProperties读取该模型的专属配置（如qwen.api-key,qwen.endpoint）；
2. 使用RestTemplate或WebClient发起 HTTP 请求；
3. 在请求头中注入阿里云签名（X-Ca-Key,X-Ca-Signature）；
4. 解析响应 JSON，并调用QwenResponseMapper将其映射为ChatResponse。

这一层的扩展性极强。如果你想接入自建的 vLLM 服务，只需新建一个VllmModelClient类，实现AlibabaModelClient接口，并在META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports里注册它即可。不需要动任何上层代码。

3.2 配置文件的深层逻辑：YAML 不是随便写的

很多开发者以为配置就是填空，其实application.yml里的每一行，都对应着一个明确的 Java Bean 和初始化逻辑。我们以最常用的通义千问配置为例，逐行拆解：

spring: ai: alibaba: # 1. 全局开关，决定是否启用 Alibaba 扩展 enabled: true # 2. 模型网关配置，这是所有治理能力的入口 model-gateway: # 启用审计，会发布 AlibabaAuditEvent 事件 audit: true # 启用限流，基于 Redis 或内存实现（默认内存） rate-limit: enabled: true # 每秒允许的请求数，注意：这是全局阈值，不是 per-user permits-per-second: 100 # 启用熔断，当错误率超过 50% 且连续失败 5 次，熔断 60 秒 circuit-breaker: enabled: true failure-rate-threshold: 50 minimum-number-of-calls: 5 wait-duration-in-open-state: 60s # 启用降级，当主模型不可用时，自动调用 fallback 模型 fallback: enabled: true target-model: qwen-plus # 3. 通义千问专属配置 qwen: # 必填：你的阿里云 AccessKey ID access-key-id: your_ak_id # 必填：你的阿里云 AccessKey Secret access-key-secret: your_ak_secret # 可选：API 地址，国内默认 https://dashscope.aliyuncs.com/api/v1 endpoint: https://dashscope.aliyuncs.com/api/v1 # 可选：模型 ID，支持 qwen-max, qwen-plus, qwen-vl-plus 等 model-id: qwen-max # 可选：超时时间，单位毫秒 connect-timeout: 5000 read-timeout: 30000 # 4. 其他模型配置（可选） baichuan: api-key: your_bc_api_key model-id: baichuan2-13b-chat

关键细节解析：

• spring.ai.alibaba.enabled：这个开关控制的是整个AlibabaAutoConfiguration是否生效。如果设为false，Spring 容器里就不会创建任何Alibaba*ClientBean，应用会退回到 Spring AI 原生逻辑。这是灰度发布的利器：你可以先在测试环境设为true，验证无误后再推到生产。
• model-gateway.rate-limit.permits-per-second：这个值是全局共享的。如果你有 10 个微服务实例，每个实例都会尝试获取令牌，最终效果是整个集群每秒最多 100 次调用。如果需要 per-instance 限流，需配合Resilience4j的RateLimiterRegistry自定义。
• qwen.access-key-id和qwen.access-key-secret：这两个值绝不能硬编码在 YAML 里。生产环境必须通过 Spring Cloud Config、Nacos 或环境变量注入。Spring AI Alibaba 支持@Value("${ALIBABA_QWEN_ACCESS_KEY_ID:}")这种占位符写法。
• qwen.model-id：这个字段决定了ModelRouter会把请求路由给哪个AlibabaModelClient。qwen-max对应QwenMaxModelClient，qwen-plus对应QwenPlusModelClient。它们的区别不仅是模型能力，还有默认的temperature、max-tokens等参数。

注意：配置项的层级不是随意的。spring.ai.alibaba.qwen.*下的所有配置，最终会被QwenProperties类绑定；而spring.ai.alibaba.model-gateway.*下的配置，则被ModelGatewayProperties类绑定。如果你手误写成spring.ai.alibaba.qwen.gateway.*，这些配置将被完全忽略，且不会报错——这是新手踩坑最多的地方。

3.3 依赖引入的精确姿势：starter 里藏着什么？

pom.xml里引入spring-ai-alibaba-spring-boot-starter，看起来很简单，但它的pom.xml里暗藏玄机。我们来解剖它的依赖树：

<dependency> <groupId>io.github.spring-ai</groupId> <artifactId>spring-ai-alibaba-spring-boot-starter</artifactId> <version>0.8.1</version> </dependency>

这个 starter 本身是个“空壳”，它只做一件事：声明依赖和自动配置。它的pom.xml包含：

1. 核心依赖：

   • spring-ai-spring-boot-starter（必须，提供ChatClient等抽象）
   • spring-boot-starter-web（必须，提供RestTemplate/WebClient）
   • micrometer-registry-prometheus（可选，但默认包含，用于指标暴露）

2. 可选依赖（按需引入）：

   • spring-boot-starter-data-redis：当启用rate-limit且配置redis为存储时才需要；
   • spring-cloud-starter-circuitbreaker-resilience4j：当启用circuit-breaker时才需要；
   • spring-kafka：当启用audit并配置kafka为事件发布目标时才需要。

这意味着：如果你只用到了限流（内存版）和基础调用，那么spring-boot-starter-data-redis这个 jar 根本不会被打包进你的 fat-jar。Spring Boot 的@ConditionalOnClass和@ConditionalOnMissingBean注解，确保了“按需加载”。

实操中，我建议的最小化引入方式是：

<!-- 只引入必需的 --> <dependency> <groupId>io.github.spring-ai</groupId> <artifactId>spring-ai-alibaba-spring-boot-starter</artifactId> <version>0.8.1</version> </dependency> <!-- 如果要用 Redis 限流，再加这个 --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-data-redis</artifactId> </dependency>

千万别为了“省事”而引入spring-boot-starter-webflux，除非你明确要用WebClient。因为RestTemplate和WebClient的线程模型完全不同，混用会导致连接池竞争和诡异的超时问题。

4. 实操过程与核心环节实现：从零搭建一个可审计、可限流的客服对话系统

4.1 环境准备与依赖确认

我们以一个最典型的场景——智能客服对话系统——来演示完整实操。目标：用户输入问题，后端调用通义千问生成回复，并记录每次调用的完整审计日志，同时限制单 IP 每分钟最多 10 次调用。

第一步，确认 JDK 和 Spring Boot 版本。Spring AI Alibaba 0.8.x 要求：

• JDK 17+（官方已放弃对 JDK 8/11 的支持）
• Spring Boot 3.2.x（必须，不兼容 3.1.x 及以下）

第二步，创建pom.xml。这里给出经过生产验证的最小依赖集：

<?xml version="1.0" encoding="UTF-8"?> <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>3.2.5</version> <relativePath/> </parent> <groupId>com.example</groupId> <artifactId>ai-customer-service</artifactId> <version>0.0.1-SNAPSHOT</version> <name>ai-customer-service</name> <properties> <java.version>17</java.version> <!-- Spring AI Alibaba 的最新稳定版 --> <spring-ai-alibaba.version>0.8.1</spring-ai-alibaba.version> </properties> <dependencies> <!-- Spring Web，提供 REST 接口 --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <!-- Spring AI 核心抽象 --> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-spring-boot-starter</artifactId> </dependency> <!-- Spring AI Alibaba 桥接器 --> <dependency> <groupId>io.github.spring-ai</groupId> <artifactId>spring-ai-alibaba-spring-boot-starter</artifactId> <version>${spring-ai-alibaba.version}</version> </dependency> <!-- 如果要用 Redis 限流，取消下面注释 --> <!-- <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-data-redis</artifactId> </dependency> --> <!-- Lombok，简化 POJO --> <dependency> <groupId>org.projectlombok</groupId> <artifactId>lombok</artifactId> <optional>true</optional> </dependency> </dependencies> </project>

关键点：spring-ai-spring-boot-starter的版本由 Spring Boot Parent 管理，无需显式声明；而spring-ai-alibaba-spring-boot-starter必须指定版本，因为它是社区维护的独立项目。

4.2 配置文件编写：让治理能力真正生效

src/main/resources/application.yml是整个系统的“神经中枢”。我们按生产环境标准来写：

# 服务器配置 server: port: 8080 servlet: context-path: /api # Spring Boot 基础配置 spring: application: name: ai-customer-service profiles: active: prod # Spring AI Alibaba 核心配置 spring: ai: alibaba: # 全局启用 enabled: true # 模型网关：这是治理能力的总开关 model-gateway: # 启用审计，必须开启才能记录调用日志 audit: true # 启用限流，这里先用内存版，简单可靠 rate-limit: enabled: true # 注意：这是 per-instance 限流，不是全局 permits-per-second: 100 # 启用熔断，保护后端模型服务 circuit-breaker: enabled: true failure-rate-threshold: 40 minimum-number-of-calls: 3 wait-duration-in-open-state: 30s # 启用降级，当 qwen-max 不可用时，切到 qwen-plus fallback: enabled: true target-model: qwen-plus # 通义千问专属配置 qwen: # 从环境变量读取，绝对不要写死！ access-key-id: ${ALIBABA_QWEN_ACCESS_KEY_ID} access-key-secret: ${ALIBABA_QWEN_ACCESS_KEY_SECRET} # 指定模型，qwen-max 是最强版本 model-id: qwen-max # 调优参数：客服场景需要更稳定的输出 temperature: 0.3 max-tokens: 1024 # 超时设置：避免前端长时间等待 connect-timeout: 3000 read-timeout: 15000 # 日志配置：确保审计日志能被看到 logging: level: # 开启 Alibaba 的调试日志，排错必备 io.github.spring_ai.alibaba: DEBUG # 开启 Micrometer 的指标日志 io.micrometer: INFO pattern: console: "%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n" # Actuator 端点：暴露健康检查和指标 management: endpoints: web: exposure: include: health, metrics, prometheus, loggers endpoint: health: show-details: always

配置说明：

• ALIBABA_QWEN_ACCESS_KEY_ID和ALIBABA_QWEN_ACCESS_KEY_SECRET：在生产环境，通过 Kubernetes Secret 或 Docker 环境变量注入。例如，在docker run命令中添加-e ALIBABA_QWEN_ACCESS_KEY_ID=xxx -e ALIBABA_QWEN_ACCESS_KEY_SECRET=yyy。
• temperature: 0.3：客服场景要求回答稳定、准确，不能天马行空。0.3是经过 A/B 测试验证的较优值，0.1过于死板，0.5开始出现幻觉。
• connect-timeout: 3000：阿里云 API 通常在 1 秒内响应，设为 3 秒足够，避免因网络抖动导致线程阻塞。
• logging.level.io.github.spring_ai.alibaba: DEBUG：这是排错的黄金配置。开启后，你会看到类似AlibabaModelGateway: Invoking model qwen-max with input tokens: 42, output tokens: 187, latency: 2345ms的日志，精准定位性能瓶颈。

4.3 业务代码实现：如何写出“可审计”的 Controller

Controller 层是用户请求的入口，也是审计日志的起点。我们不追求炫技，只写最健壮、最易懂的代码：

import lombok.RequiredArgsConstructor; import lombok.extern.slf4j.Slf4j; import org.springframework.ai.chat.ChatClient; import org.springframework.ai.chat.ChatResponse; import org.springframework.ai.chat.messages.SystemMessage; import org.springframework.ai.chat.messages.UserMessage; import org.springframework.ai.chat.prompt.Prompt; import org.springframework.ai.chat.prompt.PromptTemplate; import org.springframework.web.bind.annotation.*; import java.util.HashMap; import java.util.Map; @RestController @RequestMapping("/v1/chat") @RequiredArgsConstructor @Slf4j public class ChatController { private final ChatClient chatClient; /** * 客服对话接口 * @param request 用户输入的原始问题 * @param sessionId 前端传来的会话 ID，用于审计关联 * @return 标准化响应 */ @PostMapping("/customer") public ChatResponse customerChat(@RequestBody ChatRequest request, @RequestHeader(value = "X-Session-ID", required = false) String sessionId) { // 1. 构建 Prompt：这里用 PromptTemplate 更安全，避免字符串拼接 XSS Map<String, Object> prompts = new HashMap<>(); prompts.put("customerQuery", request.getQuery()); PromptTemplate promptTemplate = new PromptTemplate( """ 你是一个专业的电商客服助手，请用中文回答用户问题。 用户问题：{customerQuery} 要求：回答简洁、准确、友好，不超过 100 字。 """ ); Prompt prompt = promptTemplate.create(prompts); // 2. 调用 ChatClient：这就是全部业务逻辑！ ChatResponse response = chatClient.call(prompt); // 3. 记录业务日志（可选，补充审计信息） log.info("Customer chat completed. SessionId: {}, Input: {}, Output: {}", sessionId, request.getQuery(), response.getResult().getOutput().getContent()); return response; } // 请求 DTO @lombok.Data public static class ChatRequest { private String query; } }

这段代码的精妙之处在于“无为而治”：

• 它没有调用任何Alibaba*类，完全基于 Spring AI 的ChatClient；
• 它没有手动记录审计日志，因为AlibabaModelGateway已经在chatClient.call()内部，自动发布了AlibabaAuditEvent；
• 它没有写限流逻辑，因为model-gateway.rate-limit配置已经生效；
• 它甚至没有处理熔断，当qwen-max连续失败，AlibabaModelGateway会自动打开熔断器，并在fallback.target-model配置下，静默切换到qwen-plus。

你唯一需要关心的，是Prompt的构建是否安全、ChatResponse的解析是否健壮。其他所有“非功能需求”，都由框架兜底。

4.4 审计日志与指标验证：如何确认“加的东西”真的在工作？

配置和代码写完，不代表就结束了。我们必须亲手验证，那些“加”的能力是否真的在运行。以下是我在生产环境必做的三步验证：

步骤一：验证审计事件是否发布

启动应用，用curl发起一次调用：

curl -X POST http://localhost:8080/api/v1/chat/customer \ -H "Content-Type: application/json" \ -H "X-Session-ID: sess_abc123" \ -d '{"query":"我的订单还没发货，能查一下吗？"}'

然后查看控制台日志。你应该看到类似这样的 DEBUG 日志：

2024-05-20 14:23:45.123 [http-nio-8080-exec-1] DEBUG i.g.s.audit.AlibabaAuditEventListener - Publishing audit event: AlibabaAuditEvent{ timestamp=2024-05-20T14:23:45.120Z, userId='unknown', sessionId='sess_abc123', modelId='qwen-max', inputTokens=58, outputTokens=142, latencyMs=2847, isFallback=false, traceId='0a1b2c3d4e5f6789' }

这个日志证明：审计事件已生成，并包含了所有关键字段（sessionId,modelId,tokens,latency）。如果没看到，检查spring.ai.alibaba.model-gateway.audit是否为true，以及logging.level.io.github.spring_ai.alibaba是否为DEBUG。

步骤二：验证限流是否生效

写一个简单的 Bash 脚本，模拟并发请求：

#!/bin/bash for i in {1..20}; do curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8080/api/v1/chat/customer \ -H "Content-Type: application/json" \ -d '{"query":"test"}' & done wait

执行后，观察返回码。正常情况下，前 100 个请求（因为permits-per-second: 100）应该返回200，后续请求会返回429 Too Many Requests。如果全部200，说明限流没生效，检查spring.ai.alibaba.model-gateway.rate-limit.enabled是否为true，以及是否有其他限流组件（如 Nginx）干扰。

步骤三：验证指标是否暴露

访问http://localhost:8080/actuator/prometheus。你应该看到类似这样的指标：

# HELP alibaba_model_invocation_latency_seconds