跳到主要内容

Ollama 嵌入

DeepSeek V3 中英对照 Ollama Ollama Embeddings

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

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

前提条件​

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

你可以从 Ollama 模型库 中拉取你希望在应用程序中使用的模型：

ollama pull <model-name>
shellscript

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

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

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

自动配置​

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

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

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

基本属性​

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

属性描述默认值
spring.ai.ollama.base-urlOllama API 服务器运行的基础 URL。[localhost:11434](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.ollama.embedding.options 是用于配置 Ollama 嵌入模型的属性前缀。它包括 Ollama 请求（高级）参数，如 model、keep-alive 和 truncate，以及 Ollama 模型的 options 属性。

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

属性描述默认值
spring.ai.ollama.embedding.enabled启用 Ollama 嵌入模型的自动配置。true
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 来运行并可能减慢加载时间，牺牲了内存映射的一些优势。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.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 中指定多个单独的 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) 来配置所有嵌入请求使用的默认选项。在运行时，你可以通过将 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());
java

自动拉取模型​

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
yaml
警告

应用程序在 Ollama 中所有指定的模型都可用之前，不会完成其初始化。根据模型大小和互联网连接速度，这可能会显著减慢应用程序的启动时间。

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

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

如果你只想对特定类型的模型应用拉取策略，你可以将嵌入模型从初始化任务中排除：

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

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

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
none

  • 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);
    }
}
java

手动配置​

如果你没有使用 Spring Boot，你可以手动配置 OllamaEmbeddingModel。为此，请将 spring-ai-ollama 依赖添加到你的项目的 Maven pom.xml 或 Gradle build.gradle 构建文件中：

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

请参考依赖管理部分，将 Spring AI BOM 添加到您的构建文件中。

备注

spring-ai-ollama 依赖还提供了对 OllamaChatModel 的访问。有关 OllamaChatModel 的更多信息，请参阅 Ollama 聊天客户端 部分。

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

# 创建 OllamaEmbeddingModel 实例
embedding_model = OllamaEmbeddingModel(model_name="chroma/all-minilm-l6-v2-f32")

# 计算两个输入文本的嵌入向量
text1 = "这是一个示例文本"
text2 = "这是另一个示例文本"
embeddings = embedding_model.compute_embeddings([text1, text2])

# 输出嵌入向量
print(embeddings)
python

在这个例子中，chroma/all-minilm-l6-v2-f32 是一个预训练的嵌入模型，专门用于将文本转换为固定长度的向量表示。通过调用 compute_embeddings 方法，可以一次性计算多个文本的嵌入向量。

var ollamaApi = new OllamaApi();

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

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