跳到主要内容

Models 模型

概述​

ChatModel API 为开发者提供了将 AI 驱动的聊天补全功能集成到应用程序中的能力。它利用预训练的语言模型（如 GPT），根据用户的自然语言输入生成类似人类的响应。

该 API 通常通过向 AI 模型发送提示或部分对话来工作，然后模型根据其训练数据和对自然语言模式的理解生成对话的完成或延续。完成的响应随后返回给应用程序，应用程序可以将其呈现给用户或用于进一步处理。

Spring AI ChatModel API 被设计为一个简单且可移植的接口，用于与各种 AI 模型交互，允许开发者在不同模型之间切换时只需最少的代码更改。

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

Spring AI ChatModel API 构建在 Spring AI Generic Model API 之上，提供 Chat 特定的抽象和实现。这允许轻松集成和在不同 AI 服务之间切换，同时为客户端应用程序维护一致的 API。

Generic Model API​

为了为所有 AI Models 提供基础，Spring AI 创建了 Generic Model API。这使得通过遵循通用模式轻松地为 Spring AI 贡献新的 AI Model 支持。

以下类图展示了 Generic Model API 的架构：

Spring AI Generic Model API

Model​

Model 接口提供了调用 AI model 的通用 API。它旨在通过抽象发送请求和接收响应的过程来处理与各种类型的 AI model 的交互。该接口使用 Java 泛型来容纳不同类型的请求和响应，增强了不同 AI model 实现的灵活性和适应性。

Model 接口定义查看完整代码
public interface Model<TReq extends ModelRequest<?>, TRes extends ModelResponse<?>> {

  /**
   * Executes a method call to the AI model.
   * @param request the request object to be sent to the AI model
   * @return the response from the AI model
   */
  TRes call(TReq request);
}

StreamingModel​

StreamingModel 接口提供了调用具有流式响应的 AI model 的通用 API。它抽象了发送请求和接收流式响应的过程。

StreamingModel 接口定义查看完整代码
public interface StreamingModel<TReq extends ModelRequest<?>, TResChunk extends ModelResponse<?>> {

  /**
   * Executes a method call to the AI model.
   * @param request the request object to be sent to the AI model
   * @return the streaming response from the AI model
   */
  Flux<TResChunk> stream(TReq request);
}

ModelRequest​

ModelRequest 接口表示对 AI model 的请求。它封装了与 AI model 交互所需的信息，包括指令或输入（泛型类型 T）和附加的 model 选项。

ModelRequest 接口定义查看完整代码
public interface ModelRequest<T> {

  /**
   * Retrieves the instructions or input required by the AI model.
   * @return the instructions or input required by the AI model
   */
  T getInstructions(); // required input

  /**
   * Retrieves the customizable options for AI model interactions.
   * @return the customizable options for AI model interactions
   */
  ModelOptions getOptions();
}

ModelOptions​

ModelOptions 接口表示 AI model 交互的可自定义选项。此标记接口允许指定各种设置和参数，这些设置和参数可以影响 AI model 的行为和输出。

ModelOptions 接口定义查看完整代码
public interface ModelOptions {

}

ModelResponse​

ModelResponse 接口表示从 AI model 接收的响应。此接口提供访问 AI model 生成的主要结果或结果列表以及响应元数据的方法。

ModelResponse 接口定义查看完整代码
public interface ModelResponse<T extends ModelResult<?>> {

  /**
   * Retrieves the result of the AI model.
   * @return the result generated by the AI model
   */
  T getResult();

  /**
   * Retrieves the list of generated outputs by the AI model.
   * @return the list of generated outputs
   */
  List<T> getResults();

  /**
   * Retrieves the response metadata associated with the AI model's response.
   * @return the response metadata
   */
  ResponseMetadata getMetadata();
}

ModelResult​

ModelResult 接口提供访问 AI model 的主要输出和与此结果相关的元数据的方法。它旨在提供一种标准化和全面的方式来处理和解释 AI model 生成的输出。

