此版本仍在开发中，尚未被视为稳定版。为了获取最新的快照版本，请使用Spring AI 1.1.3！spring-doc.cadn.net.cn

Ollama 嵌入

通过 Ollama，您可以在本地运行多种 AI模型并从中生成嵌入向量。嵌入向量是一个浮点数列表（向量）。两个向量之间的距离衡量它们的相关性。距离较短表示高度相关，距离较长则表示相关性较低。spring-doc.cadn.net.cn

OllamaEmbeddingModel 实现利用了 Ollama 嵌入式 API 端点。spring-doc.cadn.net.cn

前提条件

首先，您需要访问一个Ollama实例。有几种选择，包括以下：spring-doc.cadn.net.cn

在本地机器上下载并安装Ollama。spring-doc.cadn.net.cn
配置并通过Testcontainers运行Ollama。spring-doc.cadn.net.cn
通过Kubernetes服务绑定连接到Ollama实例。spring-doc.cadn.net.cn

您可以在应用程序中从Ollama模型库拉取所需模型：spring-doc.cadn.net.cn

ollama pull <model-name>

您也可以拉取数千个免费的Hugging Face GGUF模型:spring-doc.cadn.net.cn

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

另外，您可以启用自动下载所需模型的选项：模型自动拉取.spring-doc.cadn.net.cn

自动配置

There has been a significant change in the Spring AI auto-configuration, starter modules' artifact names. Please refer to the 升级说明以获取更多信息。spring-doc.cadn.net.cn

Spring AI 为 Azure Ollama 嵌入模型提供了 Spring Boot 自动配置功能。要启用它，请在您的 Maven pom.xml 或 Gradle build.gradle 构建文件中添加以下依赖项：spring-doc.cadn.net.cn

Mavenspring-doc.cadn.net.cn
Gradlespring-doc.cadn.net.cn

<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 Central和Spring快照仓库中。请参阅仓库部分，将这些仓库添加到您的构建系统中。

基本属性

前缀 spring.ai.ollama 是用于配置与Ollama连接的属性前缀spring-doc.cadn.net.cn

属性spring-doc.cadn.net.cn

描述spring-doc.cadn.net.cn

默认spring-doc.cadn.net.cn

spring.ai.ollama.base-urlspring-doc.cadn.net.cn

Ollama API 服务器运行的基础URL。spring-doc.cadn.net.cn

http://localhost:11434spring-doc.cadn.net.cn

这里是初始化Ollama集成和自动拉取模型的属性设置。spring-doc.cadn.net.cn

属性spring-doc.cadn.net.cn

描述spring-doc.cadn.net.cn

默认spring-doc.cadn.net.cn

spring.ai.ollama.init.pull-model-strategyspring-doc.cadn.net.cn

是否在启动时拉取模型以及如何拉取。spring-doc.cadn.net.cn

neverspring-doc.cadn.net.cn

spring.ai.ollama.init.timeoutspring-doc.cadn.net.cn

等待模型被拉取的时长。spring-doc.cadn.net.cn

5mspring-doc.cadn.net.cn

spring.ai.ollama.init.max-retriesspring-doc.cadn.net.cn

模型拉取操作的最大重试次数。spring-doc.cadn.net.cn

0spring-doc.cadn.net.cn

spring.ai.ollama.init.embedding.includespring-doc.cadn.net.cn

在初始化任务中包含此类模型。spring-doc.cadn.net.cn

truespring-doc.cadn.net.cn

spring.ai.ollama.init.embedding.additional-modelsspring-doc.cadn.net.cn

除通过默认属性配置的模型之外，需要额外初始化的模型。spring-doc.cadn.net.cn

[]spring-doc.cadn.net.cn

嵌入属性

启用和禁用嵌入式自动配置现在通过带有前缀 spring.ai.model.embedding 的顶级属性进行配置。spring-doc.cadn.net.cn

要启用，请设置 spring.ai.model.embedding=ollama （默认情况下已启用）spring-doc.cadn.net.cn

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

这种修改是为了允许配置多个模型。spring-doc.cadn.net.cn

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

以下是Ollama嵌入模型的高级请求参数：spring-doc.cadn.net.cn

属性spring-doc.cadn.net.cn

描述spring-doc.cadn.net.cn

默认spring-doc.cadn.net.cn

