模型 Model

官方文档

https://docs.spring.io/spring-ai/reference/api/chatmodel.html

模型特性

通过提供统一的模型适配接口，使得切换模型变得方便；
提供了各种模型的自动配置 starter，进一步方便模型的创建
支持所有的主流模型，例如远程的 OpenAI / Anthropic / Google 等模型和本地的 Ollama 模型
支持丰富的模型类型，例如 Chat 模型 / 文生图模型 / TTS(文本转语音模型) 等

本章我们仅介绍最常用的 OpenAI 协议的 Chat 模型和 Ollama 的 Chat 模型。

模型定义

ChatModel 统一模型

java

public interface ChatModel extends Model<Prompt, ChatResponse>, StreamingChatModel {
	/**
	 * 同步调用
	 * @param prompt 标准入参
	 * @return ChatResponse 标准返回
	 */
	@Override
	ChatResponse call(Prompt prompt);
}

StreamingChatModel 流式模型

java

public interface StreamingChatModel extends StreamingModel<Prompt, ChatResponse> {
	/**
	 * 流式调用
	 *
	 * @param prompt 标准输入
	 * @return Flux<ChatResponse> 标准输入
	 */
	@Override
	Flux<ChatResponse> stream(Prompt prompt);
}

ChatOptions 模型参数运行时设置

通用参数设置（所有模型均可以设置的参数）

java

public interface ChatOptions extends ModelOptions {
	/**
	 * 所用模型
	 */
	String getModel();

    /**
     * temperature：越高，回答越发散，例如可用于写散文；越低，回答越精确，例如回答数学问题
     */
    Double getTemperature();

    /**
     * topK
     */
    Integer getTopK();

    /**
     * topP
     */
    Double getTopP();
    
	Double getFrequencyPenalty();

    Double getPresencePenalty();
	/**
	 * 最大可用 token 数
	 */
	Integer getMaxTokens();
    
	List<String> getStopSequences();
}

说明：

temperature / topK / topP：用于控制模型回答的发散性；frequencyPenalty / presencePenalty：用户控制文本出现的重复性，取值范围 -2.0~2.0，值越大，重复性越低
大部分参数的含义均可以在这里查看
除了通用参数设置之外，不同的模型还具有模型独有的参数设置，这些设置项存储在各个专有 Options 中，例如 OllamaOptions
模型参数的推荐设置方式：在服务启动的时候，可以为 ChatClient 设置统一的默认值，在运行时通过 Prompt 进行同值覆盖

ChatResponse 统一输出

java

public class ChatResponse implements ModelResponse<Generation> {
	/**
	 * 元数据
	 */
	private final ChatResponseMetadata chatResponseMetadata;

	/**
	 * 一个 prompt 返回的多个潜在信息
	 */
	private final List<Generation> generations;
}

public class Generation implements ModelResult<AssistantMessage> {
	/**
	 * assistant 消息：ai 返回的消息。包含消息内容和工具列表信息
	 */
	private final AssistantMessage assistantMessage;

	private ChatGenerationMetadata chatGenerationMetadata;
}

Ollama 本地模型

Ollama 可以方便的在本地运行大语言模型。

安装 Ollama

关于 Ollama 的安装和使用见安装大模型本地运行利器 ollama。

引入依赖

xml

<!-- model-本地 -->
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-ollama</artifactId>
</dependency>

配置 application.properties

text

spring.ai.model.chat=ollama
spring.ai.ollama.base-url=http://127.0.0.1:11434
spring.ai.ollama.chat.options.model=qwen3:32b
spring.ai.ollama.chat.options.temperature=0.7

说明：

spring.ai.model.chat：必填，ollama - 表示使用 SpringAI 的自动配置能力；none - 表示不使用 SpringAI 的自动配置能力，适用于手动配置场景
spring.ai.ollama.base-url：必填，Ollama 提供服务的地址
spring.ai.ollama.chat.options.model：必填，模型 ID
spring.ai.ollama.chat.options.temperature：默认，0.8。越高，回答越发散，例如可用于写散文；越低，回答越精确，例如回答数学问题
其他完整的配置见这里