ModelResult 接口定义查看完整代码
public interface ModelResult<T> {

  /**
   * Retrieves the output generated by the AI model.
   * @return the output generated by the AI model
   */
  T getOutput();

  /**
   * Retrieves the metadata associated with the result of an AI model.
   * @return the metadata associated with the result
   */
  ResultMetadata getMetadata();
}

Chat Model API​

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

ChatModel​

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

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

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 是一个封装了 Message 对象列表和可选模型请求选项的 ModelRequest。以下是 Prompt 类的简化版本，排除了构造函数和其他实用方法：

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 的分类。

接口定义如下：

Message 接口定义查看完整代码
public interface Content {

  String getText();

  Map<String, Object> getMetadata();
}

public interface Message extends Content {

  MessageType getMessageType();
}

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

MediaContent 接口定义查看完整代码
public interface MediaContent extends Content {

  Collection<Media> getMedia();
}

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

Spring AI Message API

主要消息类型包括：

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

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

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

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

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

ChatOptions​

表示可以传递给 AI 模型的选项。ChatOptions 类是 ModelOptions 的子类，用于定义可以传递给 AI 模型的少数可移植选项。ChatOptions 类定义如下：

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 的配置和执行，结合启动和运行时选项：

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

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

Generation 类定义查看完整代码
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 交互：

Spring AI Chat Completions Clients

支持的模型提供商​

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

API 架构​

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

Spring AI Chat API

DashScopeChatModel​

DashScope 是阿里云提供的大模型服务平台，提供通义千问等多个大语言模型。Spring AI Alibaba 提供了 DashScopeChatModel 的集成。

前置条件​

在使用 DashScopeChatModel 之前，你需要：

  1. 获取 DashScope API Key：访问 阿里云百炼
  2. 设置环境变量：export AI_DASHSCOPE_API_KEY=your_api_key

添加依赖​

<dependency>
    <groupId>com.alibaba.cloud.ai</groupId>
    <artifactId>spring-ai-alibaba-starter-dashscope</artifactId>
    <version>1.1.0.0-RC2</version>
</dependency>

基础使用​

创建 ChatModel​

创建 DashScopeChatModel查看完整代码
import com.alibaba.cloud.ai.dashscope.api.DashScopeApi;
import com.alibaba.cloud.ai.dashscope.chat.DashScopeChatModel;
import org.springframework.ai.chat.model.ChatModel;

// 创建 DashScope API 实例
DashScopeApi dashScopeApi = DashScopeApi.builder()
  .apiKey(System.getenv("AI_DASHSCOPE_API_KEY"))
  .build();

// 创建 ChatModel
ChatModel chatModel = DashScopeChatModel.builder()
  .dashScopeApi(dashScopeApi)
  .build();

简单调用​

简单调用示例查看完整代码
// 使用字符串直接调用
String response = chatModel.call("介绍一下Spring框架");
System.out.println(response);

使用 Prompt​

使用 Prompt 调用示例查看完整代码
import org.springframework.ai.chat.prompt.Prompt;
import org.springframework.ai.chat.messages.UserMessage;
import org.springframework.ai.chat.model.ChatResponse;

// 创建 Prompt
Prompt prompt = new Prompt(new UserMessage("解释什么是微服务架构"));

// 调用并获取响应
ChatResponse response = chatModel.call(prompt);
String answer = response.getResult().getOutput().getText();
System.out.println(answer);

配置选项​

使用 ChatOptions​

DashScopeChatOptions 配置示例查看完整代码
import com.alibaba.cloud.ai.dashscope.chat.DashScopeChatOptions;

DashScopeChatOptions options = DashScopeChatOptions.builder()
  .withModel("qwen-plus")           // 模型名称
  .withTemperature(0.7)              // Temperature 参数
  .withMaxToken(2000)                // 最大令牌数
  .withTopP(0.9)                     // Top-P 采样
  .build();

