聊天模型 API

Chat Model API 为开发者提供了一种将 AI 驱动的聊天补全能力集成到应用程序中的方式。它基于预训练的语言模型（如 GPT，生成式预训练变换器），能够根据用户的自然语言输入生成类人化的回复。

Chat Model API 为开发者提供了一种将 AI 驱动的聊天补全能力 集成到应用程序中的方式。它基于预训练的语言模型（如 GPT，生成式预训练变换器），能够根据用户的自然语言输入生成类人化的回复。

该 API 的典型工作流程是：向 AI 模型发送一个 提示（prompt） 或一段 不完整的对话，模型会基于其训练数据以及对自然语言模式的理解，生成对话的补全或延续。生成完成后，响应会返回给应用程序，供其展示给用户或用于后续处理。

Spring AI 的 Chat Model API 被设计为一个 简单且可移植的接口，用于与多种 AI 模型进行交互，使开发者只需进行极少的代码修改，就能在不同模型之间自由切换。这一设计理念与 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() 方法与 ChatModel 类似，可以接收 String 或 Prompt 作为参数，不同之处在于它通过 响应式的 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 接口用于封装 Prompt 的文本内容、一组元数据属性，以及一种称为 MessageType 的分类信息。

其接口定义如下：

public interface Content {

    String getText();

    Map<String, Object> getMetadata();
}

public interface Message extends Content {

    MessageType getMessageType();
}

对于多模态消息类型，还会实现 MediaContent 接口，用于提供一组媒体内容对象：

public interface MediaContent extends Content {

    Collection<Media> getMedia();

}

Message 接口具有多种实现，用于对应 AI 模型能够处理的不同消息类别。

Spring AI Message API

聊天补全（Chat Completion）接口会根据对话角色来区分不同的消息类别，这些角色在 Spring AI 中通过 MessageType 进行映射。

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

尽管 MessageType 这个名称看起来像是在表示某种特定的消息格式，但在这里它本质上表示的是消息在对话中所扮演的角色。

对于那些不区分具体角色的 AI 模型，UserMessage 实现充当了默认的消息类型，通常用于表示用户生成的问题或指令。若要深入理解 Prompt 与 Message 的实际用法，以及它们与这些角色或消息类别之间的关系，请参阅 Prompts 章节中的详细说明。

Chat Options

ChatOptions 用于表示可以传递给 AI 模型的配置选项。它是 ModelOptions 的一个子接口，用来定义一组通用且可移植的模型参数。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 实现都可以定义模型专属的选项。例如，OpenAI 的 Chat Completion 模型就支持诸如 logitBias、seed、user 等专有参数。

这是一个非常强大的特性，它允许开发者在应用启动时使用模型特有的配置，同时在运行时通过 Prompt 请求对这些配置进行覆盖。

Spring AI 提供了一套完善的 Chat Model 配置与使用体系，既支持在启动阶段设置默认配置，又允许在每次请求时灵活覆盖这些配置。这种设计使开发者能够在统一的 Spring AI 接口下，轻松切换不同的 AI 模型并按需调整参数。

下图展示了 Spring AI 在 Chat Model 配置与执行过程中的整体流程（结合了启动期与运行期配置）：

启动期配置（Start-up Configuration）—— 在初始化 ChatModel / StreamingChatModel 时设置启动期 ChatOptions，用于提供全局的默认配置。
运行期配置（Runtime Configuration）—— 每一次请求中，Prompt 都可以携带运行期 ChatOptions，用于覆盖默认配置。
配置合并（Option Merging Process）—— 在 “合并选项” 阶段，将启动期配置与运行期配置进行合并；如果提供了运行期配置，则其优先生效。
输入处理（Input Processing）—— 在 “输入转换” 阶段，将输入指令转换为具体模型所需的原生格式。
输出处理（Output Processing）—— 在 “输出转换” 阶段，将模型返回的响应统一转换为标准化的 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 实例都表示一次提示（Prompt）可能产生的 多个输出之一。

此外，ChatResponse 还包含一个 ChatResponseMetadata 对象，用于保存 AI 模型响应的元数据信息。

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

    // 其他方法已省略
}

Generation 对象封装了模型生成的一条 助手回复，同时还携带了与该生成结果相关的 元数据信息，用于描述和补充模型输出的上下文。

可用实现

该示意图展示了如何通过统一的接口 ChatModel 和 StreamingChatModel 与来自不同提供商的多种 AI 聊天模型进行交互。借助这一统一抽象，客户端应用能够在保持 一致 API 的前提下，轻松完成集成，并在不同 AI 服务之间自由切换。

Spring AI Chat Completions 客户端支持的模型包括：

OpenAI Chat Completion 支持流式输出、多模态以及函数调用
Microsoft Azure OpenAI Chat Completion 支持流式输出与函数调用
Ollama Chat Completion 支持流式输出、多模态以及函数调用
Hugging Face Chat Completion 不支持流式输出
Google Vertex AI Gemini Chat Completion 支持流式输出、多模态以及函数调用
Amazon Bedrock
Mistral AI Chat Completion 支持流式输出与函数调用
Anthropic Chat Completion 支持流式输出与函数调用

你可以在 Chat Models Comparison（聊天模型对比）章节中查看各类 Chat Model 的详细对比说明。

Spring AI 的 Chat Model API 构建在 Spring AI 通用模型 API（Generic Model API） 之上，提供了面向聊天场景的专用抽象与实现。这种设计使得在不同 AI 服务之间进行集成与切换变得更加简单，同时仍能为客户端应用保持 一致的 API 接口。下面的类图展示了 Spring AI Chat Model API 中的主要类与接口结构。

models

聊天模型对比

下表对 Spring AI 支持的各类 Chat Model 进行了功能对比，涵盖以下能力：