|
获取最新的快照版本，请使用 Spring AI 1.1.3！ |
Ollama 嵌入
前提条件
首先，您需要访问一个Ollama实例。有几种选择，包括以下：
-
通过Kubernetes服务绑定连接到Ollama实例。
您可以在应用程序中从Ollama模型库拉取所需模型：
ollama pull <model-name>您也可以拉取数千个免费的Hugging Face GGUF模型:
ollama pull hf.co/<username>/<model-repository>另外，您可以启用自动下载所需模型的选项： 模型自动拉取.
自动配置
|
There has been a significant change in the Spring AI auto-configuration, starter modules' artifact names. Please refer to the 升级说明以获取更多信息。 |
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快照仓库中。 请参阅仓库部分，将这些仓库添加到您的构建系统中。 |
基本属性
前缀 spring.ai.ollama 是用于配置与Ollama连接的属性前缀
属性 |
描述 |
默认 |
spring.ai.ollama.base-url |
Ollama API 服务器运行的基础URL。 |
|
这里是初始化Ollama集成和自动拉取模型的属性设置。
属性 |
描述 |
默认 |
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嵌入模型的高级请求参数：
属性 |
描述 |
默认 |
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 |
截断每个输入的尾部以适应上下文长度。如果超出上下文长度且为假，则返回错误。 |
true |
剩余的 options 个属性基于 Ollama 有效参数及值 和 Ollama 类型。默认值依据：Ollama 类型默认值。
属性 |
描述 |
默认 |
spring.ai.ollama.embedding.options.numa |
是否使用NUMA。 |
false |
spring.ai.ollama.embedding.options.num-ctx |
设置用于生成下一个Tokens的上下文窗口的大小。 |
2048 |
spring.ai.ollama.embedding.options.num-batch |
提示处理最大批次大小。 |
512 |
spring.ai.ollama.embedding.options.num-gpu |
发送到GPU(s)的层数。在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 |
为所有Tokens返回logits，而不仅仅是最后一个。为了使 completions 能够返回 logprobs，此选项必须为真。 |
- |
spring.ai.ollama.embedding.options.vocab-only |
仅加载词汇表，不加载权重。 |
- |
spring.ai.ollama.embedding.options.use-mmap |
默认情况下，模型会被映射到内存中，这使得系统能够按需只加载模型的必要部分。然而，如果模型大小超过您总RAM量，或者系统可用内存较低，使用mmap可能会增加页面交换的风险，从而负面影响性能。禁用mmap会导致加载时间变慢，但如果未使用mlock，可能会减少页面调度。请注意，如果模型大小超过总RAM量，关闭mmap将根本阻止模型加载。 |
空值 |
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 |
生成文本时预测的最大Tokens数量。(-1 = 无限生成, -2 = 填充上下文) |
-1 |
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.min-p |
作为`top_p`的替代方案，旨在确保质量和多样性的平衡。参数p表示一个标记被考虑的最低概率，相对于最可能标记的概率。例如，如果p=0.05且最可能的标记概率为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表示回溯长度等于上下文数量(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 |
- |
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调用中添加特定于请求的运行时选项在运行时覆盖。 |
运行时选项
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属性进行配置。
在启动时，使用OllamaEmbeddingModel(OllamaApi ollamaApi, OllamaOptions defaultOptions)来配置所有嵌入请求使用的默认选项。
在运行时，您可以使用OllamaOptions实例作为EmbeddingRequest的一部分来覆盖默认选项。
例如，要为特定请求覆盖默认的模型名称：
EmbeddingResponse embeddingResponse = embeddingModel.call(
new EmbeddingRequest(List.of("Hello World", "World is big and salvation is near"),
OllamaOptions.builder()
.model("Different-Embedding-Model-Deployment-Name"))
.truncates(false)
.build());模型自动拉取
Spring AI Ollama 可在您的 Ollama 实例中未提供模型时自动拉取它们。 此功能对于开发和测试特别有用，同时也适用于将您的应用程序部署到新环境。
| 您也可以按名称拉取任何数千个免费的Hugging Face GGUF模型。 |
模型拉取有三种策略：
-
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,
OllamaOptions.builder()
.model(OllamaModel.MISTRAL.id())
.build());
EmbeddingResponse embeddingResponse = this.embeddingModel.call(
new EmbeddingRequest(List.of("Hello World", "World is big and salvation is near"),
OllamaOptions.builder()
.model("chroma/all-minilm-l6-v2-f32"))
.truncate(false)
.build());数字OllamaOptions为所有嵌入请求提供了配置信息。