Ollama 嵌入

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

OllamaEmbeddingModel 实现利用了 Ollama 的 嵌入 API 端点。

前提条件

首先，你需要能够访问一个 Ollama 实例。有几种选项，包括以下几种：

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

ollama pull <model-name>

你也可以拉取数千个免费的 GGUF Hugging Face 模型中的任何一个

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

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

自动配置

Spring AI 自动配置、starter 模块的 artifact 名称发生了重大变化。有关详细信息，请参阅升级说明。

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

  • Maven

  • Gradle

<dependency>
   <groupId>org.springframework.ai</groupId>
   <artifactId>spring-ai-starter-model-ollama</artifactId>
</dependency>
dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-model-ollama'
}
请参阅依赖管理部分，将 Spring AI BOM 添加到你的构建文件中。Spring AI artifact 发布在 Maven Central 和 Spring Snapshot 仓库中。请参阅仓库部分，将这些仓库添加到你的构建系统中。

基础属性

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

属性

描述

默认值

spring.ai.ollama.base-url

Ollama API 服务器运行的基础 URL。

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

除了通过默认属性配置的模型之外，要初始化的其他模型。

[]

嵌入属性

嵌入自动配置的启用和禁用现在通过前缀为 spring.ai.model.embedding 的顶级属性进行配置。

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

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

进行此更改是为了允许配置多个模型。

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

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

属性

描述

默认值

spring.ai.ollama.embedding.enabled (已移除且不再有效)

启用 Ollama 嵌入模型的自动配置。

true

spring.ai.model.embedding

启用 Ollama 嵌入模型的自动配置。

ollama

spring.ai.ollama.embedding.options.model

要使用的受支持模型的名称。你可以使用专用的嵌入模型类型

mistral

spring.ai.ollama.embedding.options.keep_alive

控制模型在请求后在内存中驻留的时间。

5m

spring.ai.ollama.embedding.options.truncate

截断每个输入的末尾以适应上下文长度。如果为 false 且超出上下文长度，则返回错误。

true

剩余的 options 属性基于 Ollama 有效参数和值 以及 Ollama 类型。默认值基于：Ollama 类型默认值。

属性

描述

默认值

spring.ai.ollama.embedding.options.numa

是否使用 NUMA。

false

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

设置用于生成下一个 token 的上下文窗口大小。

2048

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

提示处理最大批量大小。

512

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

发送到 GPU 的层数。在 macOS 上，默认为 1 以启用 metal 支持，0 以禁用。这里的 1 表示 NumGPU 应动态设置

-1

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

当使用多个 GPU 时，此选项控制用于小张量的 GPU，对于这些小张量，将计算拆分到所有 GPU 上的开销不值得。该 GPU 将使用稍微更多的 VRAM 来存储临时结果的暂存缓冲区。

0

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

-

false

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

-

true

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

返回所有 token 的 logits，而不仅仅是最后一个。要使 completions 返回 logprobs，此值必须为 true。

-

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

仅加载词汇表，不加载权重。

-

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

默认情况下，模型会被映射到内存中，这使得系统可以按需加载模型的必要部分。但是，如果模型大于你的总 RAM 或系统可用内存较低，使用 mmap 可能会增加页面换出的风险，从而对性能产生负面影响。禁用 mmap 会导致加载时间变慢，但如果你不使用 mlock，可能会减少页面换出。请注意，如果模型大于总 RAM，关闭 mmap 将导致模型根本无法加载。

null

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

将模型锁定在内存中，防止在内存映射时被换出。这可以提高性能，但需要更多 RAM 来运行，并且可能随着模型加载到 RAM 而减慢加载时间，从而牺牲了内存映射的一些优势。

false

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

设置计算期间使用的线程数。默认情况下，Ollama 会检测以获得最佳性能。建议将此值设置为系统物理 CPU 内核数（而不是逻辑核心数）。0 = 让运行时决定

0

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

-

4

spring.ai.ollama.embedding.options.seed

设置用于生成文本的随机数种子。将其设置为特定数字将使模型为相同的提示生成相同的文本。

-1

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

生成文本时预测的最大 token 数。（-1 = 无限生成，-2 = 填充上下文）

-1

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.min-p

作为 top_p 的替代方案，旨在确保质量和多样性之间的平衡。参数 p 表示 token 被考虑的最低概率，相对于最有可能的 token 的概率。例如，当 p=0.05 且最有可能的 token 的概率为 0.9 时，值小于 0.045 的 logits 将被过滤掉。

0.0

spring.ai.ollama.embedding.options.tfs-z

无尾采样用于减少输出中概率较低的 token 的影响。较高的值（例如 2.0）会更多地减少影响，而值为 1.0 则禁用此设置。

1.0

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

-

1.0

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

-

0.0

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

-

0.0

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

-

true

spring.ai.ollama.embedding.options.stop

设置要使用的停止序列。当遇到此模式时，LLM 将停止生成文本并返回。可以在 modelfile 中指定多个单独的停止参数来设置多个停止模式。

-

spring.ai.ollama.embedding.options.functions

函数列表，由其名称标识，用于在单个提示请求中启用函数调用。具有这些名称的函数必须存在于 functionCallbacks 注册表中。

-
所有以 spring.ai.ollama.embedding.options 为前缀的属性都可以在运行时通过向 EmbeddingRequest 调用添加请求特定的运行时选项来覆盖。

运行时选项

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

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

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

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

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

自动拉取模型

当 Ollama 实例中不存在模型时，Spring AI Ollama 可以自动拉取模型。此功能对于开发、测试以及将应用程序部署到新环境特别有用。

你也可以按名称拉取数千个免费的 GGUF Hugging Face 模型中的任何一个。

拉取模型有三种策略：

  • always（定义在 PullModelStrategy.ALWAYS 中）：总是拉取模型，即使模型已存在。有助于确保你使用的是模型的最新版本。

  • when_missing（定义在 PullModelStrategy.WHEN_MISSING 中）：仅在模型不存在时拉取模型。这可能会导致使用模型的旧版本。

  • never（定义在 PullModelStrategy.NEVER 中）：从不自动拉取模型。

由于下载模型时可能存在延迟，不建议在生产环境中使用自动拉取。相反，请考虑提前评估并预下载所需的模型。

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

spring:
  ai:
    ollama:
      init:
        pull-model-strategy: always
        timeout: 60s
        max-retries: 1
在 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.options.model=hf.co/mixedbread-ai/mxbai-embed-large-v1
spring.ai.ollama.init.pull-model-strategy=always

  • spring.ai.ollama.embedding.options.model：指定要使用的 Hugging Face GGUF 模型。

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

示例 Controller

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

@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 构建文件中。

  • Maven

  • Gradle

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-ollama</artifactId>
</dependency>
dependencies {
    implementation 'org.springframework.ai:spring-ai-ollama'
}
请参阅依赖管理部分，将 Spring AI BOM 添加到你的构建文件中。
spring-ai-ollama 依赖项还提供了对 OllamaChatModel 的访问。有关 OllamaChatModel 的更多信息，请参阅 Ollama 聊天客户端部分。

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

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

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

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

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