39_Spring AI 干货笔记之 Ollama 嵌入-开发者社区

一、Ollama 嵌入

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

OllamaEmbeddingModel 实现利用了 Ollama 嵌入 API 端点。

二、先决条件

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

在本地机器上下载并安装 Ollama。
通过 Testcontainers 配置和运行 Ollama。
通过 Kubernetes 服务绑定连接到 Ollama 实例。

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

ollama pull<model-name>

您也可以拉取数千个免费的 GGUF Hugging Face 模型中的任何一个：

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

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

三、自动配置

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

Spring AI 为 Ollama 嵌入模型提供了 Spring Boot 自动配置。要启用它，请将以下依赖项添加到您的 Maven pom.xml 或 Gradle build.gradle 构建文件中：

Maven

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

Gradle

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

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

3.1 基础属性

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

以下是用于初始化 Ollama 集成和自动拉取模型的属性。

3.2 嵌入属性

嵌入自动配置的启用和禁用现在通过顶级属性 spring.ai.model.embedding 前缀进行配置。
要启用：spring.ai.model.embedding=ollama（默认启用）
要禁用：spring.ai.model.embedding=none（或任何与 ollama 不匹配的值）
进行此更改是为了允许配置多个模型。

前缀 spring.ai.ollama.embedding.options 是用于配置 Ollama 嵌入模型的属性前缀。它包括 Ollama 请求（高级）参数，例如模型、keep-alive 和 truncate，以及 Ollama 模型选项属性。

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

其余选项属性基于 Ollama 有效参数和值和 Ollama 类型。默认值基于：Ollama 类型默认值。

所有以 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 的一部分来覆盖默认选项。

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

EmbeddingResponseembeddingResponse=embeddingModel.call(newEmbeddingRequest(List.of("Hello World","World is big and salvation is near"),OllamaEmbeddingOptions.builder().model("Different-Embedding-Model-Deployment-Name").truncates(false).build()));

五、自动拉取模型

当模型在您的 Ollama 实例中不可用时，Spring AI Ollama 可以自动拉取模型。此功能对于开发和测试以及将应用程序部署到新环境特别有用。

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

有三种拉取模型的策略：

always（在 PullModelStrategy.ALWAYS 中定义）：始终拉取模型，即使它已经可用。有助于确保使用最新版本的模型。
when_missing（在 PullModelStrategy.WHEN_MISSING 中定义）：仅在模型不可用时拉取。这可能会导致使用较旧版本的模型。
never（在 PullModelStrategy.NEVER 中定义）：从不自动拉取模型。

由于下载模型时可能存在延迟，不建议在生产环境中使用自动拉取。相反，请考虑提前评估并预下载必要的模型。

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

spring:ai:ollama:init:pull-model-strategy:alwaystimeout:60smax-retries:1

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

您可以在启动时初始化其他模型，这对于在运行时动态使用的模型很有用：

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

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

spring:ai:ollama:init:pull-model-strategy:alwaysembedding: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 实现，您可以将其注入到您的类中。下面是一个简单的 @Controller 类示例，它使用 EmbeddingModel 实现。

@RestControllerpublicclassEmbeddingController{privatefinalEmbeddingModelembeddingModel;@AutowiredpublicEmbeddingController(EmbeddingModelembeddingModel){this.embeddingModel=embeddingModel;}@GetMapping("/ai/embedding")publicMapembed(@RequestParam(value="message",defaultValue="给我讲个笑话")Stringmessage){EmbeddingResponseembeddingResponse=this.embeddingModel.embedForResponse(List.of(message));returnMap.of("embedding",embeddingResponse);}}

八、手动配置

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

Maven

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

Gradle

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

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

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

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

varollamaApi=OllamaApi.builder().build();varembeddingModel=newOllamaEmbeddingModel(this.ollamaApi,OllamaEmbeddingOptions.builder().model(OllamaModel.MISTRAL.id()).build());EmbeddingResponseembeddingResponse=this.embeddingModel.call(newEmbeddingRequest(List.of("Hello World","World is big and salvation is near"),OllamaEmbeddingOptions.builder().model("chroma/all-minilm-l6-v2-f32").truncate(false).build()));