Ollama 嵌入

借助 Ollama，你可以在本地运行各种 AI 模型 并从它们生成嵌入。 一个嵌入是一个浮点数的向量（列表）。 两个向量之间的距离衡量它们的相关性。 距离小表示相关性高，距离大表示相关性低。

OllamaEmbeddingModel 实现利用 Ollama 的 Embeddings API 端点。

前置条件

你首先需要一个可访问的 Ollama 实例。有几种方式，包括以下这些：

• 在本地机器上 下载并安装 Ollama。
• 配置并 通过 Testcontainers 运行 Ollama。

你可以从 Ollama 模型库 拉取你想在应用中使用模型：

ollama pull <model-name>

你也可以拉取数以千计的免费 GGUF Hugging Face 模型：

ollama pull hf.co/<username>/<model-repository>

或者，你可以启用自动下载任何所需模型的选项：自动拉取模型。

自动配置

NOTE

Spring AI 的自动配置、starter 模块的制品名称发生了重大变更。 更多信息请参阅 升级说明。

Spring AI 为 Ollama 嵌入模型提供 Spring Boot 自动配置。 要启用它，请将以下依赖添加到你的 Maven pom.xml 或 Gradle build.gradle 构建文件：

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

TIP

参见 依赖管理 一节，把 Spring AI BOM 添加到你的构建文件。

Spring AI 的制品发布在 Maven Central 和 Spring Snapshot 仓库中。 参见仓库一节，把这些仓库添加到你的构建系统。

基础属性

前缀 spring.ai.ollama 是配置连接到 Ollama 的属性前缀

属性	描述	默认值
spring.ai.ollama.base-url	运行 Ollama API 服务端的 Base URL。	+http://localhost:11434+

以下是初始化 Ollama 集成并 自动拉取模型 的属性。

属性	描述	默认值
spring.ai.ollama.init.pull-model-strategy	是否在启动时拉取模型以及如何拉取。	never
spring.ai.ollama.init.timeout	等待某个模型被拉取的时长。	5m
spring.ai.ollama.init.max-retries	模型拉取操作的最大重试次数。	0
spring.ai.ollama.init.embedding.include	将此类模型纳入初始化任务。	true
spring.ai.ollama.init.embedding.additional-models	除通过默认属性配置的模型之外，额外要初始化的模型。	[]

嵌入属性

NOTE

嵌入自动配置的启用与禁用，现已通过以 spring.ai.model.embedding 为前缀的顶层属性来配置。

要启用，spring.ai.model.embedding=ollama（默认启用）

要禁用，spring.ai.model.embedding=none（或任何不匹配 ollama 的值）

做出此变更是为了支持配置多个模型。

前缀 spring.ai.ollama.embedding 是配置 Ollama 嵌入模型的属性前缀。 它包含 Ollama 请求（高级）参数，如 model、keep-alive 和 truncate，以及 Ollama 模型属性。

以下是 Ollama 嵌入模型的高级请求参数：

属性	描述	默认值
spring.ai.ollama.embedding.enabled（已移除，不再生效）	启用 Ollama 嵌入模型的自动配置。	true
spring.ai.model.embedding	启用 Ollama 嵌入模型的自动配置。	ollama
spring.ai.ollama.embedding.model	要使用的 受支持模型 的名称。你可以使用专用的 Embedding Model 类型 | mxbai-embed-large	spring.ai.ollama.embedding.keep_alive
控制请求之后模型会在内存中保持加载多久	5m	spring.ai.ollama.embedding.truncate
截断每段输入的末尾以适配上下文长度。若为 false 且超出上下文长度则返回错误。	true

其余的 options 属性基于 Ollama 有效参数与取值 和 Ollama 类型。默认值基于：Ollama 类型默认值。

