Spring AI
参考文档
模型
嵌入模型
Ollama
Ollama 嵌入
使用 Ollama，您可以在本地运行各种 AI 模型并从中生成嵌入。嵌入是一个浮点数向量（列表）。两个向量之间的距离衡量它们的相关性。距离小表示相关性强，距离大表示相关性弱。
OllamaEmbeddingModel 实现利用了 Ollama 嵌入 API 端点。
前置条件
您首先需要访问一个 Ollama 实例。有以下几种选择，包括：
- 在本地机器上下载并安装 Ollama。
- 通过 Testcontainers 配置和运行 Ollama。
您可以从 Ollama 模型库中拉取您想在应用程序中使用的模型：
bash
ollama pull <模型名称>您也可以拉取数以千计的免费 GGUF Hugging Face 模型中的任何一个：
bash
ollama pull hf.co/<用户名>/<模型仓库>或者，您可以启用自动下载所需模型的选项：自动拉取模型。
自动配置
Spring AI 自动配置中，启动器模块的工件名称发生了重大变化。更多信息请参考升级说明。
Spring AI 为 Ollama 嵌入模型提供了 Spring Boot 自动配置。要启用它，请将以下依赖项添加到您的 Maven pom.xml 或 Gradle build.gradle 构建文件中：
Maven
Gradle
xml
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-model-ollama</artifactId>
</dependency>请参考依赖管理部分，将 Spring AI BOM 添加到您的构建文件中。Spring AI 工件发布在 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 是配置 Ollama 嵌入模型的属性前缀。它包括 Ollama 请求（高级）参数，如模型、keep-alive 和 truncate，以及 Ollama 模型属性。
以下是 Ollama 嵌入模型的高级请求参数：
| 属性 | 描述 | 默认值 |
|---|---|---|
spring.ai.ollama.embedding.enabled (已移除且不再有效) |
启用 Ollama 嵌入模型自动配置。 | true |
spring.ai.model.embedding |
启用 Ollama 嵌入模型自动配置。 | ollama |
spring.ai.ollama.embedding.model |
要使用的支持模型的名称。您可以使用专用的嵌入模型类型。 | mxbai-embed-large |
spring.ai.ollama.embedding.keep_alive |
控制请求后模型在内存中保持加载的时间。 | 5m |
spring.ai.ollama.embedding.truncate |
截断每个输入的末尾以适应上下文长度。如果为 false 且超出上下文长度，则返回错误。 |
true |
其余选项属性基于 Ollama 有效参数和值 以及 Ollama 类型。默认值基于：Ollama 类型默认值。
| 属性 | 描述 | 默认值 |
|---|---|---|
spring.ai.ollama.embedding.numa |
是否使用 NUMA。 | false |
spring.ai.ollama.embedding.num-ctx |
设置用于生成下一个标记的上下文窗口大小。 | 2048 |
spring.ai.ollama.embedding.num-batch |
提示处理的最大批次大小。 | 512 |
spring.ai.ollama.embedding.num-gpu |
发送到 GPU 的层数。在 macOS 上，默认为 1 以启用 Metal 支持，0 表示禁用。此处的 1 表示应动态设置 NumGPU。 |
-1 |
spring.ai.ollama.embedding.main-gpu |
使用多个 GPU 时，此选项控制哪个 GPU 用于小张量，因为将计算拆分到所有 GPU 的开销并不划算。相关 GPU 将使用稍多的 VRAM 来存储临时结果的暂存缓冲区。 | 0 |
spring.ai.ollama.embedding.low-vram |
- | false |
spring.ai.ollama.embedding.f16-kv |
- | true |
spring.ai.ollama.embedding.logits-all |
返回所有标记的 logits，而不仅仅是最后一个。要使补全返回 logprobs，此值必须为 true。 |
- |
spring.ai.ollama.embedding.vocab-only |
仅加载词汇表，不加载权重。 | - |
spring.ai.ollama.embedding.use-mmap |
默认情况下，模型被映射到内存中，这允许系统仅根据需要加载模型的必要部分。但是，如果模型大于您的总 RAM 量，或者您的系统可用内存不足，使用 mmap 可能会增加页面换出的风险，从而对性能产生负面影响。禁用 mmap 会导致加载时间变慢，但如果您不使用 mlock，可能会减少页面换出。请注意，如果模型大于总 RAM 量，关闭 mmap 将阻止模型加载。 |
null |
spring.ai.ollama.embedding.use-mlock |
将模型锁定在内存中，防止在内存映射时被换出。这可以提高性能，但会牺牲一些内存映射的优点，因为它需要更多的 RAM 来运行，并且可能因为模型加载到 RAM 中而减慢加载时间。 | false |
spring.ai.ollama.embedding.num-thread |
设置计算期间使用的线程数。默认情况下，Ollama 会检测此值以获得最佳性能。建议将此值设置为系统拥有的物理 CPU 核心数（与逻辑核心数相对）。0 = 让运行时决定。 |
0 |
spring.ai.ollama.embedding.num-keep |
- | 4 |
spring.ai.ollama.embedding.seed |
设置用于生成的随机数种子。设置为特定数字将使模型为相同的提示生成相同的文本。 | -1 |
spring.ai.ollama.embedding.num-predict |
生成文本时预测的最大标记数。（-1 = 无限生成，-2 = 填充上下文） |
-1 |
spring.ai.ollama.embedding.top-k |
降低生成无意义内容的概率。较高的值（例如，100）会给出更多样化的答案，而较低的值（例如，10）会更保守。 |
40 |
spring.ai.ollama.embedding.top-p |
与 top-k 协同工作。较高的值（例如，0.95）会导致更多样化的文本，而较低的值（例如，0.5）会生成更集中和保守的文本。 |
0.9 |
spring.ai.ollama.embedding.min-p |
作为 top_p 的替代方案，旨在确保质量和多样性的平衡。参数 p 表示要考虑的标记的最小概率，相对于最可能标记的概率。例如，p=0.05 且最可能标记的概率为 0.9 时，值小于 0.045 的 logits 将被过滤掉。 |
0.0 |
spring.ai.ollama.embedding.tfs-z |
无尾采样用于减少输出中不太可能的标记的影响。较高的值（例如，2.0）会更大程度地减少影响，而 1.0 则禁用此设置。 |
1.0 |
spring.ai.ollama.embedding.typical-p |
- | 1.0 |
spring.ai.ollama.embedding.repeat-last-n |
设置模型回溯多远以防止重复。（默认：64，0 = 禁用，-1 = num_ctx） |
64 |
spring.ai.ollama.embedding.temperature |
模型的温度。提高温度会使模型回答更具创造性。 | 0.8 |
spring.ai.ollama.embedding.repeat-penalty |
设置如何强烈地惩罚重复。较高的值（例如，1.5）会更强烈地惩罚重复，而较低的值（例如，0.9）会更宽容。 |
1.1 |
spring.ai.ollama.embedding.presence-penalty |
- | 0.0 |
spring.ai.ollama.embedding.frequency-penalty |
- | 0.0 |
spring.ai.ollama.embedding.mirostat |
启用 Mirostat 采样以控制困惑度。（默认：0，0 = 禁用，1 = Mirostat，2 = Mirostat 2.0） |
0 |
spring.ai.ollama.embedding.mirostat-tau |
控制输出连贯性和多样性之间的平衡。较低的值会导致更集中和连贯的文本。 | 5.0 |
spring.ai.ollama.embedding.mirostat-eta |
影响算法对生成文本反馈的响应速度。较低的学习率会导致调整较慢，而较高的学习率会使算法响应更灵敏。 | 0.1 |
spring.ai.ollama.embedding.penalize-newline |
- | true |
spring.ai.ollama.embedding.stop |
设置要使用的停止序列。遇到此模式时，LLM 将停止生成文本并返回。可以通过在模型文件中指定多个单独的 stop 参数来设置多个停止模式。 |
- |
spring.ai.ollama.embedding.functions |
要启用的函数列表，通过函数名称在单个提示请求中启用函数调用。这些名称的函数必须存在于 toolCallbacks 注册表中。 |
- |
所有以 spring.ai.ollama.embedding 为前缀的属性都可以在运行时通过向 EmbeddingRequest 调用添加特定请求的运行时选项来覆盖。
运行时选项
OllamaEmbeddingOptions.java 提供了 Ollama 配置，例如要使用的模型、低级 GPU 和 CPU 调优等。
OllamaOptions类已弃用。对于聊天模型，请使用OllamaChatOptions；对于嵌入模型，请使用OllamaEmbeddingOptions。新类提供了类型安全、特定于模型的配置选项。
可以使用 spring.ai.ollama.embedding 属性配置默认选项。
在启动时，使用 OllamaEmbeddingModel(OllamaApi ollamaApi, OllamaEmbeddingOptions options) 配置用于所有嵌入请求的默认选项。在运行时，您可以使用 OllamaEmbeddingOptions 实例覆盖默认选项，作为 EmbeddingRequest 的一部分。
例如，要为特定请求覆盖默认模型名称：
java
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")
.truncate(false)
.build()));自动拉取模型
Spring AI Ollama 可以在模型在您的 Ollama 实例中不可用时自动拉取它们。此功能对于开发和测试以及将应用程序部署到新环境特别有用。
您也可以通过名称拉取数以千计的免费 GGUF Hugging Face 模型中的任何一个。
有三种拉取模型的策略：
always（在PullModelStrategy.ALWAYS中定义）：始终拉取模型，即使它已经可用。有助于确保您使用的是最新版本的模型。when_missing（在PullModelStrategy.WHEN_MISSING中定义）：仅在模型尚未可用时拉取。这可能导致使用旧版本的模型。never（在PullModelStrategy.NEVER中定义）：从不自动拉取模型。
由于下载模型可能存在延迟，自动拉取不推荐用于生产环境。建议提前评估并预先下载必要的模型。
所有通过配置属性和默认选项定义的模型都可以在启动时自动拉取。您可以使用配置属性配置拉取策略、超时时间和最大重试次数：
yaml
spring:
ai:
ollama:
init:
pull-model-strategy: always
timeout: 60s
max-retries: 1应用程序将在所有指定模型在 Ollama 中可用之前完成初始化。根据模型大小和互联网连接速度，这可能会显著减慢应用程序的启动时间。
您可以在启动时初始化额外的模型，这对于在运行时动态使用的模型很有用：
yaml
spring:
ai:
ollama:
init:
pull-model-strategy: always
embedding:
additional-models:
- mxbai-embed-large
- nomic-embed-text如果您想仅将拉取策略应用于特定类型的模型，您可以从初始化任务中排除嵌入模型：
yaml
spring:
ai:
ollama:
init:
pull-model-strategy: always
embedding:
include: false此配置将把拉取策略应用于除嵌入模型之外的所有模型。
HuggingFace 模型
Ollama 可以开箱即用地访问所有 GGUF Hugging Face 嵌入模型。您可以通过名称拉取这些模型中的任何一个：ollama pull hf.co/<用户名>/<模型仓库> 或配置自动拉取策略：自动拉取模型。
yaml
spring.ai.ollama.embedding.model=hf.co/mixedbread-ai/mxbai-embed-large-v1
spring.ai.ollama.init.pull-model-strategy=alwaysspring.ai.ollama.embedding.model：指定要使用的 Hugging Face GGUF 模型。spring.ai.ollama.init.pull-model-strategy=always：（可选）在启动时启用自动模型拉取。对于生产环境，您应该预先下载模型以避免延迟：ollama pull hf.co/mixedbread-ai/mxbai-embed-large-v1。
示例控制器
这将创建一个您可以注入到类中的 EmbeddingModel 实现。下面是一个简单的 @Controller 类示例，它使用了 EmbeddingModel 实现。
java
@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);
}
}手动配置
如果您不使用 Spring Boot，您可以手动配置 OllamaEmbeddingModel。为此，请将 spring-ai-ollama 依赖项添加到您项目的 Maven pom.xml 或 Gradle build.gradle 构建文件中：
Maven
Gradle
xml
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-ollama</artifactId>
</dependency>请参考依赖管理部分，将 Spring AI BOM 添加到您的构建文件中。
spring-ai-ollama 依赖项还提供了对 OllamaChatModel 的访问。有关 OllamaChatModel 的更多信息，请参考 Ollama 聊天客户端部分。
接下来，创建一个 OllamaEmbeddingModel 实例，并使用它来计算两个输入文本的嵌入，使用专用的 chroma/all-minilm-l6-v2-f32 嵌入模型：
java
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 提供了所有嵌入请求的配置信息。