Ollama 嵌入模型

本站(springdoc.cn)中的内容来源于 spring.io ，原始版权归属于 spring.io。由 springdoc.cn 进行翻译，整理。可供个人学习、研究，未经许可，不得进行任何转载、商用或与之相关的行为。商标声明：Spring 是 Pivotal Software, Inc. 在美国以及其他国家的商标。

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

OllamaEmbeddingModel 实现基于 Ollama Embedding API 端点构建。

先决条件

你需要先获得 Ollama 实例的访问权限，可选方式包括：

在你的本地机器上下载并安装 Ollama。
通过 Testcontainers 配置并运行 Ollama。
通过 Kubernetes Service Binding 连接 Ollama 实例。

你可以从 Ollama 模型库拉取应用所需的模型：

ollama pull <model-name>

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

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

或者启用自动下载所需模型的选项：自动拉取模型功能。

自动配置

Spring AI 自动配置及 starter 模块的构件命名已发生重大变更，详情请参阅升级说明文档。

Spring AI 为 Azure 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 构件已发布至 Maven 中央仓库和 Spring 快照仓库，请参考 “仓库配置” 章节将这些仓库添加到你的构建系统中。

基础配置

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

属性

说明

默认值

spring.ai.ollama.base-url

Ollama API 服务运行的 Base 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

控制模型在请求后保持加载到内存中的时长。

spring.ai.ollama.embedding.options.truncate

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

true

其余 options 属性基于 Ollama 的有效参数和值（Ollama Valid Parameters and Values）以及 Ollama 类型（Ollama Types）。默认值基于 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 用于处理小型张量（tensor），因为对这些张量进行跨 GPU 分布式计算的开销并不值得。指定的 GPU 将会使用稍多一些的显存（VRAM）来存储临时结果的缓冲区。

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

仅加载词汇表，不加载权重（weights）。

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

默认情况下，模型会被映射到内存（mmap），这允许系统按需加载模型的必要部分。然而，如果模型大小超过系统的总 RAM，或者可用内存不足，使用 mmap 可能会增加页面换出（pageouts）的风险，从而对性能产生负面影响。

禁用 mmap 会导致加载速度变慢，但如果未使用 mlock，可能会减少页面换出。请注意，如果模型大小超过了总 RAM 容量，关闭 mmap 将导致模型无法加载。

null

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

将模型锁定在内存中，防止其在内存映射（memory-mapped）状态下被换出。这可以提升性能，但会牺牲部分内存映射的优势，因为它需要更多的 RAM 来运行，并且在模型加载到内存时可能会降低加载速度。

false

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

设置在计算过程中使用的线程数。默认情况下，Ollama 会自动检测以实现最佳性能。建议将此值设置为系统中 物理 CPU 核心数（而不是逻辑核心数）。

0 表示由运行时决定使用多少线程。

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

spring.ai.ollama.embedding.options.seed

设置用于生成文本的随机数种子（random number seed）。将此值设为特定数字后，模型在相同提示（prompt）下将生成相同的输出文本。

-1

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

在生成文本时，要预测的最大 token 数量。-1 表示无限生成，-2 表示填满上下文。

-1

spring.ai.ollama.embedding.options.top-k

减少生成无意义内容的概率。较高的值（例如 100）会产生更多样化的回答，而较低的值（例如 10）则会更加保守。

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 的 token 都将被过滤掉。

0.0

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

无尾采样用于减少输出中可能性较低的标记的影响。数值越大（如 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）

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）

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 中指定多个独立的 stop 参数来设置多个停止模式。

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) 配置所有嵌入请求的默认选项。运行时可通过在 EmbeddingRequest 中添加 OllamaOptions 实例来覆盖默认配置。

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

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

自动拉取模型

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 嵌入模型。通过以下方式拉取任意模型：ollama pull hf.co/<用户名>/<模型仓库> 或配置自动拉取策略：自动拉取模型功能。

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 类示例：

@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 或 Gradle build.gradle 构建文件中添加 spring-ai-ollama 依赖：

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 为所有嵌入请求提供配置信息。