跳到主要内容
版本：2.0.1

Ollama Embeddings

QWen 3.8 中英对照 Ollama Ollama Embeddings

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

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

先决条件​

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

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

ollama pull <model-name>

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

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

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

自动配置​

备注

Spring AI 自动配置和 starter 模块的 artifact 名称发生了重大变更。详情请参阅升级说明。

Spring AI 为 Ollama Embedding Model 提供了 Spring Boot 自动配置。要启用该功能，请在您的 Maven pom.xml 或 Gradle build.gradle 构建文件中添加以下依赖项：

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

请参阅 依赖管理 章节，以将 Spring AI BOM 添加到您的构建文件中。Spring AI 工件发布在 Maven Central 和 Spring Snapshot 仓库中。请参考 Repositories 章节，将这些仓库添加到您的构建系统中。

基本属性​

前缀 spring.ai.ollama 是用于配置与 Ollama 连接的属性前缀。

属性描述默认值
spring.ai.ollama.base-urlOllama API 服务器运行所在的 Base URL。http://localhost:11434

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

PropertyDescriptionDefault
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除通过默认属性配置的模型外，额外需要初始化的模型。[]

嵌入属性​

备注

嵌入自动配置（embedding auto-configurations）的启用与禁用，现在通过前缀为 spring.ai.model.embedding 的顶级属性进行配置。

要启用，请设置 spring.ai.model.embedding=ollama（默认情况下已启用）。

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

此更改旨在支持多模型配置。

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

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

属性描述默认值
spring.ai.ollama.embedding.enabled (已移除且不再有效)启用 Ollama embedding 模型的自动配置。true
spring.ai.model.embedding启用 Ollama embedding 模型的自动配置。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 上并不划算。被选中的 GPU 会占用略多的显存（VRAM），用于存储临时结果的暂存缓冲区（scratch buffer）。0
spring.ai.ollama.embedding.low-vram-false
spring.ai.ollama.embedding.f16-kv-true
spring.ai.ollama.embedding.logits-all返回所有令牌的 logits，而不仅仅是最后一个令牌。若要启用 completions 返回 logprobs，此值必须为 true。-
spring.ai.ollama.embedding.vocab-only仅加载词表，不加载权重。-
spring.ai.ollama.embedding.use-mmap默认情况下，模型会被映射到内存中，这使得系统能够按需仅加载模型的必要部分。然而，如果模型大于你的总 RAM 容量，或者你的系统可用内存较少，使用 mmap 可能会增加页面换出（pageouts）的风险，从而负面影响性能。禁用 mmap 会导致加载时间变慢，但如果你没有使用 mlock，它可能会减少页面换出。请注意，如果模型大于总 RAM 容量，关闭 mmap 将导致模型根本无法加载。null
spring.ai.ollama.embedding.use-mlock将模型锁定在内存中，防止其在内存映射时发生交换。这可以改进性能，但会以牺牲部分内存映射优势为代价：运行时需要占用更多 RAM，并且由于模型需加载到 RAM，加载时间可能会变长。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生成文本时预测的最大 token 数量。（-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 表示相对于最可能 token 的概率，一个 token 被考虑所需的最低概率。例如，当 p=0.05 且最可能的 token 的概率为 0.9 时，logits 值小于 0.045 的将被过滤掉。0.0
spring.ai.ollama.embedding.tfs-zTail-free 采样用于降低输出中低概率 token 的影响。较高的值（例如，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模型的temperature。提高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 注册表中。-
提示

所有以 spring.ai.ollama.embedding 为前缀的属性，都可以通过在 EmbeddingRequest 调用中添加请求特定的 Runtime Options 在运行时进行覆盖。

运行时选项​

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

important

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());

自动拉取模型​

Spring AI Ollama 可以在模型在您本地 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 Embedding 模型。你可以按名称拉取任意一个模型：ollama pull hf.co/<username>/<model-repository>，或配置自动拉取策略：Auto-pulling Models：

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 实现，您可以将其注入到类中。下面是一个简单的 @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 构建文件中：

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

请参考 Dependency Management 部分，以在构建文件中添加 Spring AI BOM。

备注

spring-ai-ollama 依赖项还允许访问 OllamaChatModel。有关 OllamaChatModel 的更多信息，请参阅 Ollama Chat Client 部分。

接下来，创建一个 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 提供了所有嵌入请求的配置信息。