属性	描述	默认值
spring.ai.ollama.embedding.numa	是否使用 NUMA。	false
spring.ai.ollama.embedding.num-ctx	设置用于生成下一个令牌的上下文窗口大小。	2048
spring.ai.ollama.embedding.num-batch	提示词处理的最大批大小。	512
spring.ai.ollama.embedding.num-gpu	发送到 GPU 的层数。在 macOS 上默认为 1 以启用 metal 支持，为 0 则禁用。这里的 1 表示 NumGPU 应被动态设置	-1
spring.ai.ollama.embedding.main-gpu	使用多个 GPU 时，此选项控制哪个 GPU 用于那些把计算切分到所有 GPU 并不划算的小张量。该 GPU 会多用一点 VRAM 来存放一个用于临时结果的暂存缓冲区。	0
spring.ai.ollama.embedding.low-vram	-	false
spring.ai.ollama.embedding.f16-kv	-	true
spring.ai.ollama.embedding.logits-all	返回所有令牌的 logits，而不仅仅是最后一个。要启用补全返回 logprobs，此项必须为 true。	-
spring.ai.ollama.embedding.vocab-only	只加载词表，不加载权重。	-
spring.ai.ollama.embedding.use-mmap	默认情况下，模型被映射进内存，使系统能按需只加载模型的必要部分。然而，如果模型大于你的内存总量，或系统可用内存偏低，使用 mmap 可能会增加换页出去的风险，从而损害性能。禁用 mmap 会导致加载变慢，但若不 Using mlock 则可能减少换页。注意，如果模型大于内存总量，关闭 mmap 会使模型根本无法加载。	null
spring.ai.ollama.embedding.use-mlock	把模型锁定在内存中，防止其在内存映射时被换出。这能提升性能，但会牺牲内存映射的部分优势，需要更多内存运行，并可能因模型加载进内存而拖慢加载时间。	false
spring.ai.ollama.embedding.num-thread	设置计算期间使用的线程数。默认情况下，Ollama 会自动检测以获得最佳性能。建议把此值设为系统拥有的物理 CPU 核数（而非逻辑核数）。0 = 让运行时决定	0
spring.ai.ollama.embedding.num-keep	-	4
spring.ai.ollama.embedding.seed	设置生成时使用的随机数种子。把它设为特定值会让模型对相同提示词生成相同文本。	-1
spring.ai.ollama.embedding.num-predict	生成文本时要预测的最大令牌数。（-1 = 无限生成，-2 = 填满上下文）	-1
spring.ai.ollama.embedding.top-k	降低生成胡话的概率。较高的值（如 100）会给出更多样的答案，较低的值（如 10）会更保守。	40
spring.ai.ollama.embedding.top-p	与 top-k 协同工作。较高的值（如 0.95）会带来更多样的文本，较低的值（如 0.5）会生成更聚焦、更保守的文本。	0.9
spring.ai.ollama.embedding.min-p	top_p 的替代方案，旨在兼顾质量与多样性。参数 p 表示一个令牌被考虑时的最小概率，相对于最可能令牌的概率。例如，p=0.05 且最可能令牌概率为 0.9 时，值小于 0.045 的 logits 会被过滤掉。	0.0
spring.ai.ollama.embedding.tfs-z	无尾采样（tail-free sampling）用于降低低概率令牌对输出的影响。较高的值（如 2.0）会更大程度降低其影响，值为 1.0 则禁用此设置。	1.0
spring.ai.ollama.embedding.typical-p	-	1.0
spring.ai.ollama.embedding.repeat-last-n	设置模型回看多远以防止重复。（默认：64，0 = 禁用，-1 = num_ctx）	64
spring.ai.ollama.embedding.temperature	模型的温度。提高温度会让模型回答得更有创造性。	0.8
spring.ai.ollama.embedding.repeat-penalty	设置对重复的惩罚强度。较高的值（如 1.5）会更强烈地惩罚重复，较低的值（如 0.9）会更宽松。	1.1
spring.ai.ollama.embedding.presence-penalty	-	0.0
spring.ai.ollama.embedding.frequency-penalty	-	0.0
spring.ai.ollama.embedding.mirostat	启用 Mirostat 采样以控制困惑度。（默认：0，0 = 禁用，1 = Mirostat，2 = Mirostat 2.0）	0
spring.ai.ollama.embedding.mirostat-tau	控制输出连贯性与多样性之间的平衡。较低的值会带来更聚焦、更连贯的文本。	5.0
spring.ai.ollama.embedding.mirostat-eta	影响算法对已生成文本反馈的响应速度。较低的学习率会导致较慢的调整，较高的学习率会让算法更敏捷。	0.1
spring.ai.ollama.embedding.penalize-newline	-	true
spring.ai.ollama.embedding.stop	设置要使用的停止序列。遇到此模式时，LLM 会停止生成文本并返回。可通过在 modelfile 中指定多个独立的 stop 参数来设置多个停止模式。	-
spring.ai.ollama.embedding.functions	在单个提示词请求中为函数调用启用的函数名列表。这些名称对应的函数必须存在于 toolCallbacks 注册表中。	-

TIP

所有以 spring.ai.ollama.embedding 为前缀的属性，都可通过在 EmbeddingRequest 调用中添加一个请求专用的 embedding-options 在运行时被覆盖。

运行时选项

