聊天模型 API

聊天模型 API 让开发者能够为应用集成由 AI 驱动的聊天补全能力。它利用经过预训练的语言模型（例如 GPT，即生成式预训练变换器），针对用户输入生成类似人类的自然语言响应。

该 API 通常的工作方式是：把一个提示词或部分对话发送给 AI 模型，模型再基于其训练数据以及对自然语言模式的理解，生成一个补全或对话的延续。随后完成的响应被返回给应用，应用可以把它呈现给用户或用于进一步处理。

Spring AI Chat Model API 被设计为一个简单且可移植的接口，用于与各种 AI 模型交互，让开发者只需极少的代码改动就能在不同模型间切换。这一设计与 Spring 的模块化与可互换理念一脉相承。

同时，借助用于输入封装的 Prompt 和用于输出处理的 ChatResponse 等配套类，聊天模型 API 统一了与 AI 模型的通信。它管理请求准备与响应解析的复杂性，提供一个直接而简化的 API 交互。

你可以在可用实现一节中找到关于可用实现的更多信息，也能在聊天模型对比一节中找到详细的比较。

API 概览

本节提供 Spring AI 聊天模型 API 接口及相关类的指南。

ChatModel

以下是 ChatModel 接口的定义：

java

public interface ChatModel extends Model<Prompt, ChatResponse>, StreamingChatModel {

	default String call(String message) {...}

    @Override
	ChatResponse call(Prompt prompt);
}

带 String 参数的 call() 方法简化了最初的使用，避免了更复杂的 Prompt 和 ChatResponse 类所带来的繁复。在真实应用中，更常用的是接收一个 Prompt 实例并返回一个 ChatResponse 的 call() 方法。

StreamingChatModel

以下是 StreamingChatModel 接口的定义：

java

public interface StreamingChatModel extends StreamingModel<Prompt, ChatResponse> {

    default Flux<String> stream(String message) {...}

    @Override
	Flux<ChatResponse> stream(Prompt prompt);
}

stream() 方法像 ChatModel 一样接收一个 String 或 Prompt 参数，但它使用响应式 Flux API 来流式传输响应。

Prompt

Prompt 是一个 ModelRequest，它封装了一个 Message 对象列表以及可选的模型请求选项。下面的清单展示了 Prompt 类的精简版本，省略了构造器和其他工具方法：

java

public class Prompt implements ModelRequest<List<Message>> {

    private final List<Message> messages;

    private ChatOptions modelOptions;

	@Override
	public ChatOptions getOptions() {...}

	@Override
	public List<Message> getInstructions() {...}

    // constructors and utility methods omitted
}

Message

Message 接口封装了一个 Prompt 文本内容、一组元数据属性，以及一个称为 MessageType 的分类。

该接口定义如下：

java

public interface Content {

	String getText();

	Map<String, Object> getMetadata();
}

public interface Message extends Content {

	MessageType getMessageType();
}

多模态消息类型还实现了 MediaContent 接口，提供一个 Media 内容对象列表。

java

public interface MediaContent extends Content {

	Collection<Media> getMedia();

}

Message 接口有多种实现，对应 AI 模型可处理的消息类别：

聊天补全端点会区分基于对话角色的消息类别，而这些角色由 MessageType 有效地映射。

例如，OpenAI 会为不同的对话角色识别消息类别，如 system、user、function 或 assistant。

虽然 MessageType 这个术语可能暗示某种特定的消息格式，但在此语境中，它实际上标示的是一条消息在对话中所扮演的角色。

对于不使用特定角色的 AI 模型，UserMessage 实现充当一个标准类别，通常代表用户生成的询问或指令。要理解其实际应用以及 Prompt 与 Message 之间的关系，尤其是在这些角色或消息类别的语境下，请参见提示词一节中的详细说明。

聊天选项

表示可传给 AI 模型的选项。ChatOptions 类是 ModelOptions 的子类，用于定义少数可传给 AI 模型的可移植选项。 ChatOptions 类定义如下：

java

public interface ChatOptions extends ModelOptions {

	String getModel();
	Double getFrequencyPenalty();
	Integer getMaxTokens();
	Double getPresencePenalty();
	List<String> getStopSequences();
	Double getTemperature();
	Integer getTopK();
	Double getTopP();
	ChatOptions.Builder<?> mutate();

}

此外，每个模型特定的 ChatModel/StreamingChatModel 实现都可以有其自己可传给 AI 模型的选项。例如，OpenAI 聊天补全模型就有它自己的选项，如 logitBias、seed 和 user。

Spring AI 提供了一套精巧的系统来配置和使用聊天模型。它允许在启动时设置默认配置，同时也提供在每次请求基础上覆盖这些设置的灵活性。这种方式让开发者能够在 Spring AI 框架提供的一致接口内，轻松使用不同的 AI 模型并按需调整参数。

当使用 ChatModel.call() / ChatModel/stream() 时，所传入的提示词需要包含一整套选项，它们会完全优先于模型中设置的选项（或在 Prompt 中使用 null 选项以采用模型的默认值）。

