★ FEATURED ARTICLE Spring AI 1.x 用久了你会发现真正拉开模型输出效果差距的往往不是提示词模板本身而是 ChatOptions 里那些看起来不起眼的配置项。这个系列写到第 9 篇前几篇一直在聊 ChatClient 怎么写、Prompt 怎么组织、Advisor 怎么挂这篇专门把 ChatOptions 拎出来从接口设计、参数含义到全局配置与请求级覆盖的合并规则一次性讲透。刚上手 Spring AI 的同学建议重点看第 2 节和第 5 节会被很多隐蔽的坑救一把。1. ChatOptions 接口设计与核心定位1.1 从一个最简单的调用说起很多初学者第一次接触 ChatOptions其实是无意识的。写这样的代码时String answer chatClient.prompt(介绍一下 Spring AI) .options(OpenAiChatOptions.builder() .model(deepseek-chat) .temperature(0.3) .build()) .call() .content();.options()里的东西就是 ChatOptions。你再回头看看如果去掉这一行程序也能跑但最终请求到大模型服务端的参数就是一套默认值。默认值好不好用很多时候够用但真正要上线一个正经项目默认值几乎撑不住要么输出太长被截断要么回答太发散不合预期要么换了模型之后参数根本没有对齐。你可以把 ChatOptions 理解成“点菜单上的口味偏好”。Prompt 是你的菜模型是你的厨师而 ChatOptions 规定的是厨师怎么发挥火力大一点还是小一点装盘最多装多少哪一句话一出来马上停手。同一个 Prompt不同 Options产出的内容完全是两个风格。1.2 ChatOptions 接口到底定义了哪些东西Spring AI 1.x 里所有聊天模型的配置都抽象成了一个公共接口ChatOptions它位于spring-ai-model核心模块里。这个接口里的 getter 集合大致长这样public interface ChatOptions { String getModel(); Double getTemperature(); Double getTopP(); Integer getMaxTokens(); ListString getStop(); Double getPresencePenalty(); Double getFrequencyPenalty(); Integer getSeed(); // 部分版本还会有 stream、responseFormat、metadata 等扩展字段 }这里要注意一个关键点这些 getter 并不等同于“底层模型一定都支持”。它们只是 Spring AI 在框架层面定义的跨厂商通用参数。真正发送到各个模型服务端时由具体实现类把temperature翻译成temperature把maxTokens翻译成max_tokens或者max_completion_tokens。这层抽象最大的价值在于业务代码不依赖具体厂商。今天用 GPT 系的模型明天切到国产模型只要底层实现类适配得好你的ChatClient代码可以基本不动。我在项目中实际体会是它真正帮我省掉的是“每个接口厂商参数名不同要到处写 if else 转换”这种脏活。1.3 实现类看着多定位其实很清晰与ChatOptions接口对应的实现类有好几个DefaultChatOptions、OpenAiChatOptions、AnthropicChatOptions、OllamaChatOptions、QwenChatOptions等。如果你不做任何特殊设置Spring Boot 自动配置在创建ChatModel的时候会根据你引入的 starter 去构建对应类型的 Options 对象。这里有个常见误区很多人图省事直接用DefaultChatOptions.builder()生成一个通用配置塞给OpenAiChatModel。有的场景能跑通但遇到厂商专属参数就抓瞎。比如你想用 OpenAI 的response_format或者某些模型的topK通用实现类里根本没有这个字段最后还是得回来用OpenAiChatOptions或对应厂商的类。我的建议是大多数情况下不要自己手动 new 一个 Options也不要跨类型混用。用自动装配返回的ChatModel配合对应的XxxChatOptions.builder()来构建请求级配置才不容易出问题。2. 核心参数逐项拆解与建议取值2.1 搞懂 model、temperature、topP 到底在调什么model是这几个参数里最没有歧义的。它就是告诉模型服务端你要用哪个模型比如deepseek-chat、qwen-plus、gpt-4o。但有一点容易被忽略model只负责名字不负责路由地址。路由地址由baseUrl决定这部分通常在 ChatModel 或 starter 属性里配置不在 ChatOptions 里。所以当你换了一个服务商别只改 model 名字要确认baseUrl也跟着变了。temperature是控制随机性的核心参数OpenAI 系的取值范围是 0 到 2默认 0.7 左右。0 代表基本每次都挑概率最高的词适合代码生成、实体抽取、分类判定的场景2 代表极度放飞适合头脑风暴、文案发散。你可以把它理解成“厨师自由发挥的权限值”。参数值越高同一个人 Point 的确定性越低。topP是核采样参数含义是只在累计概率达到某个阈值的候选词里继续采样。取值范围 0 到 1默认 1。官方文档里通常补一句不要同时调整temperature和topP调其中一个就够了。原因也好理解这两个都是在改变下一个词的选择策略同时调等于同时踩油门和刹车。在实际项目中我常用这一套组合OpenAiChatOptions.builder() .model(deepseek-chat) .temperature(0.2) .build();如果任务是需要稳定输出的结构化文案我会让temperature尽量低如果是营销创意类我就调高temperature甚至把topP从默认 1 降到 0.95稍微收一下范围避免太离谱。2.2 maxTokens 与 maxCompletionTokens长度限制的大坑maxTokens通俗理解是“允许模型本次最多生成的 token 数”。它不等于请求的上下文长度。很多人以为设一个 8000 就万事大吉结果提示词本身已经占了 7000 token模型只剩下 1000 token 可生成输出一下就截断了。Spring AI 接口层统一叫getMaxTokens()但具体映射到厂商协议时会有差异。OpenAI 的老模型比如gpt-3.5-turbo支持的是max_tokens而新的 o1 系列模型要求使用max_completion_tokensgpt-4o在部分版本也建议使用新参数。如果你发现在请求某类模型时报了 400 错误提示信息里提到max_tokens is not supported基本都是这个参数翻译的问题。遇到这种报错不要慌先用日志看实际发出去了什么字段再对照模型文档调整。Spring AI 不同小版本对这两个字段的处理也有调整我在 1.0.0 系列里就碰到过同一个配置在某个模型上正常、换个模型就报错的情况最后是改用请求级 Options 手动指定底层字段解决的。建议的做法是先不设maxTokens用默认值跑一次看返回结果里的usage统计再根据实际输出长度做调整。这样比凭空猜一个数字靠谱得多。2.3 stop、presencePenalty、frequencyPenalty、seed用得好是神器stop是停止字符串列表。它的作用是告诉模型“看到这个标记就停”。比如你在做对话任务时希望模型不要输出多余的话可以设置[Observation:, ]之类的边界。注意不同模型对 stop 的支持不一致有的支持多个有的只支持一个有的根本不支持。如果你设置了 stop 但发现没生效先查模型文档再看请求日志里这个字段有没有被真正带过去。presencePenalty和frequencyPenalty都是对生成内容的惩罚项。presencePenalty惩罚“重复提及某个主题”frequencyPenalty惩罚“重复使用某个词”取值范围一般是 -2 到 2。配合使用可以缓解 AI 车轱辘话来回说的问题。不过国产模型中有一部分并不支持这些参数如果你发现带上去之后就报参数不存在直接忽略即可。seed是随机种子。固定 seed 理论上可以让输出更可复现但 OpenAI 官方也明确说过相同 seed 不保证完全一致只是尽力让结果更稳定。它适合用来做对照实验不适合作为生产环境的“确定性保证”。我自己在做 A/B 测试时会把 seed 固定下来至少便于排查是参数引起的差异还是随机波动。2.4 其他杂项stream、responseFormat 和 metadatastream这个字段在 ChatOptions 里偶尔会出现但我不建议你在 Options 里显式配置它。Spring AI 对流式调用有更清晰的方法级语义比如.stream()。如果你既在 Options 里设置了 stream又调用了.stream()有些实现会忽略 Options 里的这个值有些实现则会产生误导性的日志。与其踩这个坑不如把所有流量控制都交给 API 方法去表达。responseFormat是让模型返回结构化 JSON 的参数。在做实体抽取、信息解析这类任务时它非常关键。我在做数据标注类功能时会结合.entity(SomeClass.class)使用底层会自动帮我把响应格式和类型转换串起来。metadata主要用于透传一些框架级信息比如追踪 ID、业务标记。这部分数据不会原样发给模型服务端主要服务链路追踪和自定义处理逻辑。这里给一份常用参数速查方便做任务选型时参考参数典型默认推荐场景备注temperature0.70.1-0.3 代码/分类0.4-0.6 摘要0.7-1.0 创作部分模型范围只有 0-1topP1.00.8-0.95与 temperature 二选一maxTokens视实现根据上下文余量不是总上下文长度presencePenalty00-1 防重复主题模型不支持时忽略frequencyPenalty00-1 防重复词模型不支持时忽略seednull实验对比时固定不保证绝对复现responseFormatnull结构化输出时设置需要模型支持3. 全局默认与请求级覆盖的合并规则3.1 全局配置建议放在构建 ChatClient 的位置ChatOptions 的配置绝不只是写在每次请求里。更常见的是在创建ChatClient时设置一套全局默认值。比如ChatClient chatClient ChatClient.builder(chatModel) .defaultOptions(OpenAiChatOptions.builder() .model(deepseek-chat) .temperature(0.7) .maxTokens(2048) .build()) .build();这样所有通过该ChatClient发出去的请求在没有单独覆盖时都会带有 model 为deepseek-chat、temperature 为 0.7 的配置。如果整个应用的模型参数相对固定这套全局配置就是最好的兜底。另外Spring AI 的 starter 一般也支持通过application.yml配置全局参数。形如spring.ai.openai.chat.options.model、spring.ai.openai.chat.options.temperature之类具体前缀看你引入的 starter 以及版本。启动时看自动配置日志通常能直接看到它加载了哪些属性。这两种方式并不冲突ChatClient.Builder.defaultOptions()里的值会覆盖配置文件里的同名默认字段。3.2 请求级 options 如何优雅覆盖全局配置关键问题来了请求级.options()是全量替换还是字段级合并Spring AI 实际做的是字段级合并逻辑。框架拿到全局默认 Options 和请求传入的 Options 之后会以请求级为准但只覆盖那些非空字段请求级里没有显式设置的字段仍然回落到默认值。看个例子String result chatClient.prompt(把下面内容改成正式公文风格) .options(OpenAiChatOptions.builder() .temperature(0.1) .build()) .call() .content();这里只设置了 temperature那么 model 会继续使用全局的deepseek-chatmaxTokens 也会继续使用全局的 2048。这就是合并规则带来的便利局部关注差异全局负责兜底。我在实际项目里经常利用这个特性做多租户模型路由。不同租户使用不同模型时请求级只需覆盖 model 字段其他生成参数统一走全局配置代码非常清爽。3.3 常量配置与动态配置如何取舍有人问既然 ChatOptions 这么轻是不是每个请求都重新创建一个新对象从性能和设计角度我建议分情况。如果配置在业务层面是稳定不变的比如“所有客服摘要请求都用 temperature 0.1”那完全可以把这个 Options 定义成常量在多个调用点复用。比如private static final ChatOptions SUMMARY_OPTIONS OpenAiChatOptions.builder() .temperature(0.1) .maxTokens(512) .build();但如果配置依赖每次请求的特征比如根据用户输入内容判断是“创作模式”还是“事实问答模式”再动态设置不同的 temperature那就建议每次请求时构建一个新的 Options。ChatOptions 本身没有持久的可变状态每次用 builder 创建也没有可感知的性能开销。不要为了这种地方去做缓存过度设计反而会把代码搞乱。还有一个经验不要把业务判断逻辑散落在调用处用枚举维护几套预设 Options能让代码更好读。4. 两个可复制的实战配置模板4.1 用 OpenAI 兼容协议接 DeepSeek 系模型Spring AI 的 OpenAI starter 支持通过baseUrl指向任意兼容 OpenAI 协议的模型服务。DeepSeek 这类模型通常可以直接用这个方式接入。配置模板如下OpenAiChatOptions options OpenAiChatOptions.builder() .model(deepseek-chat) .temperature(0.2) .maxTokens(1024) .build();然后在application.yml中配置spring: ai: openai: base-url: https://api.deepseek.com/v1 api-key: ${DEEPSEEK_API_KEY}这属于“协议兼容”的接入方式好处是模型切换成本低坏处是你只能使用双方协议都支持的能力比如 responseFormat 这类结构化输出要看对方是否兼容。遇到参数不支持的情况完全可以再看模型自家的原生 SDK 风格是否更适合。4.2 用 DashScope 系配置对接千问模型如果使用的是阿里云百炼等提供 DashScope 协议的服务Spring AI 里有对应的 starter。构建 Options 找到的类名可能随版本略有不同有的叫QwenChatOptions有的叫DashScopeChatOptions。写法基本一致ChatOptions options DashScopeChatOptions.builder() .model(qwen-plus) .temperature(0.3) .maxTokens(1024) .build();这里我特别想说一下写之前先到 IDE 里看一眼你引入版本里的类名和包名。Spring AI 各子模块在不同小版本里调整过包名和上下文直接照旧博客的代码可能编译不过。但配置思维是通用的找到正确的 builder 之后model、temperature、maxTokens 这些东西大差不差。4.3 流式调用里 ChatOptions 还管用吗流式场景同样可以设置 ChatOptions。比如FluxString chunks chatClient.prompt(说一段冷笑话) .options(OpenAiChatOptions.builder() .temperature(0.9) .build()) .stream() .content();流式和非流式最终发送到模型服务端的参数体系是一样的区别只是返回方式不同。需要注意的是同一个 Options 对象不要在多路并发请求之间共享复用尤其是如果你的业务会基于请求上下文动态修改配置最好每个请求都从 builder 新建一份。虽然大多数实现是无状态的但流式订阅过程中线程模型比较复杂能避免的坑就尽量提前避免。5. ChatOptions 高频问题排查稳定复现的报错都有解5.1 请求级 options 不生效先检查合并逻辑遇到过好几次的现象是明明在.options()里设置了 model结果日志里请求还是用了另外一个模型。排查思路是先确认你构建请求 Options 的时候是不是直接把一个空对象传进去了。比如有人图方便先创建了一个OpenAiChatOptions.builder()不带任何字段然后业务里条件不满足时就不设置内容直接.build()此时它里面全是 null。请求级非空字段才覆盖全局所以空对象并不会覆盖任何东西看起来就像“完全没生效”。另一个隐蔽原因是类型不匹配。有的代码里方法参数类型写的是ChatOptions实际传入的却是DefaultChatOptions而底层 ChatModel 期望的是厂商自己的 Options 类型某些实现里会直接忽略不认识的对象。遇到这种情况把类型统一成OpenAiChatOptions或对应的厂商实现类问题就消失了。5.2 temperature 范围违例到底按谁的规矩最常见的报错是IllegalArgumentException: temperature must be between 0.0 and 2.0。这说明你已经超出 OpenAI 系的范围了。但有些模型平台标称的取值范围是 0 到 1甚至 0 到 1.5。取值范围是在 ChatOptions 构建时校验还是在服务端校验取决于实现。你只需要记住一条经验不要只看 Spring AI 接口的默认约束要看模型厂商文档里的有效范围。我遇到过最坑的情况是代码里合法但模型服务端拒绝了请求因为该模型只支持 0 到 1 的 temperature。这种问题日志里会带一个服务端返回的错误信息定位并不难难的是一开始没查文档。5.3 maxTokens 相关的问题大多是上下文理解错了如果模型回答到一半突然断了十有八九是maxTokens设置得太小剩下的输出空间不够。不要只看最终内容长度要结合模型的usage统计去看提示词本身占用的 token 也需要计入上下文。如果请求直接报 400提示max_tokens参数不被支持就去查你用的模型是不是要求max_completion_tokens。遇到这种情况可以通过修改 ChatOptions 里的底层扩展字段解决。Spring AI 不同版本对这两个参数的映射处理不同你可以先开启 DEBUG 日志查看实际发出的请求体把具体字段名看清楚再做调整。5.4 stop 参数不生效看清模型支持列表有的模型对 stop 的个数有限制有的模型根本不支持。你配置的 stop 字符串如果带有特殊语义但被模型转义了也会出现“该停的时候没停”的情况。我建议做结构化输出时不要只依赖 stop还要配合输出格式校验和重试机制。stop 更像一个性能优化手段保底逻辑仍然要放在代码层面。比如要求模型输出 JSON 时先设置responseFormat再做一次 JSON 解析校验解析失败就重试而不是傻等 stop 起作用。5.5 ChatOptions 调试技巧让日志说实话排查配置问题最有效的方法是看到 Spring AI 到底把哪些参数发给了模型服务端。最简单的方式是把请求日志级别调到 DEBUG观察 outgoing request 的 payload。如果日志没显示详细 body可以临时在拦截器里打印。我习惯在本地复现问题时把 ChatOptions 里所有字段直接 toString 打印出来确认全局和请求级合并之后的结果。很多时候“不生效”只是因为我们大脑里以为的配置值和实际值不一样。下面把高频问题整理成速查表方便直接对号入座现象可能原因解决思路options 看起来没生效请求级空对象或类型不匹配检查 Options 类型、检查非空字段合并逻辑temperature 异常超出厂商支持范围查模型文档按范围调整输出被截断maxTokens 与上下文余量不匹配看 usage 统计合理调整 maxTokens400 提示 max_tokens 问题模型要求新参数名查模型文档调整底层映射字段stop 不生效模型不支持或分隔符被转义简化 stop代码层做兜底校验流式调用偶发诡异复用了同一个 Options每请求独立构建 Options最后说一点我自己的使用习惯。ChatOptions 不要设置一次就再也不动它应该是你调优链路中的核心变量。我一般会把一套系统里的模型参数预设成几个枚举模板比如“严谨模式”“均衡模式”“创意模式”在业务代码里只决定用哪个模板具体的 temperature、maxTokens、seed 全封装在配置层。这样既不让参数散落在各个调用点也为后续灰度实验留有抓手。搞懂了 ChatOptions 的合并规则Spring AI 的配置体系你会觉得越用越顺手。
阅读完成 · 觉得有帮助？