OllamaEmbeddingOptions.java 提供 Ollama 的各项配置，例如要使用的模型、底层的 GPU 与 CPU 调优等。

WARNING

OllamaOptions 类已被弃用。请改用 OllamaChatOptions（用于聊天模型）和 OllamaEmbeddingOptions（用于嵌入模型）。新类提供了类型安全、模型特定的配置选项。

默认选项也可通过 spring.ai.ollama.embedding 属性来配置。

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

例如，为某个特定请求覆盖默认模型名：

EmbeddingResponse embeddingResponse = embeddingModel.call(
    new EmbeddingRequest(List.of("Hello World", "World is big and salvation is near"),
        OllamaEmbeddingOptions.builder()
            .model("Different-Embedding-Model-Deployment-Name"))
            .truncates(false)
            .build());

自动拉取模型

当模型在你的 Ollama 实例中不可用时，Spring AI Ollama 可以自动拉取它们。 此功能对开发和测试、以及把应用部署到新环境尤其有用。

TIP

你也可以按名称拉取数以千计的免费 GGUF Hugging Face 模型 之一。

拉取模型有三种策略：

• always（定义于 PullModelStrategy.ALWAYS）：始终拉取模型，即便它已可用。用于确保你使用的是模型的最新版本。
• when_missing（定义于 PullModelStrategy.WHEN_MISSING）：仅当模型尚未可用时才拉取。这可能导致使用较旧版本的模型。
• never（定义于 PullModelStrategy.NEVER）：从不自动拉取模型。

WARNING

由于下载模型可能耗时较长，不建议在生产环境使用自动拉取。取而代之，请考虑预先评估并预下载所需的模型。

所有通过配置属性和默认选项定义的模型，都可在启动时自动拉取。 你可以使用配置属性来配置拉取策略、超时和最大重试次数：

spring:
  ai:
    ollama:
      init:
        pull-model-strategy: always
        timeout: 60s
        max-retries: 1

WARNING

在所有指定模型都可在 Ollama 中获得之前，应用不会完成其初始化。取决于模型大小和网速，这可能会显著拖慢应用的启动时间。

你可以在启动时初始化额外的模型，这对在运行时动态使用的模型很有用：

spring:
  ai:
    ollama:
      init:
        pull-model-strategy: always
        embedding:
          additional-models:
            - mxbai-embed-large
            - nomic-embed-text

如果你只想把拉取策略应用到特定类型的模型，可以将嵌入模型排除在初始化任务之外：

spring:
  ai:
    ollama:
      init:
        pull-model-strategy: always
        embedding:
          include: false

此配置会对除嵌入模型之外的所有模型应用拉取策略。

HuggingFace 模型

Ollama 开箱即用地可访问所有 GGUF Hugging Face 嵌入模型。 你可以按名称拉取其中任何模型：ollama pull hf.co/<username>/<model-repository>，或配置自动拉取策略：自动拉取模型：

spring.ai.ollama.embedding.model=hf.co/mixedbread-ai/mxbai-embed-large-v1
spring.ai.ollama.init.pull-model-strategy=always

• spring.ai.ollama.embedding.model：指定要使用的 Hugging Face GGUF 模型。
• spring.ai.ollama.init.pull-model-strategy=always：（可选）在启动时启用自动模型拉取。 对于生产环境，你应预下载模型以避免延迟：ollama pull hf.co/mixedbread-ai/mxbai-embed-large-v1。

示例控制器

这会创建一个可注入到你类中的 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。 为此，将 spring-ai-ollama 依赖添加到你的项目的 Maven pom.xml 或 Gradle build.gradle 构建文件：

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

TIP

参见 依赖管理 一节，把 Spring AI BOM 添加到你的构建文件。

NOTE

spring-ai-ollama 依赖同时也提供对 OllamaChatModel 的访问。

关于 OllamaChatModel 的更多信息，请参阅 Ollama 聊天客户端 一节。

接下来，创建一个 OllamaEmbeddingModel 实例，并使用专门的 chroma/all-minilm-l6-v2-f32 嵌入模型为两个输入文本计算嵌入：

var ollamaApi = OllamaApi.builder().build();

var embeddingModel = new OllamaEmbeddingModel(this.ollamaApi,
        OllamaEmbeddingOptions.builder()
			.model(OllamaModel.MISTRAL.id())
            .build());

EmbeddingResponse embeddingResponse = this.embeddingModel.call(
    new EmbeddingRequest(List.of("Hello World", "World is big and salvation is near"),
        OllamaEmbeddingOptions.builder()
            .model("chroma/all-minilm-l6-v2-f32"))
            .truncate(false)
            .build());

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