Spring AI 第三讲Embeddings（嵌入式） Model API 第一讲Ollama 嵌入

有了 Ollama，你可以在本地运行各种大型语言模型 (LLM)，并从中生成嵌入。Spring AI 通过 OllamaEmbeddingModel 支持 Ollama 文本嵌入。

嵌入是一个浮点数向量（列表）。两个向量之间的距离可以衡量它们之间的相关性。距离小表示关联度高，距离大表示关联度低。

前提条件

首先需要在本地计算机上运行 Ollama。

请参阅官方 Ollama 项目 README，开始在本地计算机上运行模型。

安装 Ollama 运行 llama3 将下载一个 4.7GB 的模型工件。

添加资源库和 BOM

Spring AI 工件发布在 Spring Milestone 和 Snapshot 资源库中。请参阅 "资源库"部分，将这些资源库添加到您的构建系统中。

为了帮助进行依赖性管理，Spring AI 提供了一个 BOM（物料清单），以确保在整个项目中使用一致的 Spring AI 版本。请参阅 "依赖关系管理 "部分，将 Spring AI BOM 添加到构建系统中。

自动配置

Spring AI 为 Azure Ollama 嵌入式客户端提供 Spring Boot 自动配置功能。要启用它，请在 Maven pom.xml 文件中添加以下依赖关系：

<dependency>
   <groupId>org.springframework.ai</groupId>
   <artifactId>spring-ai-ollama-spring-boot-starter</artifactId>
</dependency>

或 Gradle build.gradle 构建文件。

dependencies {
    implementation 'org.springframework.ai:spring-ai-ollama-spring-boot-starter'
}

请参阅 "依赖关系管理 "部分，将 Spring AI BOM 添加到构建文件中

