Spring AI之Chat Model API

聊天模型API为开发者提供了将基于人工智能的聊天补全功能集成到应用程序中的能力。它利用预训练语言模型（如GPT（生成式预训练变换器）），根据自然语言输入生成类人响应。

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

Spring AI聊天模型API旨在提供一个与各类AI模型交互的简洁且可移植的接口，使开发者能够以最小的代码改动切换不同模型。该设计理念与Spring框架的模块化和可替换性哲学保持一致。

通过使用Prompt（输入封装）和ChatResponse（输出处理）等配套类，聊天模型API统一了与AI模型的通信流程。它管理请求准备和响应解析的复杂性，提供直接简化的API交互方式。

您可在可用实现部分查看详细实施方案，并在聊天模型对比部分获得各模型的详细比较分析。

API 概述

本节提供 Spring AI 聊天模型 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() {...}

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

• messages：存储对话消息的列表 。
• modelOptions：定义模型调用时的可选配置（如温度、最大令牌数等）。
• getInstructions()：返回消息列表，适配 ModelRequest 接口的通用性设计。

消息（Message）

Message 接口封装了 Prompt 的文本内容、元数据属性集合以及称为 MessageType 的分类。
接口定义如下：

public interface Content {
    String getContent();
    Map<String, Object> getMetadata();
}

public interface Message extends Content {
    MessageType getMessageType();
}

多模态消息类型还实现了 MediaContent 接口，提供媒体内容对象列表：

public interface MediaContent extends Content {
    Collection<Media> getMedia();
}

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

Spring AI 消息 API

聊天补全端点根据对话角色区分消息类别，这些角色通过 MessageType 映射。
例如，OpenAI 为不同对话角色（如系统、用户、函数、助手）定义了消息类别。
尽管术语 MessageType 可能暗示特定消息格式，但在此上下文中，它实际表示消息在对话中扮演的角色 。
对于不使用特定角色的 AI 模型，UserMessage 实现作为标准类别，通常代表用户生成的查询或指令。有关 Prompt 与 Message 的实际应用及角色关系，请参阅 Prompts 章节。

聊天选项（Chat Options）

ChatOptions 类表示可传递给 AI 模型的配置项，是 ModelOptions 的子类，定义了可移植的通用参数：

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 聊天补全模型支持 logitBias、seed 和 user 等参数。
此设计允许开发者在启动时配置模型默认参数，并在运行时通过 Prompt 动态覆盖，提升灵活性。

Spring AI 通过分层配置系统管理聊天模型：

• 启动配置
  ChatModel/StreamingChatModel 初始化时使用全局默认参数（如 temperature=0.7）。
• 运行时配置
  每个 Prompt 可携带覆盖默认值的参数（如 temperature=0.2）。
• 选项合并
  系统合并启动配置与运行时配置，后者优先级更高。
• 输入/输出处理
  输入指令被转换为模型原生格式，输出则统一为 ChatResponse 格式。
  此机制实现了全局配置与请求级调整的平衡，支持跨模型参数适配 。
  

流程图说明

• Start-Up Options ：初始化时的默认配置。
• Runtime Options ：单次请求的动态覆盖。
• Merge Options ：合并策略（运行时参数优先）。
• Convert Input/Output ：适配模型输入输出格式。

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

public class Generation implements ModelResult<AssistantMessage> {

    private final AssistantMessage assistantMessage;
    private ChatGenerationMetadata chatGenerationMetadata;

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

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

    // 其他方法省略
}

• assistantMessage：模型生成的助手消息内容 。
• chatGenerationMetadata：生成过程的元数据（如令牌数、生成时间等）。
• getOutput() 返回助手消息，getMetadata() 返回生成元数据

可用实现

下图展示了统一的接口 ChatModel 和 StreamingChatModel 如何与不同供应商的 AI 聊天模型交互，支持轻松集成和切换各类 AI 服务，同时为客户端应用提供一致的 API。

Spring AI 聊天补全客户端支持列表

• OpenAI 聊天补全 （支持流式传输、多模态及函数调用）
• Microsoft Azure OpenAI 聊天补全 （支持流式传输及函数调用）
• Ollama 聊天补全 （支持流式传输、多模态及函数调用）
• Hugging Face 聊天补全 （不支持流式传输）
• Google Vertex AI Gemini 聊天补全 （支持流式传输、多模态及函数调用）
• Amazon Bedrock
• Mistral AI 聊天补全 （支持流式传输及函数调用）
• Anthropic 聊天补全 （支持流式传输及函数调用）
  各模型的详细功能对比请参阅 聊天模型对比 部分 。

聊天模型 API

Spring AI 聊天模型 API 基于 Spring AI 通用模型 API 构建，提供针对聊天场景的抽象和实现。它支持无缝集成和切换不同 AI 服务，同时为客户端应用保持统一的 API。以下类图展示了 Spring AI 聊天模型 API 的核心类与接口：

• 核心接口 ：ChatModel（单次响应）和 StreamingChatModel（流式响应）
• 输入封装 ：Prompt（包含消息列表和配置）
• 输出处理 ：ChatResponse 和 Generation（含助手消息及元数据）

该设计延续了 Spring 框架的模块化理念，允许通过最小代码改动切换底层模型