spring ai 1.0.0-SNAPSHOT

Chat Model API 为开发者提供了将智能对话补全能力集成至应用程序的接口。该API基于预训练语言模型（如GPT生成式预训练变换器），可生成符合人类语言习惯的交互响应。

其标准工作流程是：应用程序向AI模型发送提示信息或对话片段，模型根据训练数据对自然语言模式的理解生成对话补全内容，最终将结构化响应返回给调用方，供终端用户展示或后续业务处理。

Spring AI Chat Model API 采用简洁可移植的设计理念，通过统一接口实现对多种AI模型的调用，开发者仅需极少的代码调整即可切换不同模型。这一设计完美契合Spring框架模块化与可互换性的核心思想。

通过Prompt（输入封装）和ChatResponse（输出处理）等配套类的协作，该API实现了与AI模型通信的标准化。它封装了请求构建与响应解析的复杂性，为开发者提供了开箱即用的简洁接口。

API概述

ChatModel
ChatModel接口的定义如下：

public interface ChatModel extends Model<Prompt, ChatResponse>, StreamingChatModel {
	default String call(String message) {
		...
	}
	default String call(Message... messages) {
		...
	}
	@Override
	ChatResponse call(Prompt prompt);
	default ChatOptions getDefaultOptions() {
		...
	}
	default Flux<ChatResponse> stream(Prompt prompt) {
		...
	}
}

带有String参数的call()方法简化了初始使用，避免了更复杂的Prompt和ChatResponse类的复杂性。在实际应用中，更常见的是使用接受Prompt实例并返回ChatResponse的call()方法。
在新的代码中增加了Message参数的call方法，除了携带的文本内容之外还能附加一些属性和消息的类型（user，assistant，system，tool）。

StreamingChatModel
StreamingChatModel接口的方法和与ChatModel接口的方法类似，但是StreamingChatModel使用响应式的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
Message 接口封装了提示文本内容、一组元数据属性以及一个称为 MessageType 的分类标识。

public interface Content {

	String getText();

	Map<String, Object> getMetadata();
}

public interface Message extends Content {

	MessageType getMessageType();
}

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

聊天补全端点（chat completion endpoint）根据对话角色区分消息类别，这种区分通过MessageType进行了有效映射。
例如，OpenAI 将消息类别划分为不同的对话角色，如 system（系统）、user（用户）、function（函数）或 assistant（助手）。
虽然 MessageType 这一术语可能让人联想到某种特定的消息格式，但在此上下文中，它实际上用于标识消息在对话中的 角色。
对于不使用特定角色的 AI 模型，UserMessage 则会充当标准类别，通常代表用户生成的查询或指令。

Chat Options
表示可传递给AI模型的配置选项。ChatOptions类是ModelOptions的子类，用于定义一组可跨模型通用的配置参数，这些参数能够传递给AI模型使用。

此外，每个特定模型的ChatModel/StreamingChatModel实现都可以包含专属于该模型的配置选项。以OpenAI的聊天补全模型为例，它支持logitBias（对数偏差）、seed（随机种子）和user（用户标识）等特有参数。

这一设计赋予了开发者强大的灵活性：既能在应用启动时配置模型专用参数，又能在运行时通过Prompt请求动态覆盖这些设置。

Spring AI构建了一套精密的聊天模型配置与执行体系。该系统支持：

1. 启动阶段设置默认配置
2. 每次请求时动态覆盖配置
3. 通过统一接口适配不同AI模型
4. 实时调整模型参数

这种双重配置机制（启动配置+运行时覆盖）使开发者能够：

• 快速切换不同AI模型
• 按需调整参数
• 保持接口一致性

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

1. 启动配置 – ChatModel/StreamingChatModel 在初始化时会加载”启动配置项”。这些配置项在模型初始化阶段设置，用于提供默认参数。
2. 运行时配置 – 每个Prompt请求可携带”运行时配置项”：这些配置能够覆盖启动阶段的默认设置。
3. 配置合并流程 – “合并配置”步骤会将启动配置与运行时配置进行整合。若存在运行时配置，则其优先级高于启动配置。
4. 输入处理 – “转换输入”步骤将输入指令转换为模型特定的原生格式。
5. 输出处理 – “转换输出”步骤将模型的响应转换为标准化的ChatResponse格式。

启动配置与运行时配置的分离机制，既支持全局参数预设，又能实现请求级细粒度调优。

ChatResponse
ChatResponse 类封装了 AI 模型的输出结果，其中每个 Generation 实例代表单个提示可能产生的多个输出之一。
ChatResponse 类还包含 ChatResponseMetadata 元数据，用于记录 AI 模型响应的相关信息。

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

Chat模型API

Spring AI 聊天模型 API 基于 Spring AI 通用模型 API 构建，提供了专门针对聊天场景的抽象层与实现。这种架构设计使得：

1. 能够轻松集成不同AI服务
2. 支持服务间的无缝切换
3. 为客户端应用保持统一的API接口

下图展示了 Spring AI 聊天模型 API 的核心类与接口关系：