Ollama Embeddings

利用 Ollama，可以在本地运行各种大型语言模型 (LLM)，并由此生成嵌入。Spring AI 支持使用 `OllamaEmbeddingClient`的 Ollama 文本嵌入。 嵌入是一个浮点数向量（列表）。两个向量之间的距离测量它们的相关性。距离越小表示相关性越高，距离越大表示相关性越低。

Prerequisites

你首先需要在本地计算机上运行 Ollama。

请参考官方 Ollama 项目 README开始在本地计算机上运行模型。

请注意，安装`ollama run llama2` 将下载一个 4GB 的 docker 镜像。

Add Repositories and BOM

Spring AI 工件发布在 Spring Milestone 和 Snapshot 存储库中。有关将这些存储库添加到你的构建系统的说明，请参阅 Repositories 部分。

为了帮助进行依赖项管理，Spring AI 提供了一个 BOM（物料清单）以确保在整个项目中使用一致版本的 Spring AI。有关将 Spring AI BOM 添加到你的构建系统的说明，请参阅 Dependency Management 部分。

Auto-configuration

Spring AI 为 Azure Ollama 嵌入客户端提供了 Spring Boot 自动配置。要启用它，请将以下依赖项添加到 Maven pom.xml 文件中：

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

或添加到 Gradle build.gradle 构建文件中。

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

  1. 参见 Dependency Management 部分，将 Spring AI BOM 添加到你的构建文件中。

spring.ai.ollama.embedding.options.* 属性用于配置所有嵌入请求使用的默认选项。（它用作 OllamaEmbeddingClient#withDefaultOptions() 实例）。

Embedding Properties

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

Property Description Default

spring.ai.ollama.base-url

Ollama API 服务器正在运行的基本 URL。

http://localhost:11434

前缀 spring.ai.ollama.embedding.options 是为 Ollama 配置 EmbeddingClient 实现的属性前缀。

Property Description Default

spring.ai.ollama.embedding.enabled

Enable Ollama embedding client.

true

spring.ai.ollama.embedding.model (DEPRECATED)

要使用的模型的名称。已弃用，而代之以 spring.ai.ollama.embedding.options.model

mistral

spring.ai.ollama.embedding.options.model

要使用的 supported models的名称。

mistral

spring.ai.ollama.embedding.options.numa

Whether to use NUMA.

false

spring.ai.ollama.embedding.options.num-ctx

设置用于生成下一个标记的上下文窗口的大小。

2048

spring.ai.ollama.embedding.options.num-batch

???

-

spring.ai.ollama.embedding.options.num-gqa

转换器层中 GQA 组的数量。某些模型需要此设置，例如，对于 llama2:70b，此设置是 8。

-

spring.ai.ollama.embedding.options.num-gpu

要发送到 GPU 的层数。在 macOS 上，它默认为 1 以启用 metal 支持，0 表示禁用。

-

spring.ai.ollama.embedding.options.main-gpu

???

-

spring.ai.ollama.embedding.options.low-vram

???

-

spring.ai.ollama.embedding.options.f16-kv

???

-

spring.ai.ollama.embedding.options.logits-all

???

-

spring.ai.ollama.embedding.options.vocab-only

???

-

spring.ai.ollama.embedding.options.use-mmap

???

-

spring.ai.ollama.embedding.options.use-mlock

???

-

spring.ai.ollama.embedding.options.embedding-only

???

-

spring.ai.ollama.embedding.options.rope-frequency-base

???

-

spring.ai.ollama.embedding.options.rope-frequency-scale

???

-

spring.ai.ollama.embedding.options.num-thread

设置在计算期间要使用的线程数。默认情况下，Ollama 将检测此值以获得最佳性能。建议将此值设置为您的系统具有的物理 CPU 核心的数量（与逻辑核心数相反）。

-

spring.ai.ollama.embedding.options.num-keep

???

-

spring.ai.ollama.embedding.options.seed

为生成设置要使用的随机数种子。将此设置特定为数字，将使模型为同一提示生成相同的文本。

0

spring.ai.ollama.embedding.options.num-predict

在生成文本时要预测的最大令牌数。（默认值：128，-1 = 无限生成，-2 = 填充上下文）

128

spring.ai.ollama.embedding.options.top-k

降低生成无意义文本的概率。较高的值（例如 100）将给出更多样化的答案，而较低的值（例如 10）将更稳妥。

40

spring.ai.ollama.embedding.options.top-p

