Spring AI 使用 Ollama 嵌入向量

借助 Ollama，你可以在本地运行各类人工智能模型并生成对应的嵌入向量。嵌入向量是由浮点数组成的向量（列表），两个向量之间的距离可衡量二者的关联度：距离越小代表关联度越高，距离越大代表关联度越低。

OllamaEmbeddingModel 实现类基于 Ollama 嵌入向量 API 接口实现功能。

前提条件

首先你需要连接到一个 Ollama 实例，支持以下几种方式：

• 在本地设备下载并安装 Ollama

• 通过 Testcontainers 配置并运行 Ollama

• 通过 Kubernetes 服务绑定连接到 Ollama 实例

你可以从 Ollama 模型库拉取应用所需的模型：

ollama pull <model-name>

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

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

此外，你还可以开启模型自动下载功能：自动拉取模型。

自动配置

Spring AI 自动配置、启动器模块的构件名称发生了重大变更。更多信息请参考升级说明。

Spring AI 为 Ollama 嵌入模型提供了 Spring Boot 自动配置。启用该功能需在项目的 Maven pom.xml 或 Gradle build.gradle 文件中添加以下依赖：

Maven 依赖

org.springframework.aispring-ai-starter-model-ollama

参考「依赖管理」章节，将 Spring AI 物料清单添加到构建文件中。Spring AI 构件已发布至 Maven 中央仓库和 Spring 快照仓库，参考「仓库」章节将对应仓库添加到构建系统中。

基础配置属性

配置前缀 spring.ai.ollama 用于配置 Ollama 连接参数：

以下是 Ollama 集成初始化和模型自动拉取的配置属性：

嵌入向量配置属性

嵌入向量自动配置的启用与禁用，现已通过顶级前缀 spring.ai.model.embedding 配置：

• 启用：spring.ai.model.embedding=ollama（默认已启用）

• 禁用：spring.ai.model.embedding=none（或任意非 ollama 的值）

该变更用于支持多模型的配置管理。

配置前缀 spring.ai.ollama.embedding.options 用于配置 Ollama 嵌入模型，包含模型名称、keep-alive、truncate 等 Ollama 请求高级参数，以及模型配置属性。

Ollama 嵌入模型高级请求参数：

其余配置属性基于 Ollama 官方有效参数和类型定义，默认值遵循 Ollama 类型默认配置：

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

运行时选项

OllamaEmbeddingOptions.java 提供 Ollama 完整配置项，包括使用模型、GPU/CPU 底层调优等。

OllamaOptions 类已废弃，聊天模型使用 OllamaChatOptions，嵌入模型使用 OllamaEmbeddingOptions，新类提供类型安全的模型专属配置。

默认选项可通过 spring.ai.ollama.embedding.options 配置。启动时通过 OllamaEmbeddingModel 构造函数设置全局默认选项，运行时可在 EmbeddingRequest 中传入 OllamaEmbeddingOptions 实例覆盖配置。

示例：为单个请求覆盖默认模型名称

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")
            .truncate(false)
            .build()));

模型自动拉取

Spring AI Ollama 支持在模型不存在时自动拉取，该功能适用于开发、测试和新环境部署场景。

你可以按名称拉取 Hugging Face 上任意免费 GGUF 模型，支持三种拉取策略：

• always（PullModelStrategy.ALWAYS）：始终拉取模型，即使已存在，确保使用最新版本

• when_missing（PullModelStrategy.WHEN_MISSING）：仅在模型不存在时拉取，可能使用旧版本

• never（PullModelStrategy.NEVER）：从不自动拉取模型

模型下载可能产生延迟，生产环境不建议使用自动拉取，推荐提前预下载所需模型。

所有通过配置属性和默认选项定义的模型均可在启动时自动拉取，可通过配置指定拉取策略、超时时间和最大重试次数：

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

应用会等待所有指定模型就绪后完成初始化，模型大小和网络速度会影响启动耗时。

你可以在启动时初始化额外模型，适用于运行时动态使用的场景：

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 原生支持所有 Hugging Face GGUF 嵌入模型，可通过命令拉取或配置自动拉取：

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 实例，可直接注入使用。以下是简单的控制器示例：

@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 依赖

org.springframework.aispring-ai-ollama

参考「依赖管理」章节添加 Spring AI 物料清单。

spring-ai-ollama 依赖同时提供 OllamaChatModel 支持，更多信息参考 Ollama 聊天客户端章节。

创建 OllamaEmbeddingModel 实例并生成嵌入向量：

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 提供所有嵌入向量请求的配置信息，支持构建器模式快速创建。