跳到主要内容
版本：2.0.1

聊天模型 API

QWen 3.8 中英对照 Chat Models Chat Model API

Chat Model API 为开发者提供了在应用程序中集成 AI 驱动的聊天补全功能的能力。它利用预训练语言模型（例如 GPT，即生成式预训练 Transformer）根据用户的自然语言输入生成类人响应。

API 通常通过向 AI 模型发送提示词或部分对话来工作，该模型随后基于其训练数据和对自然语言模式的理解，生成完成或对话的延续。生成的响应返回给应用程序，应用程序可以将其呈现给用户，或用于进一步处理。

Spring AI Chat Model API 旨在提供一个简单且可移植的接口，用于与各种 AI Models 进行交互，使开发人员能够以极少的代码修改在不同模型之间切换。这种设计与 Spring 的模块化和可替换性理念相一致。

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

你可以在 Available Implementations 部分了解更多可用的实现，以及在 Chat Models Comparison 部分查看详细对比。

API 概览​

本节提供 Spring AI Chat Model API 接口及相关类的使用指南。

ChatModel​

以下是 ChatModel 接口定义：

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 接口定义：

public interface StreamingChatModel extends StreamingModel<Prompt, ChatResponse> {

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

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

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

Prompt​

Prompt 是一个 ModelRequest，它封装了一个 Message 对象列表以及可选的模型请求选项。以下列表展示了 Prompt 类的截断版本，其中省略了构造器和其他实用方法：

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 接口封装了 Prompt 文本内容、一组元数据属性以及一个名为 MessageType 的分类。

该接口定义如下：

public interface Content {

	String getText();

	Map<String, Object> getMetadata();
}

public interface Message extends Content {

	MessageType getMessageType();
}

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

public interface MediaContent extends Content {

	Collection<Media> getMedia();

}

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

Spring AI Message API

聊天补全端点会根据对话中的角色来区分消息类别，并有效地映射到 MessageType。

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

虽然术语 MessageType 可能暗示特定的消息格式，但在此上下文中，它实际上指的是消息在对话中所扮演的角色。

对于不使用特定角色的 AI 模型，UserMessage 实现作为一种标准类别，通常代表用户生成的查询或指令。要了解 Prompt 和 Message 之间的实际应用及关系，尤其是在这些角色或消息类别的背景下，请参阅 Prompts 部分中的详细说明。

聊天选项​

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

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 Chat Completion 模型就有诸如 logitBias、seed 和 user 等专属选项。

Spring AI 提供了一套成熟的 Chat Model 配置和使用体系。它支持在启动时设置默认配置，同时允许在每次请求时灵活地覆盖这些配置。这种方式使开发人员能够在 Spring AI 框架提供的一致接口内，轻松地使用不同的 AI 模型并根据需要调整参数。

使用 ChatModel.call() / ChatModel.stream() 时，传入的 prompt 需要包含一套完整的选项，该选项将完全覆盖模型中设置的选项（或者在 Prompt 中使用 null 选项以使用模型的默认值）。

ChatClient 抽象允许采用增量式的方法，用户可以提供一个“delta”定制器，在每次请求的基础上覆盖默认选项。

以下流程图说明了 Spring AI 如何处理聊天模型的配置与执行：

chat model conversions

  1. 启动配置 - ChatModel/StreamingChatModel 使用 “Start-Up” Chat Options 进行初始化。这些选项在 ChatModel 初始化时设置，旨在提供默认配置。

  2. 运行时配置 - 对于每个请求，Prompt 可以包含 Runtime Chat Options：这些选项会完全覆盖启动配置中的选项。

  3. 输入处理 - “Convert Input” 步骤将输入指令转换为原生的、模型特定的格式。

  4. 输出处理 - “Convert Output” 步骤将模型响应转换为标准化的 ChatResponse 格式。

ChatResponse​

ChatResponse 类的结构如下：

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 类继承自 ModelResult，用于表示模型输出（助手消息）及相关元数据：

public class Generation implements ModelResult<AssistantMessage> {

	private final AssistantMessage assistantMessage;
	private ChatGenerationMetadata chatGenerationMetadata;

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

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

    // other methods omitted
}

可用实现​

该图展示了统一接口 ChatModel 和 StreamingChatModel，它们用于与来自不同提供商的多种 AI 聊天模型进行交互，使得客户端应用能够在保持 API 一致性的同时，轻松地集成和切换不同的 AI 服务。

spring ai chat completions clients

提示

关于可用 Chat Models 的详细对比，请参见Chat Models Comparison部分。

聊天模型 API​

Spring AI 聊天模型 API 构建于 Spring AI 通用模型 API 之上，提供了聊天相关的抽象和实现。这便于在不同 AI 服务之间进行集成和切换，同时为客户端应用保持一致的 API。以下类图展示了 Spring AI 聊天模型 API 的主要类和接口。

spring ai chat api

章节概要​