通过 Ollama，您可以在本地运行各种大型语言模型（LLMs）并从中生成嵌入。Spring AI支持使用`OllamaEmbeddingClient`的Ollama文本嵌入。

嵌入是一个浮点数的向量（列表）。两个向量之间的距离衡量它们的相关性。小距离表明高度相关，大距离表明低度相关。

先决条件

首先，你需要在你的本地机器上运行Ollama。

参照官方的Ollama项目链接：https://github.com/jmorganca/ollama[README]来开始在你的本地机器上运行模型。

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

添加仓库和BOM

Spring AI 工件发布在 Spring Milestone 和 Snapshot 仓库中。参考 仓库 部分，将这些仓库添加到你的构建系统中。

为了协助依赖管理，Spring AI 提供了一个物料清单（BOM），以确保整个项目中使用一致版本的 Spring AI。请参阅 依赖管理章节，将 Spring AI BOM 加入到您的构建系统中。

自动配置

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'
}
Tip
 请参考依赖管理部分，以将Spring AI BOM添加到您的构建文件中。

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

嵌入属性

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

Property Description Default

spring.ai.ollama.base-url

Base URL where Ollama API server is running.

`http://localhost:11434

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

属性 描述 默认值

spring.ai.ollama.embedding.enabled

启用Ollama嵌入客户端。

true

spring.ai.ollama.embedding.model (已弃用)

要使用的模型名称。已弃用，请改用 spring.ai.ollama.embedding.options.model

mistral

spring.ai.ollama.embedding.options.model

要使用的[支持模型](https://github.com/ollama/ollama?tab=readme-ov-file#model-library)的名称。

mistral

spring.ai.ollama.embedding.options.numa

是否使用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(s)的层数。在macOS上，默认为1以启用金属支持，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
Note
 The spring.ai.ollama.embedding.options.* properties are based on the Ollama Valid Parameters and Values and Ollama Types
Tip
 所有以`spring.ai.ollama.embedding.options`为前缀的属性可以在运行时通过在`EmbeddingRequest`调用中添加特定于请求的[embedding-options]来覆盖。

运行时选项

The OllamaOptions.java provides the Ollama configurations, such as the model to use, the low level GPU and CPU tuning, etc.

默认选项可以使用`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"));

样本控制器

这将创建一个`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);
    }
}

手动配置

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

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

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

dependencies {
    implementation 'org.springframework.ai:spring-ai-ollama'
}
Tip
 请参考依赖管理部分，以将Spring AI BOM添加到您的构建文件中。
Note
 '''`spring-ai-ollama` 依赖也提供了对 OllamaChatClient 的访问。关于 OllamaChatClient 的更多信息，请参考链接:../chat/ollama-chat.html[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` 提供了所有嵌入请求的配置信息。