spring.ai.ollama.embedding.enabled（已移除，不再有效）spring-doc.cadn.net.cn

启用Ollama嵌入模型的自动配置。spring-doc.cadn.net.cn

truespring-doc.cadn.net.cn

spring.ai.model.embeddingspring-doc.cadn.net.cn

启用Ollama嵌入模型的自动配置。spring-doc.cadn.net.cn

Ollamaspring-doc.cadn.net.cn

spring.ai.ollama.embedding.options.modelspring-doc.cadn.net.cn

支持的模型名称要使用。您可以使用专用的嵌入模型类型spring-doc.cadn.net.cn

mxbai-embed-largespring-doc.cadn.net.cn

spring.ai.ollama.embedding.options.keep_alivespring-doc.cadn.net.cn

控制模型在请求后保持加载在内存中的时长spring-doc.cadn.net.cn

5mspring-doc.cadn.net.cn

spring.ai.ollama.embedding.options.truncatespring-doc.cadn.net.cn

截断每个输入的尾部以适应上下文长度。如果超出上下文长度且为假，则返回错误。spring-doc.cadn.net.cn

truespring-doc.cadn.net.cn

剩余的 options 个属性基于 Ollama 有效参数及值和 Ollama 类型。默认值依据：Ollama 类型默认值。spring-doc.cadn.net.cn

属性spring-doc.cadn.net.cn

描述spring-doc.cadn.net.cn

默认spring-doc.cadn.net.cn

spring.ai.ollama.embedding.options.numaspring-doc.cadn.net.cn

是否使用NUMA。spring-doc.cadn.net.cn

falsespring-doc.cadn.net.cn

spring.ai.ollama.embedding.options.num-ctxspring-doc.cadn.net.cn

设置用于生成下一个Tokens的上下文窗口的大小。spring-doc.cadn.net.cn

2048spring-doc.cadn.net.cn

spring.ai.ollama.embedding.options.num-batchspring-doc.cadn.net.cn

提示处理最大批次大小。spring-doc.cadn.net.cn

512spring-doc.cadn.net.cn

spring.ai.ollama.embedding.options.num-gpuspring-doc.cadn.net.cn

发送到GPU(s)的层数。在macOS上，默认为1以启用Metal支持，设置为0则禁用。此处的1表示NumGPU应动态设置。spring-doc.cadn.net.cn

-1spring-doc.cadn.net.cn

spring.ai.ollama.embedding.options.main-gpuspring-doc.cadn.net.cn

在使用多块GPU时，此选项用于控制哪些小型张量使用的GPU。对于这些小型张量，跨所有GPU分配计算的开销并不划算。被选中的GPU将稍微占用更多的VRAM来存储临时结果的缓冲区。spring-doc.cadn.net.cn

0spring-doc.cadn.net.cn

spring.ai.ollama.embedding.options.low-vramspring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

falsespring-doc.cadn.net.cn

spring.ai.ollama.embedding.options.f16-kvspring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

truespring-doc.cadn.net.cn

spring.ai.ollama.embedding.options.logits-allspring-doc.cadn.net.cn

为所有Tokens返回logits，而不仅仅是最后一个。为了使 completions 能够返回 logprobs，此选项必须为真。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.ollama.embedding.options.vocab-onlyspring-doc.cadn.net.cn

仅加载词汇表，不加载权重。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.ollama.embedding.options.use-mmapspring-doc.cadn.net.cn

默认情况下，模型会被映射到内存中，这使得系统能够按需只加载模型的必要部分。然而，如果模型大小超过您总RAM量，或者系统可用内存较低，使用mmap可能会增加页面交换的风险，从而负面影响性能。禁用mmap会导致加载时间变慢，但如果未使用mlock，可能会减少页面调度。请注意，如果模型大小超过总RAM量，关闭mmap将根本阻止模型加载。spring-doc.cadn.net.cn

空值spring-doc.cadn.net.cn

spring.ai.ollama.embedding.options.use-mlockspring-doc.cadn.net.cn

将模型锁定在内存中，防止在使用内存映射时将其换出。这可以提高性能，但会牺牲内存映射的一些优势，因为它需要更多的RAM来运行，并且在模型加载到RAM时可能减慢加载时间。spring-doc.cadn.net.cn

falsespring-doc.cadn.net.cn