ChatClient 抽象支持一种渐进式方法，让用户可以提供“增量（delta）”定制器，在每次请求的基础上覆盖默认选项。

下面的流程图展示了 Spring AI 如何处理聊天模型的配置与执行：

启动配置 - ChatModel/StreamingChatModel 使用“启动时”的 Chat Options 初始化。这些选项在 ChatModel 初始化期间设置，用于提供默认配置。
运行时配置 - 对于每个请求，Prompt 可以包含运行时的 Chat Options：它们会完全覆盖启动时的选项。
输入处理 - “转换输入”这一步把输入指令转换为原生的、模型特定的格式。
输出处理 - “转换输出”这一步把模型的响应转换为标准化的 ChatResponse 格式。

ChatResponse

ChatResponse 类的结构如下：

java

public class ChatResponse implements ModelResponse<Generation> {

    private final ChatResponseMetadata chatResponseMetadata;
	private final List<Generation> generations;

	@Override
	public ChatResponseMetadata getMetadata() {...}

    @Override
	public List<Generation> getResults() {...}

    // other methods omitted
}

ChatResponse 类持有 AI 模型的输出，其中每个 Generation 实例包含由单个提示词产生的、可能多个输出中的一个。

ChatResponse 类还携带一个 ChatResponseMetadata，即关于 AI 模型响应的元数据。

Generation

最后，Generation 类继承自 ModelResult，用于表示模型输出（助手消息）及相关元数据：

java

public class Generation implements ModelResult<AssistantMessage> {

	private final AssistantMessage assistantMessage;
	private ChatGenerationMetadata chatGenerationMetadata;

	@Override
	public AssistantMessage getOutput() {...}

	@Override
	public ChatGenerationMetadata getMetadata() {...}

    // other methods omitted
}

消息部件

AssistantMessage、UserMessage、ToolResponseMessage 的内容是一个有序的 MessagePart 条目列表，可通过 getParts() 获取。一个部件是以下类型之一，均位于 org.springframework.ai.chat.messages.part 包中：

部件	内容
`TextPart`	一段文本。
`ReasoningPart`	模型的推理：文本、一个可选的摘要、一个 `redacted` 标志，以及一个服务商负载（例如签名，必须原样发回）。
`ToolCallPart`	一次工具调用，包装 `AssistantMessage.ToolCall`；服务商特定的额外字段位于其 attributes 中。
`ToolResultPart`	带有内容部件列表的工具结果，用于工具结果不止包含文本时。
`MediaPart`	图像、音频、视频或文档 `Media`。
`UnknownPart`	Spring AI 未建模的服务商区块，以原始 JSON 形式保留，以便回放给同一服务商。

那些熟悉的访问器是这些部件的视图，按部件顺序排列：getText() 连接所有 TextPart 条目，getMedia() 选取所有 MediaPart 条目；而在 AssistantMessage 上，getToolCalls() 选取完整的 ToolCallPart 条目，getReasoning() 选取 ReasoningPart 条目。一个含有部件但没有文本部件的消息，其文本为空。

通过构造器或 content(...)、text(...)、toolCalls(...) 和 media(...) 构建器方法创建的消息，其部件按传统顺序排列——先是文本，然后是工具调用，再是媒体，从而让既有代码无需改动即可继续工作。要控制顺序，请直接添加部件：

java

UserMessage question = UserMessage.builder()
    .part(TextPart.of("What changed between these two charts?"))
    .part(MediaPart.of(firstChart))
    .part(MediaPart.of(secondChart))
    .build();

ChatResponse response = chatModel.call(new Prompt(question));
AssistantMessage answer = response.getResult().getOutput();
for (ReasoningPart reasoning : answer.getReasoning()) {
    System.out.println("Reasoning: " + reasoning.text());
}
System.out.println(answer.getText());

一个部件可以携带一个 OpaquePayload，其中含 provider、kind 和不透明的 data，例如 Anthropic 的思考签名或 Gemini 的思维签名。产出某个负载的聊天模型会在下一次请求中原样回放它，而其他聊天模型则会跳过它，因此对话历史可以在服务商之间迁移。各服务商页面会记录每个聊天模型所产出的负载与属性。

在流式传输时，每个块都携带其部件，并标注它们所属内容块的索引以及一个 partial 标志，参见 StreamingParts。被 ChatClient 和各顾问使用的 MessageAggregator，会从这些块重建完整的部件并剥离流式属性，从而让聚合后的消息等同于阻塞调用返回的那一条。

可用实现

这张图展示了统一的接口 ChatModel 与 StreamingChatModel，用于与来自不同服务商的各种 AI 聊天模型交互，从而在保持对客户端应用一致 API 的同时，轻松集成并在不同 AI 服务之间切换。

OpenAI 聊天补全（支持流式、多模态与函数调用）
Ollama 聊天补全（支持流式、多模态与函数调用）
Amazon Bedrock
Mistral AI 聊天补全（支持流式与函数调用）
Anthropic 聊天补全（支持流式与函数调用）

TIP

关于可用聊天模型的详细对比，请参见聊天模型对比一节。