【Spring AI】02. 嵌入向量 API

文章目录

[嵌入向量 API](#嵌入向量 API)
- [API 概述](#API 概述)
- - EmbeddingClient
- 可用实现

嵌入向量 API

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

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

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

API 概述

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

嵌入向量 API 反过来被更高级的组件使用，为特定的嵌入向量模型实现嵌入向量客户端，例如 OpenAI、Titan、Azure OpenAI、Ollie 等。

以下图示了嵌入向量 API 与 Spring AI 模型 API 和嵌入客户端之间的关系：

EmbeddingClient

本节提供了有关 EmbeddingClient 接口及相关类的指南。

java 复制代码

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, "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<List<Double>> 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方法实现，这是调用嵌入模型的主要方法。

通常嵌入返回一组双精度数，表示嵌入数值向量格式。

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

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

EmbeddingRequest

EmbeddingRequest 是一个接受文本对象列表和可选嵌入请求选项的类。以下显示了 EmbeddingRequest 类的缩略版本，不包括构造函数和其他实用方法：

java 复制代码

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

EmbeddingResponse

EmbeddingResponse 类的结构如下：

java 复制代码

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 代表一个单独的嵌入向量。

java 复制代码

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

可用实现

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

Spring AI Azure OpenAI Embeddings
Spring AI Ollama Embeddings
Spring AI Transformers (ONNX) Embeddings
Spring AI PostgresML Embeddings
Spring AI Bedrock Cohere Embeddings
Spring AI Bedrock Titan Embeddings
Spring AI VertexAI PaLM2 Embeddings
Spring AI Mistral AI Embeddings