Spring AI这个系列写到第九篇了。前面聊过ChatModel的调用流程、ChatClient的Prompt组装、结构化输出、Tool Calling这些偏“动作”的内容今天终于要把ChatOptions单独拎出来说透。很多人会把ChatOptions当做一个“配置文件里写几个参数就完事”的东西但实际上它在Spring AI 1.x里的位置相当于所有模型调用参数的“总闸口”——你写的模型名称、温度系数、最大输出token、停止序列、响应格式、工具选择策略最终都以ChatOptions对象的形式被传递到底层模型接口。你可以在启动时通过application.yml绑定一组默认值也可以在每次调用ChatClient时临时传入一个新的配置这些能力全部由这一层抽象承接。这篇就把ChatOptions的类结构、参数语义、不同模型提供方的差异、三种配置方式以及常见坑一次讲完。1. 先搞明白ChatOptions在Spring AI里到底扮演什么角色1.1 一个配置类凭什么值得单独写一篇你可能会想配置类有什么好讲的如果是用OpenAI官方的SDK不就是一个 request body 里几个字段吗但Spring AI做了个很关键的事它把“模型调用配置”抽象成了一个统一的接口ChatOptions。无论你后面接的是OpenAI、阿里百炼DashScope、Ollama、Azure OpenAI还是Google Gemini在你业务代码里面对的都是同一个接口。这就带来一个直接的好处——你的Service层代码可以完全跟某个具体的模型供应商解耦。举个例子我在做多模型路由的时候一套业务代码既可以去调GPT也可以去调qwen只需要在配置中心切换不同的实现Bean。如果没有这层抽象你就得在业务代码里针对每家SDK写一套参数对象那代码丑得根本没法维护。Spring AI 1.x的做法是ChatOptions是一个顶层接口各家提供方各自实现比如OpenAiChatOptions、DashScopeChatOptions、OllamaChatOptions。它们都承诺实现统一的方法比如getModel()、getTemperature()、getMaxTokens()但又各有自己的扩展字段。另一个容易被忽略的点ChatOptions对象是不可变的immutable。它内部没有给你留一堆setter而是通过Builder模式和with...系列方法来生成新对象。很多人第一次看源码会很不习惯问“为什么不能直接改temperature”因为模型配置在并发场景下如果可变一个请求改一个值全局全乱了。所以Spring AI用不可变对象保证线程安全这跟Java里String不可变是同一个思路——配置一旦构建完成你只能基于它复制出一个新的不能就地修改。1.2 全局配置、Bean注入、调用传参三条路怎么选在Spring AI 1.x里ChatOptions的使用方式大体有三条路第一条是全局配置。你在application.yml里写spring: ai: openai: chat: options: model: gpt-4o-mini temperature: 0.7 max-tokens: 1024启动时Spring Boot的自动配置会把这些值读进去生成一个默认的OpenAiChatOptions注入到OpenAiChatModel里。这样你平时调用chatModel.call(prompt)的时候不用传任何options底层就用这组默认值。第二条是定义Bean。你可以在配置类里显式声明Bean ChatOptions briefChatOptions() { return OpenAiChatOptions.builder() .model(gpt-4o-mini) .temperature(0.2) .maxTokens(512) .build(); }然后在需要的地方注入这个Bean或者配合Qualifier在不同场景下选择不同配置。第三条是调用时动态传参。ChatClient支持在每次请求时传入临时optionsString result chatClient.prompt() .options(OpenAiChatOptions.builder() .model(gpt-4o) .temperature(1.3) .maxTokens(2048) .build()) .user(写一段有创意的广告文案) .call() .content();这三条路没有谁绝对更好而是取决于你的场景。全局配置适合“一个项目只用一组默认参数”的简单需求Bean定义适合“多语言、多场景需要用不同参数”的中型项目动态传参适合做Agent、工作流这类每次调用参数都不同、交互密集的场景。需要注意的是调用时传入的options会覆盖全局默认值并且它不是做合并而是整体替换。也就是说你在全局配置里设置了stop序列但调用时传了一个没有stop的新options那这次调用就没有stop这在后面排查问题时会是一个大坑。2. 常用参数逐个拆参数名背后的真实含义2.1 model、temperature、topP先搞定这“老三样”先说model。这是所有ChatOptions里一定存在的字段它的值就是模型提供方的模型标识比如gpt-4o、qwen-plus、deepseek-chat、llama3.1。有一点要注意model字段只要不设置很多实现类会默认用一个型号。比如OpenAiChatOptions默认是gpt-4o会跟随Spring AI版本变化DashScopeChatOptions默认可能是qwen-plus。这种隐式默认值有个隐患——你切到某个私有化部署的模型网关时如果忘了显式设置model它照样去请求默认模型表现就是“我明明配置了网关地址为什么报模型不存在”所以生产环境我建议所有options都显式指定model。然后说temperature。这应该算新手最容易“凭感觉填”的参数。它的作用是控制生成结果的随机性。OpenAI的定义里temperature范围是0到2值越低输出越确定、越保守适合分类、抽取、翻译这类需要“稳定答案”的任务值越高输出越发散、越有想象力适合头脑风暴、文案润色。我自己的经验是在做信息抽取、实体识别这类需要格式稳定的场景temperature直接设0甚至可以把topP也设成0做续写、创意文案时温度放到0.7到0.9区间超过1.0之后输出质量下降很快经常会出现逻辑跳跃。不要指望把temperature调高就能让模型“变聪明”它提升的是随机性不是智力。topP这个参数全称是nucleus sampling核采样。模型生成每个token时会算出一个概率分布topP0.9的意思是从概率累计达到90%的最小token集合里采样。官方文档一般建议temperature和topP只用其中一个——如果两个都调模型的输出会同时被两套采样策略约束结果容易不稳定。实际经验是改temperature比较直观所以我一般优先用temperaturetopP保持默认1.0不动。2.2 token限制与输出控制参数maxTokens作用于“新生成的token数量上限”注意它不等于“上下文总长度”。很多人误以为maxTokens是整段对话的token预算结果写代码时设置了maxTokens512但请求的上下文已经有4000多token生成200多个token就被截断了——这其实是正常行为因为输入长度和输出长度是分开计费的。真正控制上下文总长度的是模型自身的context window比如gpt-4o是128k你需要在组装Prompt时自己控制历史消息的长度。Spring AI 1.x里OpenAI的实现类同时提供了maxTokens和maxCompletionTokens两个字段。前者主要是为了兼容老接口后者在OpenAI最新的Responses API里更精确。如果两个都设置了OpenAI那边会以maxCompletionTokens为准。Ollama的实现里叫numPredict它和OpenAI的maxTokens对应。这里特别提醒在Spring AI里切模型提供方后参数的含义并不完全等价要从OpenAI切到Ollama时不要只改依赖和配置地址还要逐个检查options里的字段对不对得上。stop参数也值得讲一下。它是一个字符串数组告诉模型生成到这些序列时就停止。比如OpenAI的API支持stop: [END]你可以在Prompt末尾约定“回答完请输出END”然后模型输出到END就会停下。但在Spring AI 1.x里你把它写进OpenAiChatOptions.builder().stop(List.of(END))就可以了。实际用途一个是配合Agent的固定动作输出另一个是防止模型输出多余的客套话——比如你只想要一个JSON它每次非要在结尾加一句“以上是生成的结果”你就可以把这句话加入stop序列。2.3 结构化输出与工具调用的配置入口模型调用的配置不只影响“生成风格”还决定“以什么形式返回结果”。Spring AI里做JSON Schema约束时responseFormat是不可或缺的一个字段。在OpenAiChatOptions里你可以这样写OpenAiChatOptions options OpenAiChatOptions.builder() .model(gpt-4o-2024-08-06) .responseFormat(ResponseFormat.builder() .type(ResponseFormat.Type.JSON_SCHEMA) .jsonSchema(JsonSchema.builder() .name(MovieInfo) .schema(Map.of( type, object, properties, Map.of( title, Map.of(type, string), score, Map.of(type, number) ), required, List.of(title, score) )) .strict(true) .build()) .build()) .build();这里有个官方文档里不太点名讲的事JSON_SCHEMA模式并不是所有模型都支持。OpenAI的gpt-4o-2024-08-06之后的版本支持得比较好但旧版或第三方兼容接口经常直接忽略掉responseFormat字段。表现就是调用不报错但返回的是普通文本而不是结构化结果。排查的时候第一件事就是确认上游模型是否真的支持。DashScopeChatOptions也有responseFormat字段但实际可用参数和JSON Schema的支持程度又不完全相同所以尽量不要跨提供方直接复用同一个options配置。工具调用方面toolChoice也是一个配置项用来控制模型是否必须调用某个工具。Spring AI 1.x的工具调用默认是自动判断的模型可以决定调或者不调。但有些场景比如解析用户意图后强制走某条流程你需要设toolChoice为指定的函数名。OpenAiChatOptions里可以用toolChoice(OpenAiApiFunctionToolChoice.required(xxx))这样的方式指定。在1.x里toolChoice的类型是String你传auto、none或指定的函数名都可以。它的语义各家也略有不同最佳实践还是对照你对接的那一家API文档来设置。3. 不同模型提供方ChatOptions的“同与不同”3.1 OpenAiChatOptions的完整面貌Spring AI的OpenAI实现类OpenAiChatOptions是字段最齐全的一个几乎把OpenAI官方Chat Completion参数都映射了一遍。除了前面提到的model、temperature、topP、maxTokens、stop、responseFormat还有presencePenalty、frequencyPenalty、seed、user、logitBias、functions、toolCallbacks、toolChoice、modalities、audio这些。presencePenalty和frequencyPenalty是个容易搞混的点。presencePenalty惩罚“话题是否出现过”——值越大模型越倾向于谈论新话题避免重复提及同样内容frequencyPenalty惩罚的是“token出现的频率”——值越大模型越会避免重复使用同一个词。实际项目里我很少同时调high两个参数因为它们的共同结果都是抑制重复只是作用维度不同。OpenAI给的推荐范围是-2.0到2.0但多数情况下-0.5到1.0之间就够用了。seed参数用来做可复现生成但我不建议对它有太高期待。OpenAI官方说明里相同seed可以尽量让输出可复现但不保证100%一致因为模型状态还会受到采样、并发等因素影响。logitBias一般用到它的工程很少它是一个“词汇表token级别”的倾向调整演进到Spring AI里需要自己处理tokenizer映射实用性不强。3.2 阿里百炼DashScope与国内大模型的配置差异国内用的比较多的阿里百炼DashScope它的DashScopeChatOptions整体结构和OpenAI类似但有一些自己的特色字段。在Spring AI 1.x里它支持enableSearch用来开启模型联网搜索。这个字段在OpenAI的实现里没有等于模型可以结合实时搜索结果生成答案。实际用起来效果依赖模型本身qwen的搜索增强能力在“查询最新信息”时很有用比如让它查当天的新闻但代价是响应时间变长、token消耗增加。另外一个差异比较大的点部分qwen系列模型支持enableThinking走的是DeepSeek R1那种思考链模式。如果你在DashScope上调用qwen3或者带思考模式的模型Spring AI 1.x的DashScopeChatOptions里会暴露相关字段。这里踩过坑的人都知道开启思考模式后模型返回的结构里会出现reasoning_content而Spring AI封装时如果没把这部分单独处理会把思考内容也拼到最终输出里表现为“回答前面多了一段推理过程”。依赖版本较老时这个问题比较常见升级版本后通常会把reasoning_content单独剥离。还有一个易错点是温度范围。OpenAI传2.0没问题但qwen系列有些模型接口的temperature只支持到1.0超了会报参数校验错误或者静默截断到最大值。所以如果你有一套配置从OpenAI切到百炼最好把temperature检查一遍不要原样复制。3.3 本地模型Ollama与线上模型的参数差异Ollama在Spring AI 1.x里的实现类是OllamaChatOptions。本地模型的参数语义跟线上模型不一样的地方很多。temperature在Ollama里同样是0到2但很多开源模型的推荐调法是低温加高topP的组合而不是只动temperature。OllamaChatOptions还有topK这个参数它表示“只从概率最高的K个token中采样”。topK设为10、topP设为0.9、temperature设置为0.7这类组合在本地模型上比单独调temperature控制力更强。另外一个很实际的差异是本地模型对工具调用和结构化输出的支持参差不齐。你拿一个7B的小模型让Ollama绑定工具模型可能频繁输出无效的JSON或者直接忽略tool call。这不是Spring AI的问题是模型能力上限。所以生产环境用Ollama做工具调用时最好在options里设置较大的numPredict让模型有充足的生成空间否则模型在生成工具参数过程中token不够直接截断成一个残缺JSON调用直接失败。各家options字段对比如下参数OpenAiChatOptionsDashScopeChatOptionsOllamaChatOptionsmodel✔✔✔temperature✔ 0~2✔ 多数0~1✔ 0~2topP✔✔✔maxTokens✔✔用numPredictstop✔✔✔responseFormat✔ JSON Schema✔ 部分支持支持有限seed✔部分模型支持✔联网搜索不支持专项字段enableSearch不支持思考模式不支持enableThinking不支持4. 实操三种构建ChatOptions的方式与选择建议4.1 属性文件全局绑定最简单也最容易踩坑Spring Boot的自动配置让你可以在配置文件里直接声明ChatOptions。以OpenAI为例spring: ai: openai: base-url: https://xxx api-key: ${OPENAI_API_KEY} chat: options: model: gpt-4o-mini temperature: 0.6 max-tokens: 1024 stop: - END response-format: type: json_schema json-schema: name: Movie schema: type: object properties: title: type: string score: type: number required: - title - score strict: true这里有一个新手必踩的坑response-format在YAML里的连字符命名。Spring Boot的Relaxed Binding会把配置文件里的response-format映射到OpenAiChatOptions的responseFormat字段。此处的json-schema字段名映射类似。如果你写成responseFormat在使用ConfigurationProperties绑定的某些场景下可能映射不上用连字符比较稳妥。我平时并不太建议把复杂配置全部写进YAML。原因有两个第一YAML里写复杂的嵌套Map结构可读性很差尤其有多层嵌套的时候改一个字段来回对缩进第二配置文件无法做到条件逻辑比如“不同用户组用不同temperature”这种需求你没法在YAML里表达。它只适合做“项目级默认值”。实际项目里我会把YAML里的options收敛到只剩model、temperature、maxTokens这类简单参数复杂参数统一放代码构建。4.2 Bean定义多组配置按场景注入更灵活当你需要按不同业务场景用不同配置时Bean是更清晰的方式。比如我可以一次性定义三组一组用来做信息抽取温度极低、输出格式固定一组用来做创意生成温度高一些一组用来做对话总结token限制严格。Configuration public class ChatOptionsConfig { Bean Qualifier(extractOptions) public ChatOptions extractOptions() { return OpenAiChatOptions.builder() .model(gpt-4o-mini) .temperature(0.0) .maxTokens(1024) .responseFormat(ResponseFormat.builder() .type(ResponseFormat.Type.JSON_OBJECT) .build()) .build(); } Bean Qualifier(creativeOptions) public ChatOptions creativeOptions() { return OpenAiChatOptions.builder() .model(gpt-4o) .temperature(1.0) .maxTokens(2048) .build(); } Bean Qualifier(summaryOptions) public ChatOptions summaryOptions() { return OpenAiChatOptions.builder() .model(gpt-4o-mini) .temperature(0.3) .maxTokens(512) .build(); } }使用的时候在Service里按需选择Service public class AiService { private final ChatClient chatClient; public AiService(ChatClient.Builder builder, Qualifier(extractOptions) ChatOptions extractOptions) { this.chatClient builder .defaultOptions(extractOptions) .build(); } }这种方式的可读性比在YAML里堆一大堆配置高很多而且每个Bean都有明确的名字作用一看就知道。唯一的缺点是每次新增场景都要新加一个Bean方法业务量大时会显得类比较臃肿。但相比在XML里拼参数这已经是比较可控的方案了。4.3 调用时动态传参适合Agent与工作流做Agent或者工作流的时候每个节点可能需要完全不同的参数。比如“意图识别节点”用低温、固定model“内容生成节点”用高温、更大的maxTokens。这种场景就不适合用一个全局默认options了而是每次调用都传入新的options。ChatOptions intentOptions OpenAiChatOptions.builder() .model(gpt-4o-mini) .temperature(0) .responseFormat(ResponseFormat.builder() .type(ResponseFormat.Type.JSON_OBJECT) .build()) .build(); ChatOptions contentOptions OpenAiChatOptions.builder() .model(gpt-4o) .temperature(0.9) .maxTokens(4096) .build(); String intentJson chatClient.prompt() .options(intentOptions) .user(用户说我要订明天去北京的机票) .call() .content(); String content chatClient.prompt() .options(contentOptions) .user(根据以上意图生成订单确认文案) .call() .content();这里有一个Spring AI 1.x容易混淆的点ChatClient的defaultOptions和prompt.options的关系。defaultOptions是你在构建ChatClient时指定的相当于客户端级默认值prompt.options是每次请求时指定的。请求时传入的options优先级更高并且是“后者完全覆盖前者”而不是合并。也就是说如果默认options里有stop而请求时传入的options没有stop这次请求就不会带stop参数模型就会一直生成到你设的maxTokens为止。从1.x开始OpenAiChatOptions提供了不少copy()和with...方法例如OpenAiChatOptions base OpenAiChatOptions.builder().model(gpt-4o).temperature(0.7).build(); OpenAiChatOptions override (OpenAiChatOptions) OpenAiChatOptions.builder() .temperature(0.1) .build();但要注意这种方式并不能让override自动继承base的属性。如果你想基于一套基础配置做微调最稳的思路是先把基础配置的每个字段读出来重新构建OpenAiChatOptions dynamicOptions OpenAiChatOptions.builder() .model(base.getModel()) .temperature(0.1) .maxTokens(base.getMaxTokens()) .stop(base.getStop()) .build();这样虽然写起来啰嗦但至少不会因为字段合并逻辑不清导致参数丢失。5. 常见问题与排查技巧实录5.1 配置了没生效先按这个顺序排查ChatOptions最常见的故障就是“我明明配置了temperature为什么模型输出完全没变化”。遇到这种问题我建议按以下顺序排查第一确认调用请求有没有被上层覆盖。先检查ChatClient构建时的defaultOptions再检查调用的.options()。很多时候你全局配置了0.2但代码里某处調了一次prompt.options(builder().build())虽然没写temperature但整个options已经被替换成“无temperature状态”了。可以临时在请求前打印一下最终options的toString看参数到底传了什么。第二确认模型提供方是不是真的支持这个参数。比如responseFormat在Ollama的小模型上很可能就是静默忽略seed在部分API上也不生效enableThinking只对qwen的特定模型有效。这类“不报错但不生效”的问题只能通过查上游API的调用日志来确认。第三排查参数值本身有没有落到合理范围之外。temperature如果传0.0输出会是非常确定的但如果你任务本身需要一定的表达变化0.0会显得像“没生效”同样maxTokens设成远低于实际输出长度的值你会看到结果总是被硬生生截断很多人会误以为“设置没生效”。5.2 输出被截断不一定是maxTokens的锅我见过好几个项目反馈“模型回答到一半就断了”第一反应都是把maxTokens调大但有时候调大根本没用。除了maxTokens之外还有一个隐藏杀手是stop序列。如果你设置了stop: [\n]模型每次生成到换行符就会停结果就是每个回答只有一行看起来极其像被截断。排查方法很简单把stop临时清掉再调一次看输出是否变完整。另外一个容易被忽略的点是prompt模板里写了“请控制在xx字以内”模型可能严格遵守生成到指定长度就换行结束。这种情况加maxTokens没用要调整提示词。还有一个情况是某些模型服务端有额外的“输出长度上限”比如某些qwen系列版本服务端强制max_tokens最大4096但Spring AI没做本地校验你传8192它也不报错到服务端被截断。这种只能查服务端返回的finish_reason如果显示length那就是token限制导致的。5.3 结构化输出失败多半是模型不支持用responseFormat限制JSON输出时有一个高频问题Spring AI返回的结果是一段普通的markdown文本里面包着json代码块而不是纯JSON。这常见于两种情况。一种是你只配了type: JSON_OBJECT但模型版本不支持或调用方式不对。OpenAI的json_object模式要求在Prompt里明确出现“json”这个单词否则模型不会输出JSON。Spring AI不会自动帮你往Prompt里塞这个提示词所以你需要在用户消息模板里带上“请以JSON格式输出”之类的指令。另一种是配了JSON_SCHEMA但模型不严格校验。OpenAI的strict模型下输出非法JSON会报错或反复重试但很多第三方服务商兼容层并不严格实现strict语义该返回纯文本还是返回纯文本。我的经验是结构化输出不能只依赖responseFormat业务代码里一定要加一层兜底解析逻辑。如果返回内容没有被正确解析成JSON不要直接抛异常而是尝试提取其中的JSON片段再解析一次或者给模型一次“修正输出格式”的额外机会。5.4 从one provider切到另一个时参数“悄悄失效”多模型切换是Spring AI的卖点但也是配置事故的高发区。你从OpenAiChatOptions切到DashScopeChatOptions代码层面通常只需要改Bean类型但参数层面的细节特别多。举几个实际遇到的maxTokens字段两边都有但百炼部分模型服务端会额外要求maxTokens必须不小于某些值设小了直接报400。responseFormat在两边结构差异大从OpenAI的JSON_SCHEMA迁到百炼时需要改用DashScopeChatOptions里对应的枚举或结构。temperature取值范围不一致OpenAI允许到2百炼许多模型最大1传1.5会被拒绝。stop两边都能传但分隔符处理规则可能不同同一个stop序列在一个侧生效、另一个侧完全不生效。所以我在做多模型项目时通常会封装一层“业务参数对象”把业务上的“创造性程度”“输出长度级别”“是否强制JSON”映射成具体模型的options而不是直接把厂商options散落到Service里。6. 关于Spring AI版本演进的一点提醒6.1 1.x到2.0ChatOptions发生了什么变化写这篇文章时Spring AI已经发布了2.x版本很多人在从1.x往2.0迁移这个过程里ChatOptions的变化值得专门提醒。在1.x里ChatOptions接口位于org.springframework.ai.chat包下各家实现会比较散到了2.0整个模块结构做了大调整ChatOptions、模型客户端相关的包路径发生了变化同时ChatClient的API也有不小的改动。这意味着你从1.x升级到2.0原本写的OpenAiChatOptions.builder()这类代码一定会有编译错误不是换个版本号就能直接跑的。我个人的建议是如果项目已经上线稳定运行不要为追新而盲目升级到2.0。2.x的API设计更干净、抽象更彻底但迁移成本要预算进去尤其是有大量动态构造options的代码那些with...方法、ResponseFormat构建逻辑都要逐个改。反过来如果你是用Spring AI 1.x系列刚起的项目配套教程也比较多直接按1.x学起来更容易。如果想了解2.0可以单独打开对应的release note系统性迁移不要指望一个类名映射表就能无痛切换。6.2 多模型多场景配置的组织心得最后分享一点我实际项目的组织习惯。我会用一个小工具类把“业务场景”和“ChatOptions”做映射而不是在每个Service里零散地new optionspublic enum AiScenario { EXTRACT, CREATIVE, SUMMARY, AGENT_TOOL } Component public class ChatOptionsFactory { private final MapAiScenario, ChatOptions optionsMap new HashMap(); public ChatOptionsFactory() { optionsMap.put(AiScenario.EXTRACT, OpenAiChatOptions.builder() .model(gpt-4o-mini).temperature(0.0) .responseFormat(ResponseFormat.builder().type(ResponseFormat.Type.JSON_OBJECT).build()) .build()); optionsMap.put(AiScenario.CREATIVE, OpenAiChatOptions.builder() .model(gpt-4o).temperature(1.0).maxTokens(4096).build()); // ... 更多场景 } public ChatOptions forScenario(AiScenario scenario) { return optionsMap.get(scenario); } }这样业务代码调用时就只需要说一句“我这个场景要走CREATIVE策略”配置全收敛到一个工厂里排查配置问题只看一个类就行了。写到这里ChatOptions在Spring AI 1.x里的定位、参数细节、不同实现差异和几种配置方式都过了一遍。这个东西技术难度不高但它属于那种“不仔细研究就会在运行环境里给你上眼药”的类型。我自己的经验是把options的构建代码尽可能集中管理调试时开一个会打印完整options请求体的日志遇到参数不生效先查覆盖关系再查模型能力绝大多数问题都能在十分钟内定位。