Spring AI参考文档模型嵌入模型OllamaOllama 嵌入使用 Ollama您可以在本地运行各种 AI 模型并从中生成嵌入。嵌入是一个浮点数向量列表。两个向量之间的距离衡量它们的相关性。距离小表示相关性强距离大表示相关性弱。OllamaEmbeddingModel实现利用了 Ollama 嵌入 API 端点。前置条件您首先需要访问一个 Ollama 实例。有以下几种选择包括在本地机器上下载并安装 Ollama。通过 Testcontainers 配置和运行 Ollama。您可以从 Ollama 模型库中拉取您想在应用程序中使用的模型ollama pull模型名称您也可以拉取数以千计的免费 GGUF Hugging Face 模型中的任何一个ollama pull hf.co/用户名/模型仓库或者您可以启用自动下载所需模型的选项自动拉取模型。自动配置Spring AI 自动配置中启动器模块的工件名称发生了重大变化。更多信息请参考升级说明。Spring AI 为 Ollama 嵌入模型提供了 Spring Boot 自动配置。要启用它请将以下依赖项添加到您的 Mavenpom.xml或 Gradlebuild.gradle构建文件中MavenGradledependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-starter-model-ollama/artifactId/dependency请参考依赖管理部分将 Spring AI BOM 添加到您的构建文件中。Spring AI 工件发布在 Maven Central 和 Spring Snapshot 仓库中。请参考仓库部分将这些仓库添加到您的构建系统中。基础属性前缀spring.ai.ollama是用于配置与 Ollama 连接的基础属性。属性描述默认值spring.ai.ollama.base-urlOllama API 服务器运行的基础 URL。http://localhost:11434以下是用于初始化 Ollama 集成和自动拉取模型的属性。属性描述默认值spring.ai.ollama.init.pull-model-strategy是否在启动时拉取模型以及如何拉取。neverspring.ai.ollama.init.timeout等待拉取模型的最长时间。5mspring.ai.ollama.init.max-retries模型拉取操作的最大重试次数。0spring.ai.ollama.init.embedding.include在初始化任务中是否包含此类型的模型。truespring.ai.ollama.init.embedding.additional-models除通过默认属性配置的模型外要初始化的额外模型。[]嵌入属性嵌入自动配置的启用和禁用现在通过前缀为spring.ai.model.embedding的顶层属性进行配置。要启用设置spring.ai.model.embeddingollama默认启用。要禁用设置spring.ai.model.embeddingnone或任何不匹配ollama的值。此更改是为了允许配置多个模型。前缀spring.ai.ollama.embedding是配置 Ollama 嵌入模型的属性前缀。它包括 Ollama 请求高级参数如模型、keep-alive和truncate以及 Ollama 模型属性。以下是 Ollama 嵌入模型的高级请求参数属性描述默认值spring.ai.ollama.embedding.enabled(已移除且不再有效)启用 Ollama 嵌入模型自动配置。truespring.ai.model.embedding启用 Ollama 嵌入模型自动配置。ollamaspring.ai.ollama.embedding.model要使用的支持模型的名称。您可以使用专用的嵌入模型类型。mxbai-embed-largespring.ai.ollama.embedding.keep_alive控制请求后模型在内存中保持加载的时间。5mspring.ai.ollama.embedding.truncate截断每个输入的末尾以适应上下文长度。如果为false且超出上下文长度则返回错误。true其余选项属性基于 Ollama 有效参数和值 以及 Ollama 类型。默认值基于Ollama 类型默认值。属性描述默认值spring.ai.ollama.embedding.numa是否使用 NUMA。falsespring.ai.ollama.embedding.num-ctx设置用于生成下一个标记的上下文窗口大小。2048spring.ai.ollama.embedding.num-batch提示处理的最大批次大小。512spring.ai.ollama.embedding.num-gpu发送到 GPU 的层数。在 macOS 上默认为1以启用 Metal 支持0表示禁用。此处的1表示应动态设置 NumGPU。-1spring.ai.ollama.embedding.main-gpu使用多个 GPU 时此选项控制哪个 GPU 用于小张量因为将计算拆分到所有 GPU 的开销并不划算。相关 GPU 将使用稍多的 VRAM 来存储临时结果的暂存缓冲区。0spring.ai.ollama.embedding.low-vram-falsespring.ai.ollama.embedding.f16-kv-truespring.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将阻止模型加载。nullspring.ai.ollama.embedding.use-mlock将模型锁定在内存中防止在内存映射时被换出。这可以提高性能但会牺牲一些内存映射的优点因为它需要更多的 RAM 来运行并且可能因为模型加载到 RAM 中而减慢加载时间。falsespring.ai.ollama.embedding.num-thread设置计算期间使用的线程数。默认情况下Ollama 会检测此值以获得最佳性能。建议将此值设置为系统拥有的物理 CPU 核心数与逻辑核心数相对。0 让运行时决定。0spring.ai.ollama.embedding.num-keep-4spring.ai.ollama.embedding.seed设置用于生成的随机数种子。设置为特定数字将使模型为相同的提示生成相同的文本。-1spring.ai.ollama.embedding.num-predict生成文本时预测的最大标记数。-1 无限生成-2 填充上下文-1spring.ai.ollama.embedding.top-k降低生成无意义内容的概率。较高的值例如100会给出更多样化的答案而较低的值例如10会更保守。40spring.ai.ollama.embedding.top-p与top-k协同工作。较高的值例如0.95会导致更多样化的文本而较低的值例如0.5会生成更集中和保守的文本。0.9spring.ai.ollama.embedding.min-p作为top_p的替代方案旨在确保质量和多样性的平衡。参数p表示要考虑的标记的最小概率相对于最可能标记的概率。例如p0.05且最可能标记的概率为0.9时值小于0.045的 logits 将被过滤掉。0.0spring.ai.ollama.embedding.tfs-z无尾采样用于减少输出中不太可能的标记的影响。较高的值例如2.0会更大程度地减少影响而1.0则禁用此设置。1.0spring.ai.ollama.embedding.typical-p-1.0spring.ai.ollama.embedding.repeat-last-n设置模型回溯多远以防止重复。默认640 禁用-1num_ctx64spring.ai.ollama.embedding.temperature模型的温度。提高温度会使模型回答更具创造性。0.8spring.ai.ollama.embedding.repeat-penalty设置如何强烈地惩罚重复。较高的值例如1.5会更强烈地惩罚重复而较低的值例如0.9会更宽容。1.1spring.ai.ollama.embedding.presence-penalty-0.0spring.ai.ollama.embedding.frequency-penalty-0.0spring.ai.ollama.embedding.mirostat启用 Mirostat 采样以控制困惑度。默认00 禁用1 Mirostat2 Mirostat 2.00spring.ai.ollama.embedding.mirostat-tau控制输出连贯性和多样性之间的平衡。较低的值会导致更集中和连贯的文本。5.0spring.ai.ollama.embedding.mirostat-eta影响算法对生成文本反馈的响应速度。较低的学习率会导致调整较慢而较高的学习率会使算法响应更灵敏。0.1spring.ai.ollama.embedding.penalize-newline-truespring.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的一部分。例如要为特定请求覆盖默认模型名称EmbeddingResponseembeddingResponseembeddingModel.call(newEmbeddingRequest(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中定义从不自动拉取模型。由于下载模型可能存在延迟自动拉取不推荐用于生产环境。建议提前评估并预先下载必要的模型。所有通过配置属性和默认选项定义的模型都可以在启动时自动拉取。您可以使用配置属性配置拉取策略、超时时间和最大重试次数spring:ai:ollama:init:pull-model-strategy:alwaystimeout:60smax-retries:1应用程序将在所有指定模型在 Ollama 中可用之前完成初始化。根据模型大小和互联网连接速度这可能会显著减慢应用程序的启动时间。您可以在启动时初始化额外的模型这对于在运行时动态使用的模型很有用spring:ai:ollama:init:pull-model-strategy:alwaysembedding:additional-models:-mxbai-embed-large-nomic-embed-text如果您想仅将拉取策略应用于特定类型的模型您可以从初始化任务中排除嵌入模型spring:ai:ollama:init:pull-model-strategy:alwaysembedding:include:false此配置将把拉取策略应用于除嵌入模型之外的所有模型。HuggingFace 模型Ollama 可以开箱即用地访问所有 GGUF Hugging Face 嵌入模型。您可以通过名称拉取这些模型中的任何一个ollama pull hf.co/用户名/模型仓库或配置自动拉取策略自动拉取模型。spring.ai.ollama.embedding.modelhf.co/mixedbread-ai/mxbai-embed-large-v1 spring.ai.ollama.init.pull-model-strategyalwaysspring.ai.ollama.embedding.model指定要使用的 Hugging Face GGUF 模型。spring.ai.ollama.init.pull-model-strategyalways可选在启动时启用自动模型拉取。对于生产环境您应该预先下载模型以避免延迟ollama pull hf.co/mixedbread-ai/mxbai-embed-large-v1。示例控制器这将创建一个您可以注入到类中的EmbeddingModel实现。下面是一个简单的Controller类示例它使用了EmbeddingModel实现。RestControllerpublicclassEmbeddingController{privatefinalEmbeddingModelembeddingModel;AutowiredpublicEmbeddingController(EmbeddingModelembeddingModel){this.embeddingModelembeddingModel;}GetMapping(/ai/embedding)publicMapembed(RequestParam(valuemessage,defaultValueTell me a joke)Stringmessage){EmbeddingResponseembeddingResponsethis.embeddingModel.embedForResponse(List.of(message));returnMap.of(embedding,embeddingResponse);}}手动配置如果您不使用 Spring Boot您可以手动配置OllamaEmbeddingModel。为此请将spring-ai-ollama依赖项添加到您项目的 Mavenpom.xml或 Gradlebuild.gradle构建文件中MavenGradledependencygroupIdorg.springframework.ai/groupIdartifactIdspring-ai-ollama/artifactId/dependency请参考依赖管理部分将 Spring AI BOM 添加到您的构建文件中。spring-ai-ollama依赖项还提供了对OllamaChatModel的访问。有关OllamaChatModel的更多信息请参考 Ollama 聊天客户端部分。接下来创建一个OllamaEmbeddingModel实例并使用它来计算两个输入文本的嵌入使用专用的chroma/all-minilm-l6-v2-f32嵌入模型varollamaApiOllamaApi.builder().build();varembeddingModelnewOllamaEmbeddingModel(this.ollamaApi,OllamaEmbeddingOptions.builder().model(OllamaModel.MISTRAL.id()).build());EmbeddingResponseembeddingResponsethis.embeddingModel.call(newEmbeddingRequest(List.of(Hello World,World is big and salvation is near),OllamaEmbeddingOptions.builder().model(chroma/all-minilm-l6-v2-f32).truncate(false).build()));OllamaEmbeddingOptions提供了所有嵌入请求的配置信息。