此版本仍在开发中，尚未被视为稳定版本。最新的快照版本请使用 Spring AI 1.0.0-SNAPSHOT！spring-doc.cn

嵌入模型 API

嵌入是文本、图像或视频的数字表示形式，用于捕获输入之间的关系。spring-doc.cn

嵌入的工作原理是将文本、图像和视频转换为浮点数数组（称为向量）。 这些矢量旨在捕获文本、图像和视频的含义。 嵌入数组的长度称为向量的维数。spring-doc.cn

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

该界面旨在与 AI 和机器学习中的嵌入模型直接集成。 它的主要功能是将文本转换为数字向量，通常称为嵌入向量。 这些嵌入对于各种任务（如语义分析和文本分类）至关重要。EmbeddingModelspring-doc.cn

EmbeddingModel 接口的设计围绕两个主要目标：spring-doc.cn

  • 可移植性：此界面可确保在各种嵌入模型中轻松适应。 它允许开发人员在不同的嵌入技术或模型之间切换，只需更改最少的代码。 这种设计与 Spring 的模块化和可互换性理念一致。spring-doc.cn

  • 简单性：EmbeddingModel 简化了将文本转换为嵌入的过程。 通过提供像 和 这样的简单方法，它消除了处理原始文本数据和嵌入算法的复杂性。这种设计选择使开发人员（尤其是 AI 新手）可以更轻松地在其应用程序中利用嵌入，而无需深入研究底层机制。embed(String text)embed(Document document)spring-doc.cn

API 概述

嵌入模型 API 构建在通用 Spring AI 模型 API 之上，后者是 Spring AI 库的一部分。 因此，EmbeddingModel 接口扩展了该接口，该接口提供了一组用于与 AI 模型交互的标准方法。和 类扩展自 和 分别用于封装嵌入模型的输入和输出。ModelEmbeddingRequestEmbeddingResponseModelRequestModelResponsespring-doc.cn

嵌入 API 反过来由更高级别的组件用于为特定嵌入模型（如 OpenAI、Titan、Azure OpenAI、Ollie 等）实施嵌入模型。spring-doc.cn

下图说明了嵌入 API 及其与 Spring AI 模型 API 和嵌入模型的关系：spring-doc.cn

嵌入 APIspring-doc.cn

EmbeddingModel

本节提供了接口和关联类的指南。EmbeddingModelspring-doc.cn

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

}

嵌入方法提供了各种选项，用于将文本转换为嵌入，以适应单个字符串、结构化对象或批量文本。Documentspring-doc.cn

提供了多种用于嵌入文本的快捷方法，包括采用单个字符串并返回相应嵌入向量的方法。 所有快捷方式都是围绕该方法实现的，这是调用嵌入模型的主要方法。embed(String text)callspring-doc.cn

通常，嵌入向量会返回一个浮点数列表，以数字向量格式表示嵌入向量。spring-doc.cn

该方法提供更全面的输出，可能包括有关嵌入的其他信息。embedForResponsespring-doc.cn

dimensions 方法是开发人员快速确定嵌入向量大小的便捷工具，这对于理解嵌入空间和后续处理步骤非常重要。spring-doc.cn

嵌入请求

它是一个采用文本对象列表和可选嵌入请求选项的 ID。 下面的清单显示了 EmbeddingRequest 类的截断版本，不包括构造函数和其他 Util 方法：EmbeddingRequestModelRequestspring-doc.cn

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

EmbeddingResponse

该类的结构如下：EmbeddingResponsespring-doc.cn

public class EmbeddingResponse implements ModelResponse<Embedding> {

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

该类保存 AI 模型的输出，每个实例都包含来自单个文本输入的结果向量数据。EmbeddingResponseEmbeddingspring-doc.cn

该类还携带有关 AI 模型响应的元数据。EmbeddingResponseEmbeddingResponseMetadataspring-doc.cn

嵌入

这表示单个嵌入向量。Embeddingspring-doc.cn

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

可用的实现

在内部，各种 implementation 使用不同的低级库和 API 来执行嵌入任务。以下是这些实施的一些可用实施：EmbeddingModelEmbeddingModelspring-doc.cn