ChatModel chatModel = DashScopeChatModel.builder()
  .dashScopeApi(dashScopeApi)
  .defaultOptions(options)
  .build();

运行时覆盖选项​

运行时覆盖选项示例查看完整代码
// 创建带有特定选项的 Prompt
DashScopeChatOptions runtimeOptions = DashScopeChatOptions.builder()
  .withTemperature(0.3)  // 更低的温度，更确定的输出
  .withMaxToken(500)
  .build();

Prompt prompt = new Prompt(
  new UserMessage("用一句话总结Java的特点"),
  runtimeOptions
);

ChatResponse response = chatModel.call(prompt);

流式响应​

流式响应示例查看完整代码
import reactor.core.publisher.Flux;

// 使用流式 API
Flux<ChatResponse> responseStream = chatModel.stream(
  new Prompt("详细解释Spring Boot的自动配置原理")
);

// 订阅并处理流式响应
responseStream.subscribe(
  chatResponse -> {
      String content = chatResponse.getResult()
          .getOutput()
          .getText();
      System.out.print(content);
  },
  error -> System.err.println("错误: " + error.getMessage()),
  () -> System.out.println("
流式响应完成")
);

多轮对话​

多轮对话示例查看完整代码
import org.springframework.ai.chat.messages.Message;
import org.springframework.ai.chat.messages.SystemMessage;
import org.springframework.ai.chat.messages.AssistantMessage;
import java.util.List;

// 创建对话历史
List<Message> messages = List.of(
  new SystemMessage("你是一个Java专家"),
  new UserMessage("什么是Spring Boot?"),
  new AssistantMessage("Spring Boot是..."),
  new UserMessage("它有什么优势?")
);

Prompt prompt = new Prompt(messages);
ChatResponse response = chatModel.call(prompt);

支持的模型​

DashScope 支持多个模型，包括：

  • qwen-turbo: 通义千问超大规模语言模型，支持中文、英文等
  • qwen-plus: 通义千问增强版
  • qwen-max: 通义千问旗舰版
  • qwen-max-longcontext: 支持长文本的通义千问

函数调用​

DashScopeChatModel 支持函数调用（Function Calling），允许模型调用外部函数：

函数调用示例查看完整代码
import org.springframework.ai.chat.prompt.Prompt;
import org.springframework.ai.tool.ToolCallback;
import org.springframework.ai.tool.function.FunctionToolCallback;

// 定义函数工具
ToolCallback weatherFunction = FunctionToolCallback.builder("getWeather", (String city) -> {
      // 实际的天气查询逻辑
      return "晴朗，25°C";
  })
  .description("获取指定城市的天气")
  .inputType(String.class)
  .build();

// 使用函数
DashScopeChatOptions options = DashScopeChatOptions.builder()
  .withToolCallbacks(List.of(weatherFunction))
  .build();

Prompt prompt = new Prompt("北京的天气怎么样?", options);
ChatResponse response = chatModel.call(prompt);

与 ReactAgent 集成​

在 Spring AI Alibaba Agent Framework 中使用 DashScopeChatModel：

与 ReactAgent 集成示例查看完整代码
import com.alibaba.cloud.ai.graph.agent.ReactAgent;

ReactAgent agent = ReactAgent.builder()
  .name("my_agent")
  .model(chatModel)
  .systemPrompt("你是一个有帮助的AI助手")
  .build();

// 调用 Agent
AssistantMessage response = agent.call("帮我分析这个问题");

详细的 Agent 使用方法请参考 Agents 文档。

总结​

通过这个统一的 API，开发者可以轻松地在不同的 AI 服务提供商之间切换，同时保持代码的一致性和可维护性。

Spring AI Alibaba 开源项目基于 Spring AI 构建，是阿里云通义系列模型及服务在 Java AI 应用开发领域的最佳实践，提供高层次的 AI API 抽象与云原生基础设施集成方案，帮助开发者快速构建 AI 应用。