|
此版本仍在开发中，尚未被视为稳定版。如需最新的快照版本，请使用 Spring AI 1.1.3！ |
嵌入模型 API
嵌入表示是文本、图像或视频的数值表示，能够捕捉输入之间的关系。
嵌入表示通过将文本、图像和视频转换为浮点数组成的向量来工作。 这些向量旨在捕捉文本、图像和视频的意义。 嵌入向量数组的长度称为该向量的维度。
通过计算两段文本的向量表示之间的数值距离，应用程序可以确定生成嵌入向量的对象之间的相似性。
EmbeddingModel 接口旨在实现与人工智能和机器学习中的嵌入模型的直接集成。
其主要功能是将文本转换为数值向量，通常称为嵌入。
这些嵌入对于语义分析和文本分类等各种任务至关重要。
EmbeddingModel 接口的设计围绕两个主要目标：
-
可移植性：此接口确保了在各种嵌入模型之间的轻松适配。 它允许开发者以最小的代码更改在不同的嵌入技术或模型之间切换。 这种设计与 Spring 的模块化和可互换性理念相一致。
-
简洁性：EmbeddingModel 简化了将文本转换为嵌入向量的过程。 通过提供像
embed(String text)和embed(Document document)这样直观的方法，它消除了处理原始文本数据和嵌入算法的复杂性。这一设计选择使得开发者（尤其是那些刚接触人工智能的开发者）能够更轻松地在应用程序中使用嵌入向量，而无需深入探究其底层机制。
API概述
嵌入模型 API 构建于通用的 Spring AI 模型 API 之上，后者是 Spring AI 库的一部分。
因此，EmbeddingModel 接口扩展了 Model 接口，该接口提供了一组与 AI 模型交互的标准方法。EmbeddingRequest 和 EmbeddingResponse 类分别继承自 ModelRequest 和 ModelResponse，用于封装嵌入模型的输入和输出。
嵌入 API 进而被更高层级的组件用于实现特定嵌入模型的嵌入模型，例如 OpenAI、Titan、Azure OpenAI、Ollie 等。
下图展示了嵌入 API 及其与 Spring AI 模型 API 和嵌入模型之间的关系：
嵌入模型
本节提供了关于 EmbeddingModel 接口及相关类的指南。
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);
/**
* Extracts the text content from a Document to be used for embedding.
* By default, returns Document.getText(). Implementations that support
* MetadataMode should override this to return
* Document.getFormattedContent(MetadataMode) so that metadata is
* included in the text sent to the embedding API.
*/
default String getEmbeddingContent(Document document) {
return document.getText();
}
/**
* 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();
}
}嵌入方法提供了多种将文本转换为嵌入向量的选项，支持单个字符串、结构化的 Document 对象或批量文本。
提供了多种用于文本嵌入的快捷方法，包括 embed(String text) 方法，该方法接收单个字符串并返回对应的嵌入向量。
所有快捷方法均围绕 call 方法实现，这是调用嵌入模型的主要方法。
getEmbeddingContent(Document) 方法控制在嵌入之前如何从 Document 中提取文本。
默认情况下，它返回 Document.getText()，但支持 MetadataMode 的嵌入模型实现（例如 OpenAI、Azure OpenAI 和 Mistral AI）会重写此方法以返回 Document.getFormattedContent(MetadataMode)，从而确保在配置时将文档元数据包含在发送到嵌入 API 的文本中。
该方法被向量存储所依赖的批量嵌入路径使用。
通常，嵌入返回一个浮点数列表，以数值向量格式表示嵌入。
embedForResponse 方法提供更全面的输出，可能包含关于嵌入的额外信息。
dimensions 方法是一个对开发者而言非常实用的工具，可快速确定嵌入向量的维度大小，这对于理解嵌入空间以及后续处理步骤至关重要。
嵌入请求
EmbeddingRequest 是一个 ModelRequest，它接受一个文本对象列表和可选的嵌入请求选项。
以下清单展示了 EmbeddingRequest 类的截断版本，不包括构造函数和其他实用方法：
public class EmbeddingRequest implements ModelRequest<List<String>> {
private final List<String> inputs;
private final EmbeddingOptions options;
// other methods omitted
}嵌入响应
EmbeddingResponse 类的结构如下：
public class EmbeddingResponse implements ModelResponse<Embedding> {
private List<Embedding> embeddings;
private EmbeddingResponseMetadata metadata = new EmbeddingResponseMetadata();
// other methods omitted
}EmbeddingResponse 类包含 AI 模型的输出，每个 Embedding 实例包含来自单个文本输入的结果向量数据。
来自Java开发中Spring AI框架文档网站的HTML内容翻译如下：
The EmbeddingResponse class also carries a EmbeddingResponseMetadata metadata about the AI Model’s response.