spring.ai.ollama.embedding.options.num-threadspring-doc.cadn.net.cn

设置计算过程中使用的线程数。默认情况下，Ollama 会自动检测以达到最佳性能。建议将此值设置为系统物理CPU核心数（而非逻辑核心数）。0 = 让运行时自动决定。spring-doc.cadn.net.cn

0spring-doc.cadn.net.cn

spring.ai.ollama.embedding.options.num-keepspring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

4spring-doc.cadn.net.cn

spring.ai.ollama.embedding.options.seedspring-doc.cadn.net.cn

设置用于生成的随机数种子。将此设置为特定数值将使模型在接收到相同的提示时生成相同的文本。spring-doc.cadn.net.cn

-1spring-doc.cadn.net.cn

spring.ai.ollama.embedding.options.num-predictspring-doc.cadn.net.cn

生成文本时预测的最大Tokens数量。(-1 = 无限生成, -2 = 填充上下文)spring-doc.cadn.net.cn

-1spring-doc.cadn.net.cn

spring.ai.ollama.embedding.options.top-kspring-doc.cadn.net.cn

降低生成无意义内容的概率。较高的值（例如，100）将提供更加多样化的答案，而较低的值（例如，10）则更为保守。spring-doc.cadn.net.cn

40spring-doc.cadn.net.cn

spring.ai.ollama.embedding.options.top-pspring-doc.cadn.net.cn

与 top-k 配合使用。较高的值（例如，0.95）将产生更多样化的文本，而较低的值（例如，0.5）将生成更集中和保守的文本。spring-doc.cadn.net.cn

0.9spring-doc.cadn.net.cn

spring.ai.ollama.embedding.options.min-pspring-doc.cadn.net.cn

作为`top_p`的替代方案，旨在确保质量和多样性的平衡。参数p表示一个标记被考虑的最低概率，相对于最可能标记的概率。例如，如果p=0.05且最可能的标记概率为0.9，则值小于0.045的logits会被过滤掉。spring-doc.cadn.net.cn

0.0spring-doc.cadn.net.cn

spring.ai.ollama.embedding.options.tfs-zspring-doc.cadn.net.cn

无尾采样用于减少输出中较不可能的Tokens的影响。较高的值（例如，2.0）会更大程度地减少这种影响，而1.0的值则会禁用此设置。spring-doc.cadn.net.cn

1.0spring-doc.cadn.net.cn

spring.ai.ollama.embedding.options.typical-pspring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

1.0spring-doc.cadn.net.cn

spring.ai.ollama.embedding.options.repeat-last-nspring-doc.cadn.net.cn

设置模型回溯以防重复的时间跨度。默认值为64，0表示禁用，-1表示回溯长度等于上下文数量(num_ctx)。spring-doc.cadn.net.cn

64spring-doc.cadn.net.cn

spring.ai.ollama.embedding.options.temperaturespring-doc.cadn.net.cn

模型的温度。提高温度将使模型的回答更具创造性。spring-doc.cadn.net.cn

0.8spring-doc.cadn.net.cn

spring.ai.ollama.embedding.options.repeat-penaltyspring-doc.cadn.net.cn

设置重复内容的惩罚强度。值越高（例如，1.5），对重复内容的惩罚越重；值越低（例如，0.9），则对重复内容更加宽容。spring-doc.cadn.net.cn

1.1spring-doc.cadn.net.cn

spring.ai.ollama.embedding.options.presence-penaltyspring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

0.0spring-doc.cadn.net.cn

spring.ai.ollama.embedding.options.frequency-penaltyspring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

0.0spring-doc.cadn.net.cn

spring.ai.ollama.embedding.options.mirostatspring-doc.cadn.net.cn

启用Mirostat采样以控制困惑度。（默认值：0，0=禁用，1=Mirostat，2=Mirostat 2.0）spring-doc.cadn.net.cn

0spring-doc.cadn.net.cn

spring.ai.ollama.embedding.options.mirostat-tauspring-doc.cadn.net.cn

控制输出的一致性与多样性之间的平衡。较低的值将产生更集中且连贯的文本。spring-doc.cadn.net.cn

5.0spring-doc.cadn.net.cn

spring.ai.ollama.embedding.options.mirostat-etaspring-doc.cadn.net.cn

影响算法根据生成文本的反馈进行响应的速度。较低的学习率将导致调整速度较慢，而较高的学习率将使算法更加灵敏。spring-doc.cadn.net.cn

