聊天模型 API

本站(springdoc.cn)中的内容来源于 spring.io ，原始版权归属于 spring.io。由 springdoc.cn 进行翻译，整理。可供个人学习、研究，未经许可，不得进行任何转载、商用或与之相关的行为。 商标声明：Spring 是 Pivotal Software, Inc. 在美国以及其他国家的商标。

聊天模型（Chat Model） API 使开发者能将 AI 驱动的对话补全功能集成到应用中。该 API 基于 GPT（生成式预训练变换器）等预训练语言模型，生成类人的自然语言响应。

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

Spring AI Chat Model API 设计为简洁可移植的接口，支持与多种 AI 模型 交互，使开发者能以最小代码变更切换不同模型。这一设计符合 Spring 模块化与可互换性的理念。

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

具体实现可参阅 可用实现 章节，详细对比参见 聊天模型对比 部分。

API 概览

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

ChatModel

ChatModel 接口的定义如下：

public interface ChatModel extends Model<Prompt, ChatResponse> {

	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() {...}

    // 省略构造函数及其他工具方法
}

Message

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();
	Float getFrequencyPenalty();
	Integer getMaxTokens();
	Float getPresencePenalty();
	List<String> getStopSequences();
	Float getTemperature();
	Integer getTopK();
	Float getTopP();
	ChatOptions copy();

}

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

这一强大特性允许开发者在启动应用时使用模型专属配置，并通过 Prompt 请求在运行时动态覆盖这些参数。

Spring AI 提供了一套完善的聊天模型配置与使用体系。该系统支持在应用启动时设置默认配置，同时允许基于每个请求灵活覆盖这些设置。通过这一设计，开发者能够借助 Spring AI 框架的统一接口，便捷地切换不同 AI 模型并按需调整参数。

以下流程图展示了 Spring AI 如何处理聊天模型的配置与执行，融合了启动配置和运行时选项：

chat options flow

  1. 启动配置 - ChatModel / StreamingChatModel 初始化时加载 “Start-Up” 聊天选项。这些选项在模型初始化阶段设置，用于提供默认配置。

  2. 运行时配置 - 每个请求的 Prompt 可携带运行时聊天选项，这些选项会覆盖启动配置。

  3. 选项合并流程 - “Merge Options” 步骤会将启动配置与运行时选项结合。若存在运行时选项，其优先级高于启动配置。

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

  5. 输出处理 - “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() {...}

    // 其他方法省略
}

ChatResponse 类封装 AI 模型的输出结果，每个 Generation 实例可能包含单个提示词生成的多个输出之一。

ChatResponse 类还携带描述 AI 模型响应的元数据 ChatResponseMetadata。

Generation

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

public class Generation implements ModelResult<AssistantMessage> {

	private final AssistantMessage assistantMessage;
	private ChatGenerationMetadata chatGenerationMetadata;

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

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

    // 其他方法省略
}

可用的实现

如下示意图展示统一接口 ChatModel 和 StreamingChatModel 的运作机制，这些接口用于与不同供应商的 AI 聊天模型交互，使客户端应用在保持统一 API 的同时，能轻松集成和切换不同的 AI 服务。

spring ai chat completions clients
详细对比现有聊天模型的功能特性，请参阅 聊天模型对比 章节。

聊天模型 API

Spring AI 聊天模型 API 构建于通用模型 API 之上，提供聊天场景专用的抽象与实现。该设计既能保持客户端应用接口的一致性，又能轻松集成和切换不同的 AI 服务。以下类图展示了 Spring AI 聊天模型 API 的核心接口与类结构。

spring ai chat api