Embeddings API
EmbeddingClient 接口旨在直接与 AI 和机器学习中的嵌入模型集成。其主要功能是将文本转换为数字向量，通常称为嵌入。这些嵌入对于语义分析和文本分类等各种任务至关重要。
EmbeddingClient 接口的设计围绕着两个主要目标：
-
Portability：此接口确保了跨各种嵌入模型的轻松适应性。它允许开发人员在不同的嵌入技术或模型之间切换，同时仅需进行最少的代码更改。此设计符合 Spring 的模块化和可互换性理念。
-
Simplicity：EmbeddingClient 简化了将文本转换为嵌入的过程。通过提供诸如
embed(String text)和embed(Document document)之类的直接方法，它消除了处理原始文本数据和嵌入算法的复杂性。这样的设计选择使得开发人员（尤其是 AI 新手）能够在不深入了解底层机制的情况下轻松在其应用程序中利用嵌入。
API Overview
Embedding API 构建在通用 Spring AI Model API之上，这是 Spring AI 库的一部分。因此，EmbeddingClient 接口扩展了 `ModelClient`接口，其中提供了用于与人工智能模型进行交互的一组标准方法。`EmbeddingRequest`和 `EmbeddingResponse`类从 `ModelRequest`和 `ModelResponse`扩展而来，分别用于封装嵌入模型的输入和输出。
Embedding API 反过来被更高级别的组件用于为特定的嵌入模型（如 OpenAI、Titan、Azure OpenAI、Ollie 等）实现嵌入客户端。
下图说明了嵌入 API 及其与 Spring AI 模型 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, "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 是一个接受文本对象列表和可选嵌入请求选项的 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。