Ollama 向量模型 - 零基础入门Java AI

通过 Ollama，您可以在本地运行各种AI 模型并从中生成嵌入。嵌入是一个浮点数向量（列表）。两个向量之间的距离衡量它们的相关性。小距离表示高相关性，大距离表示低相关性。 OllamaEmbeddingModel 实现利用了 Ollama Embeddings API 端点。

先决条件

您首先需要访问 Ollama 实例。有几种选择，包括：

在本地计算机上下载并安装 Ollama。
通过 Testcontainers 配置并运行 Ollama。
通过 Kubernetes 服务绑定绑定到 Ollama 实例。

您可以从 Ollama 模型库中拉取要在应用程序中使用的模型：

ollama pull <模型名称>

您还可以拉取数千个免费的 GGUF Hugging Face 模型中的任何一个：

ollama pull hf.co/<用户名>/<模型存储库>

或者，您可以启用自动下载任何所需模型的选项：自动拉取模型。

自动配置

Spring AI 自动配置、启动器模块的工件名称已发生重大更改。有关更多信息，请参阅升级说明。

Spring AI 为 Ollama Embedding 模型提供 Spring Boot 自动配置。要启用它，请将以下依赖项添加到您的 Maven pom.xml 或 Gradle build.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.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	除通过默认属性配置的模型外，要初始化的其他模型。	[]

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	要使用的支持的模型的名称。您可以使用专用的嵌入模型类型	mistral
spring.ai.ollama.embedding.options.keep_alive	控制模型在请求后将保持加载到内存中的时间。	5m
spring.ai.ollama.embedding.options.truncate	截断每个输入的末尾以适应上下文长度。如果为 false 且超出上下文长度，则返回错误。	true

其余 options 属性基于 Ollama 有效参数和值和 Ollama 类型。默认值基于：Ollama 类型默认值。

属性	描述	默认值
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 调用添加特定于请求的嵌入选项来覆盖。

运行时选项

OllamaOptions.java 提供了 Ollama 配置，例如要使用的模型、低级 GPU 和 CPU 调整等。默认选项也可以使用 spring.ai.ollama.embedding.options 属性进行配置。在启动时，使用 OllamaEmbeddingModel(OllamaApi ollamaApi, OllamaOptions defaultOptions) 配置用于所有嵌入请求的默认选项。在运行时，您可以通过在 EmbeddingRequest 中使用 OllamaOptions 实例来覆盖默认选项。例如，要覆盖特定请求的默认模型名称：

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 模型中的任何一个。

有三种拉取模型的策略：

always (在 PullModelStrategy.ALWAYS 中定义): 始终拉取模型，即使它已经可用。有助于确保您使用的是最新版本的模型。
when_missing (在 PullModelStrategy.WHEN_MISSING 中定义): 仅当模型尚不可用时才拉取模型。这可能会导致使用较旧版本的模型。
never (在 PullModelStrategy.NEVER 中定义): 从不自动拉取模型。

通过配置属性和默认选项定义的所有模型都可以在启动时自动拉取。您可以使用配置属性配置拉取策略、超时和最大重试次数：

spring:
  ai:
    ollama:
      init:
        pull-model-strategy: always
        timeout: 60s
        max-retries: 1

您可以在启动时初始化其他模型，这对于在运行时动态使用的模型很有用：

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/<用户名>/<模型存储库> 或配置自动拉取策略：自动拉取模型：

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 实现，您可以将其注入到您的类中。这是一个简单的 @Controller 类示例，它使用 EmbeddingModel 实现。

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

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

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

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 为所有嵌入请求提供配置信息。

文档有误？请协助编辑

发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！

手册

​先决条件

​自动配置

​基本属性

​Embedding 属性

​运行时选项

​自动拉取模型

​HuggingFace 模型

​示例控制器

​手动配置

文档有误？请协助编辑

先决条件

自动配置

基本属性

Embedding 属性

运行时选项

自动拉取模型

HuggingFace 模型

示例控制器

手动配置