spring.ai.ollama.embedding.options.* 属性用于配置所有嵌入请求的默认选项。(它作为 OllamaEmbeddingModel#withDefaultOptions() 实例使用）。

嵌入属性

前缀 spring.ai.ollama 是配置与 Ollama 连接的属性前缀
PropertyDescriptionDefault
spring.ai.ollama.base-url
运行 Ollama API 服务器的基本 URL。

localhost:11434

The prefix

spring.ai.ollama.embedding.options

is the property prefix that configures the

EmbeddingModel

implementation for Ollama.
PropertyDescriptionDefault
spring.ai.ollama.embedding.enabled
启用 Ollama 嵌入模型。
true

spring.ai.ollama.embedding.options.model
要使用的支持模型名称。
mistral

其余选项属性基于 Ollama 有效参数和值以及Ollama 类型。默认值基于Ollama 类型默认值。

Property

Description

Default

spring.ai.ollama.embedding.options.numa
是否使用 NUMA。
false

spring.ai.ollama.embedding.options.num-ctx
设置用于生成下一个标记的上下文窗口的大小。
2048

spring.ai.ollama.embedding.options.num-batch

spring.ai.ollama.embedding.options.num-gqa
变压器层中 GQA 组的数量。某些型号需要，例如 llama2:70b 为 8。
-

spring.ai.ollama.embedding.options.num-gpu
要发送到 GPU 的层数。在 macOS 上，默认值为 1 表示启用金属支持，0 表示禁用。
-

spring.ai.ollama.embedding.options.main-gpu

spring.ai.ollama.embedding.options.low-vram

spring.ai.ollama.embedding.options.f16-kv

spring.ai.ollama.embedding.options.logits-all

spring.ai.ollama.embedding.options.vocab-only

spring.ai.ollama.embedding.options.use-mmap

spring.ai.ollama.embedding.options.use-mlock

spring.ai.ollama.embedding.options.num-thread
设置计算时使用的线程数。默认情况下，Ollama 会检测线程数以获得最佳性能。建议将此值设置为系统的物理 CPU 内核数（而非逻辑内核数）。
-

spring.ai.ollama.embedding.options.num-keep

spring.ai.ollama.embedding.options.seed
设置生成文本时使用的随机数种子。将其设置为一个特定的数字将使模型为相同的提示生成相同的文本。
0

spring.ai.ollama.embedding.options.num-predict
生成文本时要预测的最大标记数。(默认值：128，-1 = 无限生成，-2 = 填充上下文）
128

spring.ai.ollama.embedding.options.top-k
降低产生无意义答案的概率。数值越大（如 100），答案就越多样化，而数值越小（如 10），答案就越保守。
40

spring.ai.ollama.embedding.options.top-p
与 top-k 一起使用。较高的值（如 0.95）将产生更多样化的文本，而较低的值（如 0.5）将产生更集中和保守的文本。
0.9

spring.ai.ollama.embedding.options.tfs-z
无尾采样用于减少输出中可能性较低的标记的影响。数值越大（例如 2.0），影响越小，而数值为 1.0 时，则会禁用此设置。
1

spring.ai.ollama.embedding.options.typical-p

spring.ai.ollama.embedding.options.repeat-last-n
设置模型回溯多远以防止重复。(默认值：64，0 = 禁用，-1 = num_ctx）
64

spring.ai.ollama.embedding.options.temperature
模型的温度。温度越高，模型的答案越有创意。
0.8

spring.ai.ollama.embedding.options.repeat-penalty
设置对重复的惩罚力度。数值越大（如 1.5），对重复的惩罚力度就越大，而数值越小（如 0.9），惩罚力度就越宽松。
1.1

spring.ai.ollama.embedding.options.presence-penalty

spring.ai.ollama.embedding.options.frequency-penalty

spring.ai.ollama.embedding.options.mirostat
启用 Mirostat 采样以控制复杂度。(默认值：0，0 = 禁用，1 = Mirostat，2 = Mirostat 2.0）
0

spring.ai.ollama.embedding.options.mirostat-tau
控制输出的连贯性和多样性之间的平衡。数值越小，文字越集中、连贯。
5.0

spring.ai.ollama.embedding.options.mirostat-eta
影响算法对生成文本的反馈做出反应的速度。学习率越低，算法的调整速度就越慢，而学习率越高，算法的反应速度就越快。
0.1

spring.ai.ollama.embedding.options.penalize-newline

spring.ai.ollama.embedding.options.stop
设置要使用的停止序列。遇到这种模式时，LLM 将停止生成文本并返回。可以通过在模型文件中指定多个单独的停止参数来设置多个停止模式。
-

所有以 spring.ai.ollama.embedding.options 为前缀的属性都可以通过在 EmbeddingRequest 调用中添加特定于请求的 Runtime Options 来在运行时重写。

运行时选项

OllamaOptions.java 提供了 Ollama 配置，如要使用的模型、底层 GPU 和 CPU 调整等。

默认选项也可使用 spring.ai.ollama.embedding.options 属性进行配置。

启动时，使用 OllamaEmbeddingModel#withDefaultOptions() 配置用于所有嵌入请求的默认选项。在运行时，你可以使用作为 EmbeddingRequest 一部分的 OllamaOptions 实例来覆盖默认选项。

例如，要覆盖特定请求的默认模型名称：

EmbeddingResponse embeddingResponse = embeddingModel.call(
    new EmbeddingRequest(List.of("Hello World", "World is big and salvation is near"),
        OllamaOptions.create()
            .withModel("Different-Embedding-Model-Deployment-Name"));

示例Controller

这将创建一个 EmbeddingModel 实现，您可以将其注入到您的类中。下面是一个使用 EmbeddingModel 实现的简单 @Controller 类示例。

@RestController
public class EmbeddingController {

    private final EmbeddingModel embeddingModel;

    @Autowired
    public EmbeddingController(EmbeddingModel embeddingModel) {
        this.embeddingModel = embeddingModel;
    }

    @GetMapping("/ai/embedding")
    public Map embed(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
        EmbeddingResponse embeddingResponse = this.embeddingModel.embedForResponse(List.of(message));
        return Map.of("embedding", embeddingResponse);
    }
}

手动配置

如果不使用 Spring Boot，可以手动配置 OllamaEmbeddingModel。为此，请在项目的 Maven pom.xml 文件中添加 spring-ai-ollama 依赖关系：

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-ollama</artifactId>
</dependency>

或 Gradle build.gradle 构建文件。

dependencies {
    implementation 'org.springframework.ai:spring-ai-ollama'
}

请参阅 "依赖关系管理 "部分，将 Spring AI BOM 添加到构建文件中。

spring-ai-ollama 依赖关系还提供对 OllamaChatModel 的访问。有关 OllamaChatModel 的更多信息，请参阅Ollama Chat Client 部分。

接下来，创建一个 OllamaEmbeddingModel 实例，并用它来计算两个输入文本之间的相似度：

var ollamaApi = new OllamaApi();

var embeddingModel = new OllamaEmbeddingModel(ollamaApi)
    .withDefaultOptions(OllamaOptions.create()
            .withModel(OllamaOptions.DEFAULT_MODEL)
            .toMap());

EmbeddingResponse embeddingResponse = embeddingModel
    .embedForResponse(List.of("Hello World", "World is big and salvation is near"));

OllamaOptions 为所有嵌入请求提供配置信息。