第九章 Spring AI API中文版 - Ollama Embeddings API

Ollama嵌入

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

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

先决条件

您首先需要在本地机器上运行Ollama。

参考官方Ollama项目链接：README，开始在本地机器上运行模型。
注意，安装ollama运行llama2将下载一个4GB的docker镜像。

添加仓库和BOM

Spring AI工件发布在Spring Milestone和Snapshot仓库中。参考xref:getting-started.adoc#repositories部分将这些仓库添加到您的构建系统中。

为了帮助依赖管理，Spring AI提供了一个BOM（物料清单），以确保在整个项目中使用一致的Spring AI版本。参考xref:getting-started.adoc#dependency-management部分将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'
}

提示：参考xref:getting-started.adoc#dependency-management部分将Spring AI BOM添加到您的构建文件中。

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

嵌入属性

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

属性	描述	默认值
spring.ai.ollama.base-url	Ollama API服务器运行的基础URL。	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	要使用的readme支持的模型名称。	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以启用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将停止生成文本并返回。可以通过在modelfile中指定多个单独的停止参数来设置多个停止模式。	-

注意：spring.ai.ollama.embedding.options.*属性基于Ollama有效参数和值和Ollama类型。

提示：所有以spring.ai.ollama.embedding.options为前缀的属性都可以在运行时通过在EmbeddingRequest调用中添加请求特定的>覆盖。

嵌入选项

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"));

示例控制器（自动配置）

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

@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文件中：

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

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

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

提示：参考xref:getting-started.adoc#dependency-management部分将Spring AI BOM添加到您的构建文件中。

注意：spring-ai-ollama依赖项还提供了对OllamaChatClient的访问。
有关OllamaChatClient的更多信息，请参阅Ollama聊天客户端部分。

接下来，创建一个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为所有嵌入请求提供配置信息。