跳到主要内容

Ollama 嵌入

Deepseek 3.2 中英对照 Ollama Ollama Embeddings

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

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

前提条件​

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

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

ollama pull <model-name>

您也可以拉取成千上万个免费的 GGUF Hugging Face Models：

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

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

自动配置​

备注

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

Spring AI 为 Azure Ollama Embedding 模型提供了 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 仓库中。请参阅仓库章节，将这些仓库添加到你的构建系统中。
:::

基础属性​

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

PropertyDescriptionDefault
spring.ai.ollama.base-urlOllama API 服务器运行的基础 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除了通过默认属性配置的模型外，需要初始化的额外模型。[]

嵌入属性​

备注

嵌入自动配置的启用与禁用现在通过前缀为 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要使用的支持模型的名称。您可以使用专用的嵌入模型类型。mxbai-embed-large
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设置用于生成下一个令牌的上下文窗口大小。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将使用稍多的显存来存储临时结果的暂存缓冲区。0
spring.ai.ollama.embedding.options.low-vram-false
spring.ai.ollama.embedding.options.f16-kv-true
spring.ai.ollama.embedding.options.logits-all返回所有标记的logits，而不仅仅是最后一个。要使补全功能能够返回logprobs，此设置必须为true。-
spring.ai.ollama.embedding.options.vocab-only仅加载词汇表，不加载权重。-
spring.ai.ollama.embedding.options.use-mmap默认情况下，模型会被映射到内存中，这样系统就能按需加载模型必要的部分。但如果模型大小超过你的总内存容量，或者系统可用内存较低，使用内存映射可能会增加页面置换的风险，从而对性能产生负面影响。禁用内存映射会导致加载时间变慢，但如果你没有使用内存锁定，可能会减少页面置换。请注意，如果模型大小超过总内存容量，关闭内存映射将导致模型完全无法加载。空值
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生成文本时预测的最大令牌数。(-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-zTail-free sampling 用于降低低概率词元对输出的影响。数值越高（例如 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将停止生成文本并返回。可以通过在模型文件中指定多个独立的停止参数来设置多个停止模式。-
spring.ai.ollama.embedding.options.functions要在单次提示请求中启用的函数列表，以函数名称标识。这些名称的函数必须存在于functionCallbacks注册表中。-

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

运行时选项​

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

:::重要
OllamaOptions 类已被弃用。请使用 OllamaChatOptions 类处理聊天模型，使用 OllamaEmbeddingOptions 类处理嵌入模型。新的类提供了类型安全且针对特定模型的配置选项。
:::

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

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

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

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 嵌入模型。你可以通过名称拉取这些模型：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。

示例控制器​

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

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

:::提示
请参考依赖管理章节，将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 为所有嵌入请求提供配置信息。