参数设置

启动时可以通过 application.properties 中的选项或者手动通过 OllamaChatModel(api, options) 设置参数。运行时可以通过 Prompt 进行动态设置。

java

ChatResponse response = chatClient.prompt(
                new Prompt(
                        "Generate the names of 5 famous pirates.",
                        OllamaOptions.builder()
                                .model(OllamaModel.LLAMA3_1)
                                .temperature(0.4)
                                .build()
                )).call().chatResponse();

手动方式

仅引入依赖

xml

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-ollama</artifactId>
</dependency>

使用

java

@Bean
public ChatModel chatModel() {
    return OllamaChatModel.builder()
            .ollamaApi(OllamaApi.builder().build())
            .defaultOptions(
                    OllamaOptions.builder()
                            .model("qwen3:32b")
                            .temperature(0.9)
                            .build())
            .build();
}

如果需要使用 ChatClient，此时还需要单独引入：

xml

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-client-chat</artifactId>
</dependency>

java

@Bean
public ChatModel chatModel() {
    return OllamaChatModel.builder()
            .ollamaApi(OllamaApi.builder().build())
            .defaultOptions(
                    OllamaOptions.builder()
                            .model("gpt-oss:20b")
                            .temperature(0.9)
                            .build())
            .build();
}

@Bean
public ChatClient chatClient(ChatModel chatModel) {
    return ChatClient.create(chatModel);
}

兼容 OpenAI 协议的远程模型

OpenAI 是行业最领先的 AI 公司，其 API 协议也成为了行业标准，众多的模型都会去兼容 OpenAI 协议，本节就使用兼容 OpenAI 协议的 Qwen 模型来做测试。

引入依赖

xml

<!-- model-openai -->
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-openai</artifactId>
</dependency>

配置 application.properties

text

spring.ai.model.chat=openai
spring.ai.openai.base-url=https://dashscope.aliyuncs.com/compatible-mode/
spring.ai.openai.api-key=填写你自己的apiKey
spring.ai.openai.chat.options.model=qwen-long
spring.ai.openai.chat.options.temperature=0.7

说明：

spring.ai.model.chat：必填，openai - 表示使用 SpringAI 的自动配置能力；none - 表示不使用 SpringAI 的自动配置能力，适用于手动配置场景
spring.ai.openai.base-url：如果使用阿里云的百炼模型，填写如上，在百炼平台查看
spring.ai.openai.api-key：如果使用阿里云的百炼模型，在百炼平台申请和查看
spring.ai.openai.chat.options.model：如果使用阿里云的百炼模型，在百炼平台查看，选择一个合适的模型即可
spring.ai.ollama.chat.options.temperature：默认，0.8。越高，回答越发散，例如可用于写散文；越低，回答越精确，例如回答数学问题
其他完整的配置见这里

参数设置

与 Ollama 方式类似，不再赘述

手动方式

与 Ollama 方式类似，不再赘述

文章的最后，如果您觉得本文对您有用，请打赏一杯咖啡！感谢！

模型 Model ​

模型特性 ​

模型定义 ​

ChatModel 统一模型 ​

StreamingChatModel 流式模型 ​

ChatOptions 模型参数运行时设置 ​

ChatResponse 统一输出 ​

Ollama 本地模型 ​

安装 Ollama ​

引入依赖 ​

配置 application.properties ​

参数设置 ​

手动方式 ​

兼容 OpenAI 协议的远程模型 ​

引入依赖 ​

配置 application.properties ​

参数设置 ​

手动方式 ​

模型 Model

模型特性

模型定义

ChatModel 统一模型

StreamingChatModel 流式模型

ChatOptions 模型参数运行时设置

ChatResponse 统一输出

Ollama 本地模型

安装 Ollama

引入依赖

配置 application.properties

参数设置

手动方式

兼容 OpenAI 协议的远程模型

引入依赖

配置 application.properties

参数设置

手动方式