Spring AI Alibaba 05｜Models 模型 · Chat Model API

Chat Model API 构建在 Generic Model API 之上，提供 Chat 特定的抽象和实现。本节提供 Spring AI ChatModel API 接口和相关类的指南。

ChatModel

ChatModel 接口扩展了 Model<Prompt, ChatResponse> 和 StreamingChatModel，提供了与 AI 模型交互的统一接口。

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 接口扩展了 StreamingModel<Prompt, ChatResponse>，提供了流式响应的能力。

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 是一个封装了 Message 对象列表和可选模型请求选项的 ModelRequest。以下是 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 模型可以处理的消息类别：

主要消息类型包括：

• UserMessage: 用户消息
• SystemMessage: 系统消息
• AssistantMessage: 助手消息
• FunctionMessage: 函数消息
• ToolResponseMessage: 工具响应消息

聊天完成端点根据对话角色区分消息类别，由 MessageType 有效映射。

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

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

对于不使用特定角色的 AI 模型，UserMessage 实现充当标准类别，通常表示用户生成的查询或指令。

ChatOptions

表示可以传递给 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();
}

常用选项说明：

• model: 要使用的模型 ID
• frequencyPenalty: 频率惩罚（-2.0 到 2.0），降低重复令牌的可能性
• maxTokens: 生成响应的最大令牌数
• presencePenalty: 存在惩罚（-2.0 到 2.0），鼓励谈论新主题
• stopSequences: 停止序列列表，遇到时停止生成
• temperature: 采样温度（0.0 到 2.0），控制随机性
• topK: Top-K 采样参数
• topP: Top-P（核采样）参数

此外，每个特定模型的 ChatModel/StreamingChatModel 实现都可以有自己的选项。例如，OpenAI Chat Completion 模型有自己的选项，如 logitBias、seed 和 user。

这是一个强大的功能，允许开发者在启动应用程序时使用特定于模型的选项，然后在运行时使用 Prompt 请求覆盖它们。

Spring AI 提供了一个复杂的系统来配置和使用 ChatModels。它允许在启动时设置默认配置，同时还提供了在每个请求基础上覆盖这些设置的灵活性。

选项合并流程：

1. 启动配置 – ChatModel/StreamingChatModel 使用”启动”ChatOptions 初始化。这些选项在 ChatModel 初始化期间设置，旨在提供默认配置。
2. 运行时配置 – 对于每个请求，Prompt 可以包含运行时 ChatOptions，这些可以覆盖启动选项。
3. 选项合并过程 – “合并选项”步骤结合启动和运行时选项。如果提供了运行时选项，它们优先于启动选项。
4. 输入处理 – “转换输入”步骤将输入指令转换为本地的、特定于模型的格式。
5. 输出处理 – “转换输出”步骤将模型的响应转换为标准化的 ChatResponse 格式。

启动和运行时选项的分离允许全局配置和特定于请求的调整。

以下流程图说明了 Spring AI 如何处理 Chat Models 的配置和执行，结合启动和运行时选项：

这种设计符合 Spring 的模块化和可互换性理念，使开发人员能够轻松地使用不同的 AI model 并根据需要调整参数，所有这些都在 Spring AI 框架提供的统一接口内。

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

  // 其他方法省略
}

Spring AI 提供了与多个 AI 服务提供商的集成，所有这些都通过统一的 ChatModel 和 StreamingChatModel 接口进行交互。这种设计允许轻松集成和在不同 AI 服务之间切换，同时为客户端应用程序维护一致的 API。

以下图表说明了统一的接口 ChatModel 和 StreamingChatModel 用于与来自不同提供商的各种 AI chat model 交互：

支持的模型提供商

• OpenAI Chat Completion (支持流式、多模态和函数调用)
• Microsoft Azure OpenAI Chat Completion (支持流式和函数调用)
• Alibaba DashScope Chat Completion (支持流式和函数调用)
• Ollama Chat Completion (支持流式、多模态和函数调用)
• Hugging Face Chat Completion (不支持流式)
• Google Vertex AI Gemini Chat Completion (支持流式、多模态和函数调用)
• Amazon Bedrock
• Mistral AI Chat Completion (支持流式和函数调用)
• Anthropic Chat Completion (支持流式和函数调用)

关于每个模型的具体用法与特性，请查看 Spring AI Alibaba 模型适配文档。

API 架构

Spring AI Chat Model API 构建在 Spring AI Generic Model API 之上，提供 Chat 特定的抽象和实现。以下类图说明了 Spring AI Chat Model API 的主要类和接口：

本文整理自 Spring AI Alibaba 官方文档《Models 模型》：https://java2ai.com/docs/frameworks/agent-framework/tutorials/models