Spring AI 1.x 系列【9】ChatOptions 配置解析

文章目录

[1. 概述](#1. 概述)
[2. ModelOptions API](#2. ModelOptions API)
- [2.1 继承关系](#2.1 继承关系)
- [2.2 创建对象](#2.2 创建对象)
[3. 智谱 AI](#3. 智谱 AI)
- [3.1 发展历程](#3.1 发展历程)
- [3.2 智谱大模型平台](#3.2 智谱大模型平台)
- [3.3 对话补全 API 文档](#3.3 对话补全 API 文档)
[4. 案例演示](#4. 案例演示)
- [4.1 默认配置项](#4.1 默认配置项)
- [4.2 全局默认](#4.2 全局默认)
- [4.3 单次请求配置](#4.3 单次请求配置)
- [4.4 深度思考](#4.4 深度思考)
- - [4.4.1 大模型支持](#4.4.1 大模型支持)
  - [4.4.2 全局关闭](#4.4.2 全局关闭)
  - [4.4.3 动态传参](#4.4.3 动态传参)
  - [4.4.4 验证](#4.4.4 验证)

1. 概述

在发起请求与大模型交互时，可以配置各类核心参数，以此控制模型的生成行为、回复长度、随机性等关键特性。

大白话：大模型的请求参数。

2. ModelOptions API

ModelOptions 是 Spring AI 框架中所有模型配置项的「根接口」，它定义了所有 AI 模型（不管是聊天模型、文本生成模型、嵌入模型）配置参数的通用规范。

2.1 继承关系

ChatOptions 继承了 ModelOptions 表示对话模型相关配置：

java 复制代码

public interface ChatOptions extends ModelOptions {

    /**
     * 获取要调用的大模型名称/版本
     */
    String getModel();

    /**
     * 获取频率惩罚系数（Frequency Penalty）
     */
    Float getFrequencyPenalty();

    /**
     * 获取模型生成响应的最大Token数量上限
     * 限制模型单次回复的长度，同时影响API调用成本（按Token计费）
     */
    Integer getMaxTokens();

    /**
     * 获取存在惩罚系数（Presence Penalty）
     */
    Float getPresencePenalty();

    /**
     * 获取停止序列列表（Stop Sequences）
     */
    List<String> getStopSequences();

    /**
     * 获取温度系数（Temperature）
     */
    Float getTemperature();

    /**
     * 获取Top-K采样参数
     */
    Integer getTopK();

    /**
     * 获取Top-P（核采样）参数
     */
    Float getTopP();

    /**
     * 创建当前ChatOptions对象的深拷贝副本
     */
    ChatOptions copy();
}

ChatOptions 除了一个默认实现类 DefaultChatOptions 外，还有两个子接口：

ToolCallingChatOptions：大模型调用外部工具 / 函数的专属配置接口。
StructuredOutputChatOptions：大模型生成结构化输出（如 JSON、XML、固定格式文本）的专属配置接口。

每个大模型厂商都有自己独有的 API 参数，所以 Spring AI 为特定厂商大模型也提供了不同的 ChatOptions 实现类，比如：

DeepSeekChatOptions：深度求索大模型专属配置。
ZhiPuAiChatOptions：智谱 AI 大模型专属配置。

2.2 创建对象

Spring AI 提供 ChatOptions.builder 快速构建配置，兼容所有厂商：

java 复制代码

        ChatOptions chatOptions = ChatOptions.builder()
                .model("glm-4-flash") // 指定智谱模型
                .temperature(0.1D) // 低随机性，适合精准回答
                .maxTokens(1024) // 最大输出1024 Token
                .topP(0.9D) // 核采样参数
                .stopSequences(List.of("###")) // 停止词
                .build();

也可以通过厂商专属实现类，支持厂商独有配置：

java 复制代码

        ZhiPuAiChatOptions zhipuOptions = ZhiPuAiChatOptions.builder()
                // 通用参数
                .model("glm-5")
                .maxTokens(2048)
                // 厂商独有
                .user("1234")
                .build();

3. 智谱 AI

3.1 发展历程

2019 年 6 月，北京智谱华章科技股份有限公司正式成立，由张鹏、唐杰等 KEG（清华大学计算机系知识工程实验室）团队核心成员创办，总部位于北京。

2025 年，智谱 AI 推出 GLM-4.5/4.6 旗舰模型，原生融合推理、编码、智能体三大能力，登顶 12 项权威评测国内第一、全球开源第一，编码能力全球并列第一，OpenRouter 调用量全球前 10、付费 API 收入超所有国产模型之和，实现中国大模型技术与商业双重突破。

2026 年 1 月 8 日，智谱 AI 在港交所上市，是全球首家以通用大模型为核心业务的上市公司，首日总市值 578.9 亿港元。

2026 年 2 月 11 日深夜，第五代旗舰大模型 GLM-5 正式发布，编程能力对齐 Claude Opus 4.5 ，擅长 Agentic 长程规划与执行。

截至 2026 年 3 月 4 日港股收盘，智谱 AI 的总市值约为 2336 亿港元。

提示：智谱 AI 也是采用「开源 + 闭源」并行策略，即开源中轻量级模型与工具链，闭源核心旗舰与商业服务。

3.2 智谱大模型平台

智谱大模型平台（BigModel）是智谱 AI 的，面向开发者与企业，提供功能丰富、灵活易用、高性价比的大模型 API 服务，支持智能体开发与模型精调、推理、评测等，致力于构建高效通用的一站式 MaaS（模型即服务）平台。

3.3 对话补全 API 文档

智谱 AI 开放平台提供标准的 HTTP API 接口，支持多种编程语言和开发环境，同时也提供 SDKs 方便开发者调用。

智谱 AI 开放平台的通用 API 端点如下：

java 复制代码

https://open.bigmodel.cn/api/paas/v4

使用 GLM 编码套餐时，需要配置专属的 Coding 端点：

java 复制代码

https://open.bigmodel.cn/api/coding/paas/v4

支持多种调用方式：

可以在官方 API 文档中找到对话补全 API ，和指定模型对话，模型根据请求给出响应。支持多种模型，支持多模态（文本、图片、音频、视频、文件），流式和非流式输出，可配置采样，温度，最大令牌数，工具调用等。

支持的参数如下：

参数名称	简单描述	数据类型	默认值	可配置值
model	调用的对话模型代码	enum<string>	glm-5	glm-5, glm-4.7, glm-4.7-flash, glm-4.7-flashx, glm-4.6, glm-4.5-air, glm-4.5-airx, glm-4.5-flash, glm-4-flash-250414, glm-4-flashx-250414
messages	对话消息上下文列表	array[object]	必填	包含 system/user/assistant/tool 消息
messages.role	消息角色	enum<string>	user	user
messages.content	消息文本内容	string	必填	任意字符串
stream	是否流式输出	boolean	false	true / false
thinking	思维链配置（仅 GLM-4.5+）	object	无	包含 type、clear_thinking
thinking.type	是否开启思维链	enum<string>	enabled	enabled / disabled
thinking.clear_thinking	是否清除历史推理内容	boolean	true	true / false
do_sample	是否启用采样策略	boolean	true	true / false
temperature	采样温度（0~1）	float	1.0	0.0 ~ 1.0
top_p	核采样参数（0.01~1）	float	0.95	0.01 ~ 1.0
max_tokens	最大输出 Token 数	integer	无	1 ~ 131072
tool_stream	工具调用流式输出	boolean	false	true / false
tools	工具调用配置	array[object]	无	function / retrieval / web_search 等
tools.type	工具类型	enum<string>	function	function
tools.function.name	函数名	string	必填	字母、数字、下划线、短横线
tools.function.description	函数描述	string	必填	任意字符串
tools.function.parameters	函数参数 JSON Schema	object	必填	JSON Schema 对象
tool_choice	工具选择策略	enum<string>	auto	auto
stop	停止词	array[string]	无	最多 1 个停止词
response_format	输出格式配置	object	无	{ type: "text" \| "json_object" }
response_format.type	输出格式类型	enum<string>	text	text / json_object
request_id	请求唯一 ID	string	自动生成	UUID 字符串
user_id	用户标识	string	无	6~128 字符

注意：Spring AI 中并没有集成智谱官方原生 Java SDK ，核心是为了坚守「通用抽象、厂商无关」的设计原则，避免绑定特定厂商的 SDK 版本和逻辑。

4. 案例演示

4.1 默认配置项

智谱 AI 对话模型的默认配置项前缀为 spring.ai.zhipuai.chat ，默认添加了以下配置项：

model：模型名称，默认为 glm-4-air 。
temperature：采样温度，默认为 0.7 。

java 复制代码

@ConfigurationProperties("spring.ai.zhipuai.chat")
public class ZhiPuAiChatProperties extends ZhiPuAiParentProperties {
    public static final String CONFIG_PREFIX = "spring.ai.zhipuai.chat";
    public static final String DEFAULT_CHAT_MODEL;
    private static final Double DEFAULT_TEMPERATURE;
    @NestedConfigurationProperty
    private final ZhiPuAiChatOptions options;

    public ZhiPuAiChatProperties() {
        this.options = ZhiPuAiChatOptions.builder().model(DEFAULT_CHAT_MODEL).temperature(DEFAULT_TEMPERATURE).build();
    }

    public ZhiPuAiChatOptions getOptions() {
        return this.options;
    }

    static {
        DEFAULT_CHAT_MODEL = ChatModel.GLM_4_Air.value;
        DEFAULT_TEMPERATURE = 0.7;
    }
}

此外，智谱 AI 模型配置中默认了 API 访问地址：

java 复制代码

@ConfigurationProperties("spring.ai.zhipuai")
public class ZhiPuAiConnectionProperties extends ZhiPuAiParentProperties {
    public static final String CONFIG_PREFIX = "spring.ai.zhipuai";
    public static final String DEFAULT_BASE_URL = "https://open.bigmodel.cn/api/paas";

    public ZhiPuAiConnectionProperties() {
        super.setBaseUrl("https://open.bigmodel.cn/api/paas");
    }
}

在 ZhiPuAiApi.ChatModel 中可以查看支持的所有模型名称：

提示：如果是最新版本，Spring AI 可能还没有集成，但是也是支持的，模型 API 不会随便改动，一般都是兼容之前的版本。

4.2 全局默认

无需手动构建 ChatOptions，可在配置文件中设置智谱 AI 对话模型全局默认值：

yml 复制代码

spring:
  application:
    name: spring-ai-01
    # 智谱 AI 配置
    zhipuai:
      api-key: f9d9e7c26bd24406ad03dc6fe21
      #base-url: https://open.bigmodel.cn/api/paas/v4
      # 对话模型配置
      chat:
        options:
          model: glm-5
          temperature: 0.7

在自动配置 ChatModel 时会加载全局配置：

在配置 ChatClient 时，也可以通过对象进行全局配置：

java 复制代码

    @Bean("zhiPuAiChatClient")
    public ChatClient zhiPuAiChatClient(ZhiPuAiChatModel zhiPuAiChatModel) {
        ChatOptions chatOptions = ChatOptions.builder()
                .model("glm-4-flash")
                .temperature(0.8D)
                .build();
        return ChatClient.builder(zhiPuAiChatModel)
                .defaultOptions(chatOptions)
                .build();
    }

4.3 单次请求配置

在请求处理过程中，也支持对话配置：

java 复制代码

            ChatOptions chatOptions = ChatOptions.builder()
                    .temperature(0.8D)
                    .build();
            return targetClient.prompt()
                    .user(message)
                    .options(chatOptions)
                    .stream()
                    .content()
                    .onErrorResume(e -> Flux.just("错误: " + e.getMessage()));

4.4 深度思考

深度思考（Thinking）高级推理功能，通过启用思维链（Chain of Thought）机制，让模型在回答问题前进行深层次的分析和推理。这种方式能显著提升模型在复杂任务中的准确性和可解释性，特别适用于需要多步推理、逻辑分析和问题解决的场景。

下面，我们使用智谱 AI 实现一个深度思考选择功能，默认不启用，点击后可以开启深度思考：

4.4.1 大模型支持

现在的大模型一般都支持深度思考，DeepSeek

智普 AI ：

4.4.2 全局关闭

glm-4.7 默认开启了深度思考模式，我们需要全局关闭。

方式一，可以在 application.yml 配置文件中关闭：

yml 复制代码

server:
  port: 8080
spring:
  application:
    name: ai-chat-demo
  ai:
    chat:
      client:
        enabled: false
    # 智谱 GLM 配置
    zhipuai:
      api-key: f9d9e7c26bd24406ad03dc    # 替换为你的智谱 API Key
      base-url: https://open.bigmodel.cn/api/paas # 可选，默认值可省略
      chat:
        options:
          model: glm-4.7 # 智谱模型名称（如 glm-4、glm-4-flash 等）
          thinking: disabled

查看 ChatClient 对象：

方式二，可以在 Java 配置类中关闭：

java 复制代码

    @Bean("zhiPuAiChatClient")
    public ChatClient zhiPuAiChatClient(ZhiPuAiChatModel zhiPuAiChatModel) {
        ZhiPuAiChatOptions chatOptions = ZhiPuAiChatOptions.builder()
                .thinking(ZhiPuAiApi.ChatCompletionRequest.Thinking.disabled()) // 关闭思考模式
                .build();

        return ChatClient.builder(zhiPuAiChatModel)
                .defaultOptions(chatOptions)
                .build();
    }

4.4.3 动态传参

定义 deepThink 参数，前端动态传过来就可以了：

java 复制代码

    @GetMapping(value = "/ai/generate/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
    @ResponseBody
    public Flux<String> generateStream(
            @RequestParam(value = "message", defaultValue = "你好") String message,
            @RequestParam(value = "deepThink", defaultValue = "false") boolean deepThink) {
        try {
            // 构建请求
            ChatClient.ChatClientRequestSpec promptSpec = zhiPuAiChatClient.prompt()
                    .user(message);
            // 开启深度思考
            if (deepThink){
                ZhiPuAiChatOptions chatOptions = ZhiPuAiChatOptions.builder()
                        .thinking(ZhiPuAiApi.ChatCompletionRequest.Thinking.enabled())
                        .build();
                promptSpec = promptSpec.options(chatOptions);
            }
            return promptSpec
                    .stream()
                    .content()
                    .onErrorResume(e -> Flux.just("错误: " + e.getMessage()));
        } catch (IllegalArgumentException e) {
            // 模型名称错误时返回提示
            return Flux.just("错误: " + e.getMessage());
        }
    }

4.4.4 验证

开启深度思考模式时， 助手消息中会包含 思维链内容 ：

可以参考以下方式拿到：

java 复制代码

        ZhiPuAiChatOptions chatOptions = ZhiPuAiChatOptions.builder()
                .thinking(ZhiPuAiApi.ChatCompletionRequest.Thinking.enabled())
                .build();
        ChatResponse chatResponse= zhiPuAiChatClient.prompt("你好").options(chatOptions).call().chatResponse();
        ZhiPuAiAssistantMessage output = (ZhiPuAiAssistantMessage)chatResponse.getResult().getOutput();
        String reasoningContent = output.getReasoningContent();
        System.out.println(reasoningContent);

打印结果如下：