Spring Al学习6：嵌入模型 API

嵌入（Embedding）是将文本、图像或视频转化为数值向量的技术，能够捕捉不同输入之间的语义关联。

嵌入技术通过将文本、图像和视频转换为浮点数数组（称为向量）来实现。这些向量专门用于捕捉文本、图像及视频的语义特征。嵌入数组的长度称为向量的维度。

通过计算两段文本向量表示之间的数值距离，应用程序可判定原始对象之间的相似度。

EmbeddingModel 接口专为 AI 和机器学习中的嵌入模型集成而设计，核心功能是将文本转换为数值向量（即嵌入向量）。这些嵌入向量在语义分析和文本分类等任务中具有关键作用。

EmbeddingModel 接口的设计聚焦两大核心目标：

可移植性：该接口确保能适配各类嵌入模型，开发者只需极少的代码修改即可切换不同嵌入技术或模型，这种设计与 Spring 的模块化、可互换理念一脉相承。简洁性：通过提供 embed(String text) 和 embed(Document document) 等直观方法，该接口将原始文本数据处理和嵌入算法调用的复杂性完全封装，显著降低了开发者（特别是 AI 初学者）的应用门槛，使其无需深入底层机制即可轻松使用嵌入功能。

API 概览

嵌入（Embedding）模型 API 构建于 Spring AI 通用模型 API 之上，作为 Spring AI 库的核心组件，其 EmbeddingModel 接口继承自基础 Model 接口 — 后者提供了与 AI 模型交互的标准方法集。专用类 EmbeddingRequest 和 EmbeddingResponse 分别继承自 ModelRequest 和 ModelResponse，用于封装嵌入模型的输入与输出数据。

该 Embedding API 继而会被高层组件调用，用于实现针对特定嵌入模型（如OpenAI、Titan、Azure OpenAI、Ollie 等）的定制化嵌入模型集成。

下图展示了 Embedding API 与 Spring AI 模型 API 及各类嵌入模型的关系架构：

EmbeddingModel

本节将系统讲解 EmbeddingModel 接口及其关联类的使用指南。

public interface EmbeddingModel extends Model<EmbeddingRequest, EmbeddingResponse> {

@Override
EmbeddingResponse call(EmbeddingRequest request);/*** Embeds the given document's content into a vector.* @param document the document to embed.* @return the embedded vector.*/
float[] embed(Document document);/*** Embeds the given text into a vector.* @param text the text to embed.* @return the embedded vector.*/
default float[] embed(String text) {Assert.notNull(text, "Text must not be null");return this.embed(List.of(text)).iterator().next();
}/*** Embeds a batch of texts into vectors.* @param texts list of texts to embed.* @return list of list of embedded vectors.*/
default List<float[]> embed(List<String> texts) {Assert.notNull(texts, "Texts must not be null");return this.call(new EmbeddingRequest(texts, EmbeddingOptions.EMPTY)).getResults().stream().map(Embedding::getOutput).toList();
}/*** Embeds a batch of texts into vectors and returns the {@link EmbeddingResponse}.* @param texts list of texts to embed.* @return the embedding response.*/
default EmbeddingResponse embedForResponse(List<String> texts) {Assert.notNull(texts, "Texts must not be null");return this.call(new EmbeddingRequest(texts, EmbeddingOptions.EMPTY));
}/*** @return the number of dimensions of the embedded vectors. It is generative* specific.*/
default int dimensions() {return embed("Test String").size();
}

}

embed 方法提供多种文本转嵌入向量的处理方式，支持单字符串、结构化 Document 对象以及批量文本的转换需求。

接口提供多种嵌入文本的快捷方法，包括 embed(String text) — 该方法接收单个字符串并返回对应嵌入向量。所有快捷方法均基于核心 call 方法实现，该方法是调用嵌入模型的主要入口。

嵌入操作通常返回浮点数列表，以数值向量形式表征文本的语义特征。

embedForResponse 方法提供更完整的输出结果，可能包含与嵌入向量相关的扩展元数据信息。

dimensions 方法能帮助开发者快速获取嵌入向量的维度大小，这对理解嵌入空间特征和后续处理流程至关重要。
EmbeddingRequest

EmbeddingRequest 作为 ModelRequest 的子类，接收文本对象列表及可选的嵌入请求参数。以下代码清单展示了该类的简化结构（省略构造函数和工具方法）：

public class EmbeddingRequest implements ModelRequest<List> {
private final List inputs;
private final EmbeddingOptions options;
// 其他方法省略
}

EmbeddingResponse

EmbeddingResponse 类的结构如下所示：

public class EmbeddingResponse implements ModelResponse {

private List<Embedding> embeddings;
private EmbeddingResponseMetadata metadata = new EmbeddingResponseMetadata();
// other methods omitted

}

EmbeddingResponse 类封装 AI 模型的输出结果，其中每个 Embedding 实例包含对应单个文本输入的嵌入向量数据。

EmbeddingResponse 类还附带 EmbeddingResponseMetadata 元数据，用于记录 AI 模型响应的相关信息。
Embedding

Embedding 类表征单个嵌入向量的数据结构。

public class Embedding implements ModelResult<float[]> {
private float[] embedding;
private Integer index;
private EmbeddingResultMetadata metadata;
// 其他方法省略
}

现有实现方案

各 EmbeddingModel 实现方案在底层采用不同的基础库和 API 执行嵌入任务，当前主要实现包括：

Spring AI OpenAI EmbeddingsSpring AI Azure OpenAI EmbeddingsSpring AI Ollama EmbeddingsSpring AI Transformers (ONNX) EmbeddingsSpring AI PostgresML EmbeddingsSpring AI Bedrock Cohere EmbeddingsSpring AI Bedrock Titan EmbeddingsSpring AI VertexAI EmbeddingsSpring AI Mistral AI EmbeddingsSpring AI Oracle Cloud Infrastructure GenAI Embeddings