与 top-k 搭配使用。较高的值（例如 0.95）将产生更多样化的文本，而较低的值（例如 0.5）将生成更集中和保守的文本。

0.9

spring.ai.ollama.embedding.options.tfs-z

尾部自由采样用于减少输出中概率较低标记的影响。较高的值（例如 2.0）将更多地减少这种影响，而值 1.0 则禁用此设置。

1

spring.ai.ollama.embedding.options.typical-p

???

-

spring.ai.ollama.embedding.options.repeat-last-n

设置模型回溯以防止重复的时间。 （默认值：64，0 = 禁用，-1 = num_ctx）

64

spring.ai.ollama.embedding.options.temperature

模型的温度。增加温度将使模型更具创造力地回答。

0.8

spring.ai.ollama.embedding.options.repeat-penalty

设置对重复进行惩罚的力度。较高的值（例如 1.5）将更严厉地惩罚重复，而较低的值（例如 0.9）则更宽容。

1.1

spring.ai.ollama.embedding.options.presence-penalty

???

-

spring.ai.ollama.embedding.options.frequency-penalty

???

-

spring.ai.ollama.embedding.options.mirostat

启用 Mirostat 采样以控制困惑度。 （默认值：0，0 = 禁用，1 = Mirostat，2 = Mirostat 2.0）

0

spring.ai.ollama.embedding.options.mirostat-tau

影响算法对生成文本的反馈的响应速度。较低的学习率将导致较慢的调整，而较高的学习率将使算法更具响应能力。

0.1

spring.ai.ollama.embedding.options.mirostat-eta

控制输出的连贯性和多样性之间的平衡。较低的值将产生更专注和连贯的文本。

5.0

spring.ai.ollama.embedding.options.penalize-newline

???

-

spring.ai.ollama.embedding.options.stop

设置要使用的停止序列。当遇到此模式时，LLM 将停止生成文本并返回。可以通过在模型文件中指定多个单独的停止参数来设置多个停止模式。

-

spring.ai.ollama.embedding.options.* 属性基于 Ollama Valid Parameters and Values 和 Ollama Types。

所有以 spring.ai.ollama.embedding.options 为前缀的属性都可以通过向 EmbeddingRequest 调用中添加一个特定的 Embedding Options 请求在运行时进行覆盖。

Embedding Options

OllamaOptions.java提供了 Ollama 配置，如要使用的模型、低级 GPU 和 CPU 调优等。

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

在开始时，使用 OllamaEmbeddingClient#withDefaultOptions() 配置用于所有嵌入请求的默认选项。在运行时，你可以使用 OllamaOptions 实例作为 EmbeddingRequest 的一部分来覆盖默认选项。

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

EmbeddingResponse embeddingResponse = embeddingClient.call(
    new EmbeddingRequest(List.of("Hello World", "World is big and salvation is near"),
        OllamaOptions.create()
            .withModel("Different-Embedding-Model-Deployment-Name"));

Sample Controller (Auto-configuration)

这将创建一个 EmbeddingClient 实现，你可以将其注入到你的类中。这里有一个简单的 @Controller 类的示例，它使用 EmbeddingClient 实现。

@RestController
public class EmbeddingController {

    private final EmbeddingClient embeddingClient;

    @Autowired
    public EmbeddingController(EmbeddingClient embeddingClient) {
        this.embeddingClient = embeddingClient;
    }

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

Manual Configuration

如果你不使用 Spring Boot，则可以手动配置 OllamaEmbeddingClient。为此，将 spring-ai-ollama 依赖项添加到项目的 Maven pom.xml 文件中：

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

或添加到 Gradle build.gradle 构建文件中。

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

  1. 参见 Dependency Management 部分，将 Spring AI BOM 添加到你的构建文件中。

spring-ai-ollama 依赖项还提供对 OllamaChatClient 的访问。有关 OllamaChatClient 的更多信息，请参阅 Ollama Chat Client 部分。

接下来，创建一个 OllamaEmbeddingClient 实例，并使用它来计算两个输入文本之间的相似度：

var ollamaApi = new OllamaApi();

var embeddingClient = new OllamaEmbeddingClient(ollamaApi)
    .withDefaultOptions(OllamaOptions.create()
			.withModel(OllamaOptions.DEFAULT_MODEL)
            .toMap());

EmbeddingResponse embeddingResponse = embeddingClient
	.embedForResponse(List.of("Hello World", "World is big and salvation is near"));

OllamaOptions 为所有嵌入请求提供配置信息。