嵌入模型 API
| 本站(springdoc.cn)中的内容来源于 spring.io ，原始版权归属于 spring.io。由 springdoc.cn 进行翻译，整理。可供个人学习、研究，未经许可，不得进行任何转载、商用或与之相关的行为。 商标声明：Spring 是 Pivotal Software, Inc. 在美国以及其他国家的商标。 |
嵌入（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<String>> {
private final List<String> inputs;
private final EmbeddingOptions options;
// 其他方法省略
}EmbeddingResponse
EmbeddingResponse 类的结构如下所示：
public class EmbeddingResponse implements ModelResponse<Embedding> {
private List<Embedding> embeddings;
private EmbeddingResponseMetadata metadata = new EmbeddingResponseMetadata();
// other methods omitted
}EmbeddingResponse 类封装 AI 模型的输出结果，其中每个 Embedding 实例包含对应单个文本输入的嵌入向量数据。
EmbeddingResponse 类还附带 EmbeddingResponseMetadata 元数据，用于记录 AI 模型响应的相关信息。
