Ollama Embeddings

使用 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 的自动配置和启动模块的 artifact 名称发生了重大变化，请参考升级说明获取更多信息。

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

<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 的相关 artifact 已发布在 Maven Central 和 Spring Snapshot 仓库中。请参阅仓库配置部分，将这些仓库添加到您的构建系统。

基础属性

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

属性	描述	默认值
`spring.ai.ollama.base-url`	Ollama API 服务器运行的基础 URL	`http://localhost:11434`

以下是用于初始化 Ollama 集成及自动拉取模型的相关属性：

属性	描述	默认值
`spring.ai.ollama.init.pull-model-strategy`	是否在启动时拉取模型以及拉取策略	`never`
`spring.ai.ollama.init.timeout`	拉取模型操作的等待时间	`5m`
`spring.ai.ollama.init.max-retries`	模型拉取操作的最大重试次数	`0`
`spring.ai.ollama.init.embedding.include`	是否在初始化任务中包含此类型的模型	`true`
`spring.ai.ollama.init.embedding.additional-models`	除默认属性配置的模型外，需要初始化的额外模型	`[]`

嵌入属性

嵌入模型的自动配置启用与禁用现在通过顶层属性进行管理，前缀为 spring.ai.model.embedding。

启用：spring.ai.model.embedding=ollama（默认已启用）
禁用：spring.ai.model.embedding=none（或任何不匹配 ollama 的值）

此更改旨在支持多模型配置。

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

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

属性	描述	默认值
`spring.ai.ollama.embedding.enabled`	已移除，不再有效	true
`spring.ai.model.embedding`	启用 Ollama 嵌入模型自动配置	ollama
`spring.ai.ollama.embedding.options.model`	使用的支持模型名称，可使用专用嵌入模型类型	mxbai-embed-large
`spring.ai.ollama.embedding.options.keep_alive`	控制模型在请求后保持加载到内存的时间	5m
`spring.ai.ollama.embedding.options.truncate`	如果输入超出上下文长度，则截断输入尾部；若为 false 且超长则返回错误	true

其余选项基于 Ollama 的有效参数及类型，默认值遵循 Ollama 类型的默认值：

属性	描述	默认值
`numa`	是否使用 NUMA	false
`num-ctx`	生成下一个 token 使用的上下文窗口大小	2048
`num-batch`	提示处理最大批量大小	512
`num-gpu`	发送到 GPU 层数；macOS 默认 1 支持 Metal，0 禁用	-1
`main-gpu`	多 GPU 情况下，控制小张量使用的 GPU	0
`low-vram`	是否启用低显存模式	false
`f16-kv`	使用 16 位精度 Key/Value	true
`logits-all`	返回所有 token 的 logits，而不仅是最后一个	-
`vocab-only`	仅加载词表，不加载权重	-
`use-mmap`	是否使用 mmap 将模型映射到内存	null
`use-mlock`	将模型锁定在内存，防止被交换	false
`num-thread`	计算时使用的线程数，0 表示由运行时决定	0
`num-keep`	-	4
`seed`	生成时使用的随机数种子	-1
`num-predict`	生成文本时预测的最大 token 数 (-1 = 无限生成, -2 = 填充上下文)	-1
`top-k`	降低生成无意义文本的概率	40
`top-p`	与 top-k 配合使用，提高值增加多样性	0.9
`min-p`	top-p 的替代参数，保证质量与多样性平衡	0.0
`tfs-z`	Tail-free 采样参数，降低低概率 token 的影响	1.0
`typical-p`	-	1.0
`repeat-last-n`	模型回溯防止重复的长度，0 表示禁用	64
`temperature`	模型温度，值越大生成越具有创造性	0.8
`repeat-penalty`	重复惩罚系数	1.1
`presence-penalty`	出现惩罚	0.0
`frequency-penalty`	频率惩罚	0.0
`mirostat`	是否启用 Mirostat 采样控制困惑度	0
`mirostat-tau`	输出一致性与多样性的平衡	5.0
`mirostat-eta`	算法对生成文本反馈的响应速度	0.1
`penalize-newline`	是否惩罚换行符	true
`stop`	停止序列，匹配时停止生成	-
`functions`	单次请求中启用的函数列表	-

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

运行时选项

OllamaEmbeddingOptions.java 提供了 Ollama 的配置选项，例如使用的模型、底层 GPU 和 CPU 调优等。

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

默认选项也可以通过 spring.ai.ollama.embedding.options 属性进行配置。

在启动时，可以使用以下方式配置所有嵌入请求的默认选项：

OllamaEmbeddingModel(OllamaApi ollamaApi, OllamaEmbeddingOptions defaultOptions)

在运行时，也可以通过在 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")
            .truncates(false)
            .build()
    )
);

模型自动拉取

Spring AI Ollama 可以在 Ollama 实例中模型不可用时自动拉取模型。此功能在开发、测试以及将应用部署到新环境时特别有用。

你也可以通过模型名称拉取数千个免费的 GGUF Hugging Face 模型。

拉取模型有三种策略：

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

由于下载模型可能导致延迟，不建议在生产环境中启用自动拉取。建议提前评估并预先下载所需模型。

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

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

应用程序在 Ollama 中所有指定模型可用之前，将无法完成初始化。根据模型大小和网络速度，这可能会显著延长应用启动时间。

你还可以在启动时初始化额外模型，这对于运行时动态使用的模型非常有用：

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 开箱即可访问所有 GGUF Hugging Face 嵌入模型。你可以通过模型名称拉取任意模型：

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

或者配置自动拉取策略：

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 实现。下面是一个使用 EmbeddingModel 实现的简单 @Controller 示例：

@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);
    }
}

该控制器通过构造函数注入 EmbeddingModel。
/ai/embedding 接口接收一个 message 参数（默认为 "Tell me a joke"），调用 embeddingModel.embedForResponse 获取嵌入结果，并以 Map 形式返回。

手动配置

如果你没有使用 Spring Boot，也可以手动配置 OllamaEmbeddingModel。为此，需要将 spring-ai-ollama 依赖添加到项目的 Maven pom.xml 或 Gradle build.gradle 文件中：

<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 Chat Client 部分。

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

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 提供了所有嵌入请求的配置信息。

Oci Genai

Transformers