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

Ollama 嵌入

使用 Ollama，您可以在本地运行各种 AI 模型并从中生成嵌入。嵌入是浮点数的向量（列表）。两个向量之间的距离衡量它们的相关性。小距离表示高相关性，大距离表示低相关性。spring-doc.cadn.net.cn

这OllamaEmbeddingModelimplementation 利用 Ollama Embeddings 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>

您还可以提取数千个免费的 GGUF 紧贴脸模型中的任何一个：spring-doc.cadn.net.cn

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

或者，您可以启用选项以自动下载任何需要的模型：Auto-pull Models （自动拉取模型）。spring-doc.cadn.net.cn

自动配置

Spring AI 为 Azure Ollama 嵌入模型提供 Spring Boot 自动配置。要启用它，请将以下依赖项添加到您的 Maven 中pom.xml或 Gradlebuild.gradlebuild 文件：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-spring-boot-starter</artifactId>
</dependency>

dependencies {
    implementation 'org.springframework.ai:spring-ai-ollama-spring-boot-starter'
}

请参阅 Dependency Management 部分，将 Spring AI BOM 添加到您的构建文件中。 Spring AI 工件发布在 Maven Central 和 Spring Snapshot 存储库中。请参阅 Repositories 部分，将这些存储库添加到您的构建系统中。

基本属性

前缀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

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重试spring-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

除了通过 default properties 配置的模型之外，还需要初始化其他模型。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.enabledspring-doc.cadn.net.cn

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

真spring-doc.cadn.net.cn

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

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

米斯特拉尔spring-doc.cadn.net.cn

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

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

5 分钟spring-doc.cadn.net.cn

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

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

真spring-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

假spring-doc.cadn.net.cn

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

设置用于生成下一个标记的上下文窗口的大小。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 的层数。在 macOS 上，默认为 1 表示启用 Metal 支持，默认为 0 表示禁用。此处的 1 表示应动态设置 NumGPUspring-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

假spring-doc.cadn.net.cn

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

-spring-doc.cadn.net.cn

真spring-doc.cadn.net.cn

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

返回所有令牌的 logit，而不仅仅是最后一个令牌。要使 completions 返回 logprobs，这必须为 true。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

假spring-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

生成文本时要预测的最大令牌数。（-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.tfs-zspring-doc.cadn.net.cn

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

真spring-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叫。

运行时选项

OllamaOptions.java 提供了 Ollama 配置，例如要使用的模型、低级 GPU 和 CPU 调优等。spring-doc.cadn.net.cn

默认选项可以使用spring.ai.ollama.embedding.optionsproperties 也是如此。spring-doc.cadn.net.cn

启动时，使用OllamaEmbeddingModel(OllamaApi ollamaApi, OllamaOptions defaultOptions)配置用于所有嵌入请求的默认选项。在运行时，您可以使用OllamaOptions实例作为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"),
        OllamaOptions.builder()
            .model("Different-Embedding-Model-Deployment-Name"))
            .truncates(false)
            .build());

自动拉取模型

Spring AI Ollama 可以在模型在 Ollama 实例中不可用时自动拉取模型。此功能对于开发和测试以及将应用程序部署到新环境特别有用。spring-doc.cadn.net.cn

您还可以按名称提取数千个免费的 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 中提供所有指定模型之前，应用程序不会完成其初始化。根据模型大小和 Internet 连接速度，这可能会显著减慢应用程序的启动时间。

您可以在启动时初始化其他模型，这对于在运行时动态使用的模型非常有用：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

此配置会将拉取策略应用于除 embedding 模型之外的所有模型。spring-doc.cadn.net.cn

HuggingFace 模特

Ollama 可以开箱即用地访问所有 GGUF Hugging Face Embedding 模型。您可以按名称提取这些模型中的任何一个：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：指定要使用的紧贴面部 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

Samples控制器

这将创建一个EmbeddingModel实现，您可以将其注入到您的类中。下面是一个简单的示例@Controller类使用EmbeddingModel实现。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.gradlebuild 文件：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'
}

请参阅 Dependency Management 部分，将 Spring AI BOM 添加到您的构建文件中。

这spring-ai-ollamadependency 还提供对OllamaChatModel. 有关OllamaChatModel请参阅 Ollama Chat 客户端部分。

接下来，创建一个OllamaEmbeddingModel实例，并使用它使用专用的chroma/all-minilm-l6-v2-f32嵌入模型：spring-doc.cadn.net.cn

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

这OllamaOptions提供所有嵌入请求的配置信息。spring-doc.cadn.net.cn