Embeddings API

Embeddings API

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

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

• 可移植性：该接口确保了跨各种嵌入模型的轻松适应性。它允许开发人员以最少的代码更改在不同的嵌入技术或模型之间切换。这种设计符合 Spring 的模块化和可互换性理念。

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

API概述

Embedding API 构建在通用的 Spring AI Model API 之上，后者是 Spring AI 库的一部分。因此，EmbeddingClient 接口扩展了 ModelClient 接口，它提供了一组用于与 AI 模型交互的标准方法。EmbeddingRequest 和 EmbeddingResponse 从 ModelRequest、ModelResponse 扩展而来，分别用于封装嵌入模型的输入和输出。

Embedding API 又被更高级别的组件用来实现特定嵌入模型的嵌入客户端，例如OpenAI 、Titan、Azure OpenAI、Ollie 等。

下图说明了 Embedding API 及其与 Spring AI Model API 和 Embedding Client 的关系：

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 类的截断版本，不包括构造函数和其他实用方法：

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

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 还包含 EmbeddingResponseMetadata 有关 AI 模型响应的元数据。

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：

• Spring AI OpenAI Embeddings
• 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