0.1spring-doc.cadn.net.cn

spring.ai.ollama.embedding.options.penalize-newlinespring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

truespring-doc.cadn.net.cn

spring.ai.ollama.embedding.options.stopspring-doc.cadn.net.cn

设置要使用的停止序列。当遇到此模式时，LLM 将停止生成文本并返回。可以在模型文件中通过指定多个独立的停止参数来设置多个停止模式。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

spring.ai.ollama.embedding.options.functionsspring-doc.cadn.net.cn

函数列表，通过它们的名称来识别，以便在单个提示请求中启用函数调用。具有这些名称的函数必须存在于functionCallbacks注册表中。spring-doc.cadn.net.cn

-spring-doc.cadn.net.cn

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

运行时选项

OllamaEmbeddingOptions.java 文件提供了Ollama配置选项，如使用的模型、底层GPU和CPU调优等。spring-doc.cadn.net.cn

OllamaOptions 类已被弃用。对于聊天模型，请使用 OllamaChatOptions，而对于嵌入模型，请使用 OllamaEmbeddingOptions。新类提供了类型安全、针对模型的配置选项。

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

在启动时，使用OllamaEmbeddingModel(OllamaApi ollamaApi, OllamaEmbeddingOptions defaultOptions)来配置所有嵌入请求使用的默认选项。在运行时，您可以使用OllamaEmbeddingOptions实例作为EmbeddingRequest的一部分来覆盖默认选项。spring-doc.cadn.net.cn

例如，要为特定请求覆盖默认的模型名称：spring-doc.cadn.net.cn

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 实例中未提供模型时自动拉取它们。此功能对于开发和测试特别有用，同时也适用于将您的应用程序部署到新环境。spring-doc.cadn.net.cn

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

模型拉取有三种策略：spring-doc.cadn.net.cn

always （定义于 PullModelStrategy.ALWAYS）：始终拉取模型，即使它已可用。确保使用模型的最新版本很有帮助。spring-doc.cadn.net.cn
when_missing （定义于 PullModelStrategy.WHEN_MISSING）：仅在模型尚未获取时才拉取。这可能导致使用模型的较旧版本。spring-doc.cadn.net.cn
never （定义于 PullModelStrategy.NEVER 中）：从不自动拉取模型。spring-doc.cadn.net.cn

由于在下载模型时可能存在延迟，不建议在生产环境中使用自动拉取功能。建议事先评估并预先下载所需的模型。

所有通过配置属性和默认选项定义的模型都可在启动时自动拉取。您可以使用配置属性来设置拉取策略、超时时间和最大重试次数：spring-doc.cadn.net.cn

spring:
  ai:
    ollama:
      init:
        pull-model-strategy: always
        timeout: 60s
        max-retries: 1

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

您可以在启动时初始化额外的模型，这对于在运行时动态使用的模型非常有用：spring-doc.cadn.net.cn

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

如果您只想对特定类型的模型应用拉取策略，可以从初始化任务中排除嵌入模型：spring-doc.cadn.net.cn

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

此配置将拉取策略应用于所有模型，除了嵌入模型。spring-doc.cadn.net.cn

HuggingFace 模型

Ollama开箱即用地支持所有GGUF Hugging Face嵌入模型。您可以通过名称拉取这些模型，如：ollama pull hf.co/<username>/<model-repository>，或配置自动拉取策略：自动拉取模型：spring-doc.cadn.net.cn

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-doc.cadn.net.cn
spring.ai.ollama.init.pull-model-strategy=always: （可选）启用启动时自动模型拉取。对于生产环境，您应预先下载模型以避免延迟：ollama pull hf.co/mixedbread-ai/mxbai-embed-large-v1。spring-doc.cadn.net.cn

示例控制器

这将创建一个 EmbeddingModel 实现，您可以将其注入到您的类中。以下是一个使用 EmbeddingModel 实现的简单 @Controller 类的例子。spring-doc.cadn.net.cn

@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构建文件中:spring-doc.cadn.net.cn

Mavenspring-doc.cadn.net.cn
Gradlespring-doc.cadn.net.cn

<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 嵌入模型：spring-doc.cadn.net.cn

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为所有嵌入请求提供了配置信息。spring-doc.cadn.net.cn