1. Spring AI API

Spring 提供了一套标准化 AI 开发接口，对各大 AI 厂商的 AI 能力做了统一封装，涵盖了丰富的功能模块，为便于整体了解，以下列出一些核心功能，后续会再单独详细介绍。

1.1 通用模型 API

提供可跨 AI 服务商通用的模型 API，适用于对话（Chat）、文本生成图片（Text to Image）、音频转写（Audio Transcription）、文本转语音（Text to Speech）以及嵌入（Embedding）模型。同时支持同步和流式 API 两种调用方式，也支持向下兼容调用各模型的专属功能。

支持对接多家厂商的 AI 模型，包括 OpenAI、微软、亚马逊、谷歌、Amazon Bedrock、Hugging Face 等。

1.1.1 Model

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

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);
}

1.1.2 StreamingModel

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

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);
}

1.1.3 ModelRequest

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

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();
}

1.1.4 ModelOptions

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

public interface ModelOptions {

}

1.1.5 ModelResponse

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

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();
}

1.1.6 ModelResult

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

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();
}

1.2 向量存储 API

提供可跨多家服务商通用的向量存储 API，包含一套创新性的类 SQL 元数据过滤 API（该 API 同样具备跨服务商通用性）。

目前已支持对接 14 种向量数据库。

1.3 工具调用 API

Spring AI 简化了 AI 模型调用自定义服务的流程。支持将标注 @Tool 注解的方法，或符合 POJO 规范的 java.util.Function 接口实现类作为服务，供 AI 模型直接调用。

1.4 自动配置

为 AI 模型和向量存储提供 Spring Boot 自动配置能力及专属启动器（Starters）。

1.5 ETL 数据工程

提供面向数据工程场景的 ETL 框架，该框架为将数据加载至向量数据库提供核心基础能力，助力实现检索增强生成（RAG） 模式， 通过该模式可将自定义数据输入至 AI 模型，使其融入模型的响应结果中。

2. 对话模型

2.1 支持的模型

AI 对话模型（AI Chat Model）是专门为「人机交互式对话」设计的人工智能模型。Spring AI 支持 20 + 主流对话模型提供商，覆盖商业、开源本地部署和代理服务三大类别。

不分对话模型功能对比表：

提供商	多模态支持	工具/函数调用	流式输出	重试机制	可观测性	内置JSON输出	本地部署	兼容OpenAI API
Anthropic Claude	文本、PDF、图片	√	√	√	√	×	×	×
Azure OpenAI	文本、图片	√	√	√	√	√	×	√
DeepSeek（OpenAI 代理）	文本	√	√	√	√	√	×	√
Google GenAI	文本、PDF、图片、音频、视频	√	√	√	√	×	×	×
Google VertexAI Gemini	文本、PDF、图片、音频、视频	√	√	√	√	×	×	√
Groq（OpenAI 代理）	文本、图片	√	√	√	√	×	×	√
HuggingFace	文本	×	×	×	×	×	×	×
Mistral AI	文本、图片、音频	√	√	√	√	×	×	√
MiniMax	文本	√	√	√	√	×	×	√
Moonshot AI（月之暗面）	文本	√	√	√	√	×	×	×
NVIDIA（OpenAI 代理）	文本、图片	√	√	√	√	×	×	√
OCI GenAI/Cohere	文本	×	×	×	√	×	×	×
Ollama	文本、图片	√	√	√	√	√	√	√
OpenAI SDK（官方）	输入：文本、图片、音频 输出：文本、音频	√	√	√	√	×	×	√
OpenAI	输入：文本、图片、音频 输出：文本、音频	√	√	√	√	×	×	√
Perplexity（OpenAI 代理）	文本	×	√	√	√	×	×	√
百度千帆（QianFan）	文本	×	√	√	√	×	×	×
智谱AI（ZhiPu AI）	文本、图片、文档	√	√	√	√	×	×	×
Amazon Bedrock Converse	文本、图片、视频、文档（PDF、HTML、MD、DOCX 等）	√	√	√	√	×	×	×

对比项说明：

• 多模态：模型能够处理的输入类型（例如，文本、图像、音频、视频）。
• 工具/函数调用：模型是否支持函数调用或工具使用。
• 流式响应：如果模型提供了流式回应。
• 重试：支持重试机制。
• 可观察性：用于监控和调试的功能。
• 内置JSON：原生支持JSON输出。
• 本地部署：模型是否可以本地运行。
• OpenAI API 兼容性：如果模型与 OpenAI 的 API 兼容。

2.1 对话模型 API

Spring AI 对话模型 API 构建于 Spring AI 通用模型 API 之上，提供了面向对话场景的专用抽象与实现。这使得应用可以轻松集成和切换不同的 AI 服务，同时为客户端应用保持一致的 API。

下面的类图展示了 Spring AI 对话模型 API 的主要类与接口：

2.1.1 ChatModel

ChatModel 是大模型交互的底层核心接口，只做最基础的事，它不处理任何附加逻辑，是所有上层功能的基础：

• 接收你的提示词请求
• 调用大模型 API
• 返回原始回答

ChatModel 接口定义：

public interface ChatModel extends Model<Prompt, ChatResponse>, StreamingChatModel {

    default String call(String message) {...}

    @Override
    ChatResponse call(Prompt prompt);
}

带字符串参数的 call () 方法简化了初期使用流程，规避了更为复杂的 Prompt 类和 ChatResponse 类带来的使用难度。在实际业务应用中，更常用的是接收 Prompt 实例作为参数、并返回 ChatResponse 对象的 call () 方法。

2.2.2 StreamingChatModel

ChatModel 接口继承自 StreamingChatModel ，它是是 Spring AI 中专门用于流式响应场景的对话模型接口：

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 以流式方式返回响应结果。

2.2.3 Prompt

Prompt 是一种 ModelRequest（模型请求），它封装了一个 Message 对象列表以及可选的模型请求配置项。

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
}

2.2.4 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 模型可处理的不同消息类别：

2.2.5 ChatOptions

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();

}

每个模型专属的 ChatModel/StreamingChatModel 实现类都可定义自身专属的配置项，并传递给 AI 模型。例如，OpenAI 聊天补全模型包含 logitBias、seed、user 等专属配置项。

2.2.6 ChatResponse

ChatResponse 类用于承载 AI 模型的输出结果，类的结构定义如下：

public class ChatResponse implements ModelResponse<Generation> {

 private final ChatResponseMetadata chatResponseMetadata;
    private final List<Generation> generations;

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

    @Override
    public List<Generation> getResults() {...}

    // other methods omitted
}

2.2.7 Generation

Generation 类继承自 ModelResult，用于表示模型输出（助手消息），该类还包含一个 ChatResponseMetadata 类型的元数据对象，用于存储关于 AI 模型响应的元信息：

public class Generation implements ModelResult<AssistantMessage> {

    private final AssistantMessage assistantMessage;
    private ChatGenerationMetadata chatGenerationMetadata;

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

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

    // other methods omitted
}