|
此版本仍在开发中，尚未被视为稳定版。如需最新的快照版本，请使用 Spring AI 1.1.3！ |
Ollama 嵌入
使用 Ollama，您可以在本地运行各种 AI 模型 并从中生成嵌入向量。 嵌入向量是由浮点数组成的向量（列表）。 两个向量之间的距离衡量它们的相关性。 距离较小表示相关性较高，距离较大表示相关性较低。
OllamaEmbeddingModel 实现利用了 Ollama Embeddings API 端点。
前置条件
您首先需要访问一个Ollama 实例。有几种选择，包括以下内容：
-
配置并使用Testcontainers运行Ollama。
-
通过Kubernetes服务绑定绑定到一个Ollama实例。
您可以从Ollama模型库拉取您想要在应用程序中使用的模型：
ollama pull <model-name>您也可以拉取数千个免费的GGUF Hugging Face 模型:
ollama pull hf.co/<username>/<model-repository>您可以启用自动下载任何所需模型的选项：自动拉取模型。
Auto-configuration
|
Spring AI自动配置和starter模块的artifact名称有了重大变化。 请参阅升级说明获取更多信息。 |
Spring AI 为 Azure Ollama 嵌入模型提供了 Spring Boot 自动配置。
要启用它，请将以下依赖项添加到您的 Maven pom.xml 或 Gradle build.gradle 构建文件中：
-
Maven
-
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 构件发布在 Maven Central 和 Spring Snapshot 仓库中。 请参阅仓库部分，将这些仓库添加到您的构建系统中。 |
基属性
前缀 spring.ai.ollama 是用于配置连接到 Ollama 的属性前缀。
<property> </property> |
<description> </description> |
默认 |
spring.ai.ollama.base-url |
Ollama API服务器正在运行的基础URL。 |
|
这里用于初始化Ollama集成和自动拉取模型的属性。
<property> </property> |
<description> </description> |
默认 |
spring.ai.ollama.init.pull-model-strategy |
是否在启动时拉取模型以及如何操作。 |
|
spring.ai.ollama.init.timeout |
等待模型拉取所需的时间。 |
|
spring.ai.ollama.init.max-retries |
模型拉取操作的最大重试次数。 |
|
spring.ai.ollama.init.embedding.include |
包含此类模型在内的初始化任务。 |
|
spring.ai.ollama.init.embedding.additional-models |
除了默认属性配置之外还需要初始化的其他模型。 |
|
嵌入属性
|
嵌入自动配置的启用和禁用现在通过前缀为 要启用，请设置 spring.ai.model.embedding=ollama（默认已启用） 要禁用，请设置 spring.ai.model.embedding=none（或任何不与 ollama 匹配的值） 此更改是为了允许配置多个模型。 |
前缀 spring.ai.ollama.embedding.options 是用于配置 Ollama 嵌入模型的属性前缀。
它包含 Ollama 请求（高级）参数，例如 model、keep-alive 和 truncate，以及 Ollama 模型 options 属性。
以下是 Ollama 嵌入模型的高级请求参数：
<property> </property> |
<description> </description> |
默认 |
spring.ai.ollama.embedding.enabled（已移除且不再生效） |
启用 Ollama 嵌入模型的自动配置。 |
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 |
剩余的 options 个属性基于 Ollama 有效参数和值 和 Ollama 类型。默认值基于：Ollama 类型默认值。
<property> </property> |
<description> </description> |
默认 |
spring.ai.ollama.embedding.options.numa |
是否使用NUMA。 |
false |
spring.ai.ollama.embedding.options.num-ctx |
设置用于生成下一个标记的上下文窗口大小。 |
2048 |
spring.ai.ollama.embedding.options.num-batch |
提示处理最大批量大小。 |
512 |
spring.ai.ollama.embedding.options.num-gpu |
发送到GPU的数量。在macOS上，默认值为1以启用metal支持，0以禁用。这里的1表示NumGPU应该动态设置。 |
-1 |
spring.ai.ollama.embedding.options.main-gpu |
当使用多个GPU时，此选项控制对于计算拆分到所有GPU上的开销不值得的小张量，在哪个GPU上进行处理。该GPU会稍微多占用一些VRAM来存储临时结果的缓冲区。 |
0 |
spring.ai.ollama.embedding.options.low-vram |
- |
false |
spring.ai.ollama.embedding.options.f16-kv |
- |
true |
spring.ai.ollama.embedding.options.logits-all |
返回所有标记的logits，而不仅仅是最后一个。要使完成返回logprobs，此设置必须为true。 |
- |
spring.ai.ollama.embedding.options.vocab-only |
仅加载词汇表，不加载权重。 |
- |
spring.ai.ollama.embedding.options.use-mmap |
默认情况下，模型会被映射到内存中，这使得系统可以根据需要仅加载必要的模型部分。然而，如果模型大小超过了您的总内存容量或系统可用内存较低时，使用mmap可能会增加换页的风险，从而负面影响性能。禁用mmap会导致加载时间变慢，但如果未启用mlock，则可能减少换页次数。请注意，如果模型大小超过总内存容量，关闭mmap将导致模型无法加载。 |
null |
spring.ai.ollama.embedding.options.use-mlock |
锁定模型在内存中，防止其在内存映射时被交换出去。这可以提高性能，但会牺牲一些内存映射的优势，因为它需要更多的RAM来运行，并且可能在模型加载到RAM时减慢加载时间。 |
false |
spring.ai.ollama.embedding.options.num-thread |
设置在计算过程中使用的线程数。默认情况下，Ollama 将检测此值以实现最佳性能。建议将此值设置为您系统中的物理 CPU 核心数量（而不是逻辑核心的数量）。0 = 由运行时决定 |
0 |
spring.ai.ollama.embedding.options.num-keep |
- |
4 |
spring.ai.ollama.embedding.options.seed |
设置用于生成的随机数种子。将此值设置为特定数字，可以在相同的提示下使模型生成相同的文字。 |
-1 |
spring.ai.ollama.embedding.options.num-predict |
当生成文本时预测的最大токен数。(-1 表示无限生成，-2 表示填充上下文) |
-1 |
spring.ai.ollama.embedding.options.top-k |
减小生成onsense的概率。数值越大（例如，100），答案的多样性越高；数值越小（例如，10），答案就越保守。 |
40 |
spring.ai.ollama.embedding.options.top-p |
与 top-k 共同工作。较高的值（例如，0.95）会导致生成更多样化的文本，而较低的值（例如，0.5）将生成更加聚焦且保守的文本。 |
0.9 |
spring.ai.ollama.embedding.options.min-p |
替代top_p，旨在确保质量和多样性的平衡。参数p表示一个Tokens被考虑的最小概率，相对于最可能Tokens的概率。例如，在p=0.05且最可能Tokens的概率为0.9的情况下，值小于0.045的logits会被过滤掉。 |
0.0 |
spring.ai.ollama.embedding.options.tfs-z |
无尾采样用于减少较少可能出现的Tokens对输出的影响。更高的值（例如，2.0）会更多地降低这些影响，而值为1.0则禁用此设置。 |
1.0 |
spring.ai.ollama.embedding.options.typical-p |
- |
1.0 |
spring.ai.ollama.embedding.options.repeat-last-n |
设置模型回溯的长度，以防止重复。默认值：64，0表示禁用，-1表示使用上下文长度。 |
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 |
- |
0.0 |
spring.ai.ollama.embedding.options.frequency-penalty |
- |
0.0 |
spring.ai.ollama.embedding.options.mirostat |
启用Mirostat采样以控制困惑度。(默认: 0，0 = 禁用，1 = Mirostat，2 = Mirostat 2.0) |
0 |
spring.ai.ollama.embedding.options.mirostat-tau |
控制输出的连贯性和多样性之间的平衡。数值较低会导致生成的文字更加集中和连贯。 |
5.0 |
spring.ai.ollama.embedding.options.mirostat-eta |
影响算法对生成文本反馈的响应速度。学习率较低会导致调整较慢，而较高的学习率会使算法更加灵敏。 |
0.1 |
spring.ai.ollama.embedding.options.penalize-newline |
- |
true |
spring.ai.ollama.embedding.options.stop |
设置要使用的停止序列。当遇到此模式时，LLM 将停止生成文本并返回。可以通过在模型文件中指定多个单独的停止参数来设置多个停止模式。 |
- |
spring.ai.ollama.embedding.options.functions |
函数列表，通过其名称标识，以便在单个提示请求中启用函数调用。具有这些名称的函数必须存在于 functionCallbacks 注册表中。 |
- |
所有以spring.ai.ollama.embedding.options开头的属性可以在运行时通过向EmbeddingRequest调用添加请求特定的运行时选项来覆盖。 |
运行时选项
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 模型。 |
有三种策略用于拉取模型：<br>
-
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);
}
}手动配置
如果您未使用 Spring Boot，可以手动配置 OllamaEmbeddingModel。
为此，请将 spring-ai-ollama 依赖项添加到项目的 Maven pom.xml 或 Gradle build.gradle 构建文件中：
-
Maven
-
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 聊天客户端 部分。 |
接下来，创建一个 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 提供了所有嵌入请求的配置信息。