跳到主要内容
版本：2.0.1

嵌入模型 API

QWen 3.8 中英对照 Embedding Models Embeddings Model API

嵌入（Embeddings）是文本、图像或视频的数字表示，用于捕获输入之间的关系。

Embedding 通过将文本、图像和视频转换为浮点数数组（称为向量）来工作。这些向量旨在捕捉文本、图像和视频的含义。Embedding 数组的长度被称为向量的维度（dimensionality）。

通过计算两段文本的向量表示之间的数值距离，应用程序可以确定用于生成嵌入向量的对象之间的相似性。

EmbeddingModel 接口旨在简化与 AI 和机器学习领域中嵌入模型的集成。其主要功能是将文本转换为数值向量，通常称为 embeddings。这些 embeddings 对于语义分析和文本分类等任务至关重要。

EmbeddingModel 接口的设计围绕以下两个主要目标：

  • 可移植性：该接口确保能够轻松适配各种嵌入模型。它允许开发人员以最小的代码改动在不同的嵌入技术或模型之间进行切换。这种设计与 Spring 强调的模块化和可互换性理念相一致。

  • 简洁性：EmbeddingModel 简化了将文本转换为嵌入向量的过程。通过提供 embed(String text) 和 embed(Document document) 等直观的方法，它消除了处理原始文本数据和嵌入算法的复杂性。这一设计选择使得开发人员（尤其是 AI 新手）无需深入底层机制，即可在应用中轻松使用嵌入功能。

API 概览​

Embedding Model API 构建于通用的 Spring AI Model API 之上，它是 Spring AI 库的一部分。因此，EmbeddingModel 接口继承自 Model 接口，后者提供了一套用于与 AI 模型交互的标准方法。EmbeddingRequest 和 EmbeddingResponse 类分别继承自 ModelRequest 和 ModelResponse，用于分别封装嵌入模型的输入和输出。

Embedding API 则被更高层级的组件用于为特定的嵌入模型（例如 OpenAI、Titan、Ollie 以及其他）实现 Embedding Models。

下图展示了嵌入 API（Embedding API）及其与 Spring AI 模型 API 和嵌入模型（Embedding Models）之间的关系：

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

	/**
	 * Extracts the text content from a Document to be used for embedding.
	 * By default, returns Document.getText(). Implementations that support
	 * MetadataMode should override this to return
	 * Document.getFormattedContent(MetadataMode) so that metadata is
	 * included in the text sent to the embedding API.
	 */
	default String getEmbeddingContent(Document document) {
		return document.getText();
	}

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

}

嵌入方法提供了多种选项，用于将文本转换为嵌入向量，支持单个字符串、结构化的 Document 对象或文本批次。

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

getEmbeddingContent(Document) 方法用于控制在嵌入之前如何从 Document 中提取文本。默认情况下，它返回 Document.getText()，但支持 MetadataMode 的嵌入模型实现（如 OpenAI 或 Mistral AI）会重写此方法，返回 Document.getFormattedContent(MetadataMode)，从而确保在配置了元数据时，发送给嵌入 API 的文本中包含文档元数据。该方法被向量存储所依赖的批量嵌入路径使用。

通常，嵌入（embedding）会返回一个浮点数列表，表示以数值向量格式存储的嵌入。

embedForResponse 方法提供更全面的输出，可能包含有关嵌入的额外信息。

dimensions 方法是开发人员快速确定嵌入向量维度的便捷工具，这对于理解嵌入空间以及后续处理步骤至关重要。

EmbeddingRequest​

EmbeddingRequest 是一种 ModelRequest，它接收一个文本对象列表以及可选的嵌入请求选项。以下示例展示了 EmbeddingRequest 类的简化版本，其中省略了构造函数和其他实用方法：

public class EmbeddingRequest implements ModelRequest<List<String>> {
	private final List<String> inputs;
	private final EmbeddingOptions options;
	// other methods omitted
}

EmbeddingResponse​

EmbeddingResponse 类的结构如下：

public class EmbeddingResponse implements ModelResponse<Embedding> {

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

EmbeddingResponse 类用于保存 AI Model 的输出结果，其中每个 Embedding 实例包含来自单个文本输入的向量数据结果。

EmbeddingResponse 类还携带了关于 AI Model 响应的 EmbeddingResponseMetadata 元数据。

嵌入​

Embedding 表示单个嵌入向量。

public class Embedding implements ModelResult<float[]> {
	private float[] embedding;
	private Integer index;
	private EmbeddingResultMetadata metadata;
	// other methods omitted
}

可用实现​

内部实现中，不同的 EmbeddingModel 实现使用不同的底层库和 API 来执行嵌入任务。以下是部分可用的 EmbeddingModel 实现：

章节摘要​