SpringAI-Ollama Embeddings

使用Ollama可在本地运行多种AI模型并生成嵌入向量。嵌入向量是由浮点数组成的向量（列表），两个向量间的距离用于衡量其相关性：距离越小相关性越高，距离越大相关性越低。

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

先决条件

首先需访问Ollama实例，可通过以下方式实现：

• 在本地机器下载安装Ollama

• 通过Testcontainers配置运行Ollama

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

从Ollama模型库拉取应用程序所需模型：

ollama pull <模型名称>

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

ollama pull hf.co/<用户名>/<模型仓库>

或启用自动下载所需模型功能：自动拉取模型

自动配置

Spring AI自动配置及starter模块的构件名称有重大变更，详情参阅升级说明。

Spring AI为Azure 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中央仓库和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、截断等）及模型选项属性。

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

GPU资源配置
spring.ai.ollama.embedding.options.num-gpu
发送到GPU的层数（macOS默认1启用Metal支持，0禁用；值1表示动态设置）
默认值：-1

spring.ai.ollama.embedding.options.main-gpu
多GPU环境下，指定处理小张量的主GPU（减少计算拆分开销，会略微增加VRAM占用）
默认值：0

spring.ai.ollama.embedding.options.low-vram
低显存模式
默认值：false

内存与加载控制
spring.ai.ollama.embedding.options.use-mmap
启用内存映射加载模型（默认开启，可部分加载；大模型或低内存时禁用可减少页错误，但完全禁用可能导致超大模型无法加载）
默认值：null

spring.ai.ollama.embedding.options.use-mlock
锁定模型在内存中（防止交换到磁盘，提升性能但增加RAM需求并延长加载时间）
默认值：false

spring.ai.ollama.embedding.options.vocab-only
仅加载词汇表（不加载权重）
无默认值

计算优化
spring.ai.ollama.embedding.options.f16-kv
键值缓存使用半精度浮点数
默认值：true

spring.ai.ollama.embedding.options.num-thread
计算线程数（建议设为物理CPU核心数，0=自动检测）
默认值：0

spring.ai.ollama.embedding.options.logits-all
返回所有token的logits（需启用才能获取logprobs）
无默认值

生成控制
spring.ai.ollama.embedding.options.seed
随机数种子（固定值可使相同提示生成相同结果）
默认值：-1

spring.ai.ollama.embedding.options.num-predict
生成文本的最大token数（-1=无限生成，-2=填满上下文）
默认值：-1

spring.ai.ollama.embedding.options.temperature
温度参数（值越高生成越具创造性）
默认值：0.8

采样策略
spring.ai.ollama.embedding.options.top-k
限制高概率token采样（高值增加多样性，低值更保守）
默认值：40

spring.ai.ollama.embedding.options.top-p
核心采样概率阈值（高值增加多样性）
默认值：0.9

spring.ai.ollama.embedding.options.min-p
最低相对概率阈值（过滤低概率token）
默认值：0.0

spring.ai.ollama.embedding.options.tfs-z
尾端采样因子（高值减少低概率token影响，1.0=禁用）
默认值：1.0

spring.ai.ollama.embedding.options.typical-p
典型采样概率
默认值：1.0

重复控制
spring.ai.ollama.embedding.options.repeat-last-n
防重复回溯窗口大小（0=禁用，-1=使用num_ctx值）
默认值：64

spring.ai.ollama.embedding.options.repeat-penalty
重复惩罚强度（高值惩罚更强）
默认值：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.penalize-newline
换行符惩罚
默认值：true

高级算法
spring.ai.ollama.embedding.options.mirostat
Mirostat采样器（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.stop
停止序列（命中即终止生成，可在modelfile中定义多组）
无默认值

spring.ai.ollama.embedding.options.functions
单次请求启用的函数调用列表（需在functionCallbacks注册）
无默认值

spring.ai.ollama.embedding.options.num-keep
保留token数
默认值：4

所有spring.ai.ollama.embedding.options前缀属性可在运行时通过EmbeddingRequest的运行时选项覆盖。

运行时选项

OllamaOptions类提供Ollama配置（如模型选择、GPU/CPU调优等）。默认选项可通过spring.ai.ollama.embedding.options属性配置。

启动时通过OllamaEmbeddingModel(OllamaApi ollamaApi, OllamaOptions defaultOptions)配置默认选项。运行时可通过EmbeddingRequest中的OllamaOptions实例覆盖默认值，例如：

EmbeddingResponse response = embeddingModel.call(
    new EmbeddingRequest(List.of("Hello World", "World is big"),
        OllamaOptions.builder()
            .model("Different-Embedding-Model")
            .truncates(false)
            .build());

自动拉取模型

当Ollama实例缺失模型时，Spring AI Ollama可自动拉取，此特性适用于开发测试及新环境部署。支持三种拉取策略：

• always：总是拉取（确保使用最新版）

• when_missing：仅当缺失时拉取（可能使用旧版）

• never：禁止自动拉取

因模型下载可能延迟，生产环境不建议自动拉取，应预先下载所需模型。通过配置属性可设置拉取策略、超时和重试次数：

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

应用程序将等待所有指定模型就绪后才完成初始化，大型模型可能显著延长启动时间。可初始化额外模型供运行时动态使用：

spring:
  ai:
    ollama:
      init:
        embedding:
          additional-models:
            - mxbai-embed-large
            - nomic-embed-text

若需排除特定模型类型：

spring:
  ai:
    ollama:
      init:
        embedding:
          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  # 生产环境建议预下载

示例控制器

创建可注入的EmbeddingModel实现示例：

@RestController
public class EmbeddingController {
    private final EmbeddingModel model;
    
    @Autowired
    public EmbeddingController(EmbeddingModel model) {
        this.model = model;
    }

    @GetMapping("/ai/embedding")
    public Map embed(@RequestParam(defaultValue = "Tell me a joke") String message) {
        EmbeddingResponse response = this.model.embedForResponse(List.of(message));
        return Map.of("embedding", response);
    }
}

手动配置

非Spring Boot项目需手动配置：
1 添加依赖：

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

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

2 创建OllamaEmbeddingModel实例：

var ollamaApi = OllamaApi.builder().build();
var embeddingModel = new OllamaEmbeddingModel(ollamaApi,
    OllamaOptions.builder().model("mistral").build());

EmbeddingResponse response = 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为所有嵌入请求提供配置信息。