嵌入式 API

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

EmbeddingClient 接口的设计围绕着两个主要目标：

可移植性：该接口确保易于在各种嵌入模型之间进行适配。它允许开发人员在不进行大量代码更改的情况下切换不同的嵌入技术或模型。这种设计符合 Spring 的模块化和可互换性理念。
简易性：EmbeddingClient 简化了将文本转换为嵌入的过程。通过提供诸如 embed(String text) 和 embed(Document document) 等直接的方法，它消除了处理原始文本数据和嵌入算法的复杂性。这种设计选择使得开发人员，尤其是那些对 AI 新手，能够在应用程序中利用嵌入，而无需深入了解底层机制。

API 概述

嵌入 API 建立在泛型的Spring AI 模型 API之上，是 Spring AI 库的一部分。因此，EmbeddingClient 接口扩展了 ModelClient 接口，为与 AI 模型交互提供了一组标准方法。EmbeddingRequest 和 EmbeddingResponse 类扩展自 ModelRequest 和 ModelResponse，分别用于封装嵌入模型的输入和输出。

嵌入 API 同样用于高级组件实现特定嵌入模型（如OpenAI、Titan、Azure OpenAI、Ollie等）的嵌入客户端。

以下图示展示了嵌入 API 及其与 Spring AI 模型 API 和嵌入客户端的关系：

embeddings api

EmbeddingClient

本节提供了 EmbeddingClient 接口及其关联类的指南。


public interface EmbeddingClient extends ModelClient<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.
	 */
	List<Double> embed(Document document);

	/**
	 * Embeds the given text into a vector.
	 * @param text the text to embed.
	 * @return the embedded vector.
	 */
	default List<Double> embed(String text) {
		Assert.notNull(text, "文本不能为空");
		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<List<Double>> embed(List<String> texts) {
		Assert.notNull(texts, "Texts 不能为空");
		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 不能为空");
		return this.call(new EmbeddingRequest(texts, EmbeddingOptions.EMPTY));
	}

	/**
	 * @return 嵌入向量的维数，它是生成特定的。
	 */
	default int dimensions() {
		return embed("Test String").size();
	}
}

embed 方法提供了将文本转换为嵌入的各种选项，适用于单个字符串、结构化 Document 对象或文本批处理。

为嵌入文本提供了多种快捷方式方法，包括 embed(String text) 方法，它接受单个字符串并返回相应的嵌入向量。所有快捷方式都是在主要的调用嵌入模型的 call 方法周围实现的。

通常，嵌入会返回一组双倍列表，代表一组数值向量中的嵌入。

embedForResponse 方法提供了更全面的输出，可能包括有关嵌入的其他信息。

维数方法是开发人员快速确定嵌入向量大小的有用工具，这对于了解嵌入空间和后续处理步骤非常重要。

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 模型的输出，每个 Embedding 实例均包含来自单个文本输入的结果向量数据。

EmbeddingResponse 类还附带有关 AI 模型响应的 EmbeddingResponseMetadata 元数据信息。

Embedding

Embedding 表示单个嵌入向量。

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

可用的实现

内部各种EmbeddingClient 实现使用不同的低级库和API来执行嵌入任务。以下是一些可用的 EmbeddingClient 实现：