> ## Documentation Index
> Fetch the complete documentation index at: https://javaai.pig4cloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Ollama 向量模型
通过 [Ollama](https://ollama.ai/)，您可以在本地运行各种[AI 模型](https://ollama.com/search?c=embedding)并从中生成嵌入。
嵌入是一个浮点数向量（列表）。
两个向量之间的距离衡量它们的相关性。
小距离表示高相关性，大距离表示低相关性。
`OllamaEmbeddingModel` 实现利用了 Ollama [Embeddings API](https://github.com/ollama/ollama/blob/main/docs/api.md#generate-embeddings) 端点。
## 先决条件
您首先需要访问 Ollama 实例。有几种选择，包括：
* 在本地计算机上[下载并安装 Ollama](https://ollama.com/download)。
* 通过 [Testcontainers](/spring4ai/api/testcontainers) 配置并运行 Ollama。
* 通过 [Kubernetes 服务绑定](/spring4ai/api/cloud-bindings)绑定到 Ollama 实例。
您可以从 [Ollama 模型库](https://ollama.com/search?c=embedding)中拉取要在应用程序中使用的模型：
```bash theme={"system"}
ollama pull <模型名称>
```
您还可以拉取数千个免费的 [GGUF Hugging Face 模型](https://huggingface.co/models?library=gguf\&sort=trending)中的任何一个：
```bash theme={"system"}
ollama pull hf.co/<用户名>/<模型存储库>
```
或者，您可以启用自动下载任何所需模型的选项：[自动拉取模型](#auto-pulling-models)。
## 自动配置
Spring AI 自动配置、启动器模块的工件名称已发生重大更改。
有关更多信息，请参阅[升级说明](https://docs.spring.io/spring-ai/reference/upgrade-notes.html)。
Spring AI 为 Ollama Embedding 模型提供 Spring Boot 自动配置。
要启用它，请将以下依赖项添加到您的 Maven `pom.xml` 或 Gradle `build.gradle` 构建文件中：
```xml theme={"system"}
org.springframework.ai
spring-ai-starter-model-ollama
```
```groovy theme={"system"}
dependencies {
implementation 'org.springframework.ai:spring-ai-starter-model-ollama'
}
```
请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分将 Spring AI BOM 添加到您的构建文件中。
### 基本属性
前缀 `spring.ai.ollama` 是用于配置与 Ollama 连接的属性前缀。
| 属性 | 描述 | 默认值 |
| :------------------------ | :----------------------- | :----------------------------------------------- |
| spring.ai.ollama.base-url | Ollama API 服务器运行的基本 URL。 | [http://localhost:11434](http://localhost:11434) |
以下是初始化 Ollama 集成和[自动拉取模型](#auto-pulling-models)的属性。
| 属性 | 描述 | 默认值 |
| :------------------------------------------------ | :----------------------- | :---- |
| 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 | 除通过默认属性配置的模型外，要初始化的其他模型。 | \[] |
### Embedding 属性
Embedding 自动配置的启用和禁用现在通过前缀为 `spring.ai.model.embedding` 的顶级属性进行配置。
要启用，请设置 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 | 要使用的[支持的模型](https://github.com/ollama/ollama?tab=readme-ov-file#model-library)的名称。您可以使用专用的[嵌入模型](https://ollama.com/search?c=embedding)类型 | mistral |
| spring.ai.ollama.embedding.options.keep\_alive | 控制模型在请求后将保持加载到内存中的时间。 | 5m |
| spring.ai.ollama.embedding.options.truncate | 截断每个输入的末尾以适应上下文长度。如果为 false 且超出上下文长度，则返回错误。 | true |
其余 `options` 属性基于 [Ollama 有效参数和值](https://github.com/ollama/ollama/blob/main/docs/modelfile.md#valid-parameters-and-values) 和 [Ollama 类型](https://github.com/ollama/ollama/blob/main/api/types.go)。默认值基于：[Ollama 类型默认值](https://github.com/ollama/ollama/blob/b538dc3858014f94b099730a592751a5454cab0a/api/types.go#L364)。
| 属性 | 描述 | 默认值 |
| :--------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---- |
| 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 | 默认情况下，模型映射到内存中，这允许系统仅根据需要加载模型的必要部分。但是，如果模型大于您的总 RAM 量，或者如果您的系统可用内存不足，则使用 mmap 可能会增加页面换出的风险，从而对性能产生负面影响。禁用 mmap 会导致加载时间变慢，但如果您不使用 mlock，则可能会减少页面换出。请注意，如果模型大于总 RAM 量，则关闭 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 | 降低生成无意义内容的概率。较高的值（例如 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 | 无尾采样用于减少输出中不太可能的令牌的影响。较高的值（例如 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` 调用添加特定于请求的[嵌入选项](#embedding-options)来覆盖。
## 运行时选项
[OllamaOptions.java](https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-ollama/src/main/java/org/springframework/ai/ollama/api/OllamaOptions.java) 提供了 Ollama 配置，例如要使用的模型、低级 GPU 和 CPU 调整等。
默认选项也可以使用 `spring.ai.ollama.embedding.options` 属性进行配置。
在启动时，使用 `OllamaEmbeddingModel(OllamaApi ollamaApi, OllamaOptions defaultOptions)` 配置用于所有嵌入请求的默认选项。
在运行时，您可以通过在 `EmbeddingRequest` 中使用 `OllamaOptions` 实例来覆盖默认选项。
例如，要覆盖特定请求的默认模型名称：
```java theme={"system"}
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());
```
## 自动拉取模型
当 Ollama 实例中没有可用模型时，Spring AI Ollama 可以自动拉取模型。
此功能对于开发和测试以及将应用程序部署到新环境特别有用。
您还可以按名称拉取数千个免费的 [GGUF Hugging Face 模型](https://huggingface.co/models?library=gguf\&sort=trending)中的任何一个。
有三种拉取模型的策略：
* `always` (在 `PullModelStrategy.ALWAYS` 中定义): 始终拉取模型，即使它已经可用。有助于确保您使用的是最新版本的模型。
* `when_missing` (在 `PullModelStrategy.WHEN_MISSING` 中定义): 仅当模型尚不可用时才拉取模型。这可能会导致使用较旧版本的模型。
* `never` (在 `PullModelStrategy.NEVER` 中定义): 从不自动拉取模型。
由于下载模型时可能会出现延迟，因此不建议在生产环境中使用自动拉取。相反，请考虑提前评估和预下载必要的模型。
通过配置属性和默认选项定义的所有模型都可以在启动时自动拉取。
您可以使用配置属性配置拉取策略、超时和最大重试次数：
```yaml theme={"system"}
spring:
ai:
ollama:
init:
pull-model-strategy: always
timeout: 60s
max-retries: 1
```
在 Ollama 中所有指定的模型都可用之前，应用程序不会完成其初始化。根据模型大小和互联网连接速度，这可能会显著减慢应用程序的启动时间。
您可以在启动时初始化其他模型，这对于在运行时动态使用的模型很有用：
```yaml theme={"system"}
spring:
ai:
ollama:
init:
pull-model-strategy: always
embedding:
additional-models:
- mxbai-embed-large
- nomic-embed-text
```
如果只想将拉取策略应用于特定类型的模型，则可以从初始化任务中排除嵌入模型：
```yaml theme={"system"}
spring:
ai:
ollama:
init:
pull-model-strategy: always
embedding:
include: false
```
此配置将拉取策略应用于除嵌入模型之外的所有模型。
## HuggingFace 模型
Ollama 可以开箱即用地访问所有 [GGUF Hugging Face](https://huggingface.co/models?library=gguf\&sort=trending) 嵌入模型。
您可以按名称拉取这些模型中的任何一个：`ollama pull hf.co/<用户名>/<模型存储库>` 或配置自动拉取策略：[自动拉取模型](#auto-pulling-models)：
```
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 模型](https://huggingface.co/models?library=gguf\&sort=trending)。
* `spring.ai.ollama.init.pull-model-strategy=always`: (可选) 启用启动时自动拉取模型。
对于生产环境，您应该预先下载模型以避免延迟：`ollama pull hf.co/mixedbread-ai/mxbai-embed-large-v1`。
## 示例控制器
这将创建一个 `EmbeddingModel` 实现，您可以将其注入到您的类中。
这是一个简单的 `@Controller` 类示例，它使用 `EmbeddingModel` 实现。
```java theme={"system"}
@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` 文件中：
```xml theme={"system"}
org.springframework.ai
spring-ai-ollama
```
或添加到您的 Gradle `build.gradle` 构建文件中。
```groovy theme={"system"}
dependencies {
implementation 'org.springframework.ai:spring-ai-ollama'
}
```
请参阅[依赖管理](/spring4ai/getting-started#dependency-management)部分将 Spring AI BOM 添加到您的构建文件中。
`spring-ai-ollama` 依赖项还提供对 `OllamaChatModel` 的访问。
有关 `OllamaChatModel` 的更多信息，请参阅 [Ollama 聊天客户端](/spring4ai/api/chat/ollama-chat)部分。
接下来，创建一个 `OllamaEmbeddingModel` 实例，并使用它通过专用的 `chroma/all-minilm-l6-v2-f32` 嵌入模型计算两个输入文本的嵌入：
```java theme={"system"}
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` 为所有嵌入请求提供配置信息。
发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！