10分钟Spring AI 从入门到放弃：Ollama本地模型+Function Call配置避坑指南

1. 为什么你的 Spring AI 一接 Ollama 就报错Spring AI 是 Spring 官方推出的 AI 工程应用框架它把连接大模型、向量库、工具调用这些事抽象成了一套 Spring 风格的 API让你用注入 Bean 的方式就能调模型。SpringBoot 项目接入 Spring AI 后最典型的入门路径就是本地跑一个 Ollama 模型再挂上 Function Call现在官方叫 Tool Call做工具调用。适合谁适合已经有 SpringBoot 基础、想快速把大模型能力塞进现有 Java 服务的同学。但现实往往很骨感。我见过太多人卡在三个地方一是 pom 依赖拉不下来因为 Spring AI 的里程碑版本不在阿里云镜像里二是启动直接抛OpenAI API key must be set明明用的是本地 Ollama 却要你填 OpenAI 的 key三是兴致勃勃写了个 Function Call结果模型回你一句does not support tools当场从入门到放弃。这篇就按“能跑起来”的目标来写。我会给你可复制的pom.xml和application.yml骨架、Ollama 连接参数、Function Call 注册代码再配上启动验证和常见报错排查。你照着敲十分钟内应该能看到模型正常回话而不是对着红色堆栈发呆。需要说明的是本文聚焦本地 Ollama 接入和 Tool Call 配置不涉及复杂 RAG 和向量库。如果你连 SpringBoot 的 Controller 和依赖注入都不熟建议先补一下基础再来否则报错会看得比较痛苦。2. 前置准备Ollama 与 TaoToken 的分工先说清楚本地模型和云端 API 的关系避免你走弯路。Ollama 负责在你本机跑模型优点是数据不出本地、免费、断网可用缺点是吃硬件小模型能力有限而且不是所有模型都支持 Tool Call。TaoToken 则是当你需要更强模型、或者本地机器带不动时用来统一接入云端模型的入口。它的 API 地址是https://taotoken.net/api兼容主流调用方式你可以在不改业务代码结构的前提下把base-url从本地切到云端。我试过的一个实用组合是日常调试用 Ollama 跑小模型省资源遇到需要复杂推理或工具调用的场景切到 TaoToken 上的模型。这样既保留了本地开发的便利又不会被本地硬件卡死。在动手前你需要准备两样东西第一Ollama 已经装好并能正常ollama run一个模型。去 Ollama 官网下载对应系统的安装包无脑安装后命令行执行ollama list能看到模型列表就算成功。第二一个可用的模型。入门建议先拉llama3.2:3B它体积小、支持 Tool Call适合验证功能。命令是ollama pull llama3.2:3B。如果你手头有deepseek-r1:1.5b也可以先拿来跑通普通对话但记住它不支持工具调用后面 Function Call 环节要换掉。如果你打算用 TaoToken 作为云端补充先去控制台创建一个 API Key后面配置里会用到。地址在https://taotoken.net/console创建 Key 的页面是https://taotoken.net/api-keys。这个 Key 只在切云端时用纯本地 Ollama 调试可以先不填。3. 可复制配置pom.xml 与 application.yml 骨架这一节是重头戏配置错一个字符就可能启动失败。我直接把能跑的骨架贴出来你按需改版本号。3.1 pom.xml 关键部分Spring AI 的里程碑版本不在阿里云公共仓库里所以 Maven 镜像要放行spring-milestones。先改你的settings.xmlmirror idalimaven/id namealiyun maven/name urlhttps://maven.aliyun.com/nexus/content/groups/public//url mirrorOf*,!spring-milestones/mirrorOf /mirror注意mirrorOf里的*,!spring-milestones少了这个感叹号配置依赖会一直拉不下来。然后是工程根pom.xml?xml version1.0 encodingUTF-8? project xmlnshttp://maven.apache.org/POM/4.0.0 xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd modelVersion4.0.0/modelVersion parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version3.4.4/version relativePath/ /parent groupIdorg.example/groupId artifactIdspringai-ollama-demo/artifactId version0.0.1-SNAPSHOT/version properties java.version17/java.version spring-ai.version1.0.0-M6/spring-ai.version /properties dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-ollama-spring-boot-starter/artifactId /dependency dependency groupIdorg.projectlombok/groupId artifactIdlombok/artifactId optionaltrue/optional /dependency /dependencies dependencyManagement dependencies dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-bom/artifactId version${spring-ai.version}/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement /project两个硬性约束SpringBoot 必须 3.x.xJava 必须 17 及以上。Spring AI 1.0.0-M6 对这两个有强依赖用 Java 8 或 SpringBoot 2.x 会直接编译不过。3.2 application.yml 配置spring: application: name: springai-ollama-demo ai: ollama: base-url: http://localhost:11434 chat: model: llama3.2:3B options: temperature: 0.7 openai: api-key: sk-local-placeholder这里有个坑必须提前说spring.ai.openai.api-key看起来莫名其妙你明明用的是 Ollama为什么还要配 OpenAI 的 key原因是 Spring AI 的自动配置在初始化OpenAiChatModel时会校验这个属性不填就抛OpenAI API key must be set进程直接挂掉。本地调试随便填个占位符就行它不会真的去调 OpenAI。base-url指向 Ollama 默认端口 11434chat.model写你ollama list里实际存在的模型名大小写和冒号都要一致。4. 验证请求从普通对话到 Function Call配置好了先跑通最简单的对话再上工具调用。4.1 普通对话验证写一个 Controllerimport jakarta.annotation.Resource; import org.springframework.ai.ollama.OllamaChatModel; import org.springframework.web.bind.annotation.*; RestController public class AIController { Resource private OllamaChatModel ollamaChatModel; GetMapping(/chat) public String chat(RequestParam(message) String message) { String prompt 你是一名翻译将输入的英文翻译成中文; return ollamaChatModel.call(prompt : message); } }启动项目浏览器访问http://localhost:8080/chat?messagehello world如果返回中文翻译说明 Ollama 连接和模型调用都通了。这一步不通先别往下走去排查第 5 节的连接问题。4.2 Function Call 注册代码Function Call 在 Spring AI 1.0.0-M6 里已经改名叫 Tool Call旧的FunctionCallback废弃了要用ToolCallback。先定义一个工具类import java.time.LocalDateTime; import java.time.format.DateTimeFormatter; public class DateTimeTools { public String getCurrentTime() { return LocalDateTime.now() .format(DateTimeFormatter.ofPattern(yyyy-MM-dd HH:mm:ss)); } }然后在 Controller 里注册并调用import org.springframework.ai.chat.client.ChatClient; import org.springframework.ai.chat.model.ChatResponse; import org.springframework.ai.chat.prompt.Prompt; import org.springframework.ai.model.tool.ToolCallingChatOptions; import org.springframework.ai.tool.ToolCallback; import org.springframework.ai.tool.ToolCallbacks; GetMapping(/time) public String time(RequestParam(message) String message) { ToolCallback[] dateTimeTools ToolCallbacks.from(new DateTimeTools()); ToolCallingChatOptions chatOptions ToolCallingChatOptions.builder() .toolCallbacks(dateTimeTools) .build(); Prompt prompt new Prompt(message, chatOptions); ChatResponse chatResponse ollamaChatModel.call(prompt); return chatResponse.getResult().getOutput().getText(); }访问http://localhost:8080/time?message现在几点了如果模型返回类似“现在时间是 16:59”的内容说明 Tool Call 注册成功。这里的关键是模型必须支持工具调用。如果你用deepseek-r1:1.5b会直接报registry.ollama.ai/library/deepseek-r1:1.5b does not support tools。换成llama3.2:3B就能过。这不是代码问题是模型能力问题。4.3 切到 TaoToken 云端模型如果本地模型能力不够或者你想用更强的模型做工具调用把配置改成云端即可。API 地址用https://taotoken.net/apiKey 从控制台拿。改完base-url和api-key业务代码一行不用动。想先在线验证模型效果可以直接用模型对话页面https://taotoken.net/models试几句确认模型支持你要的功能再切。5. 本篇常见报错排查把踩过的坑集中列一下对照着查能省不少时间。报错一OpenAI API key must be set现象是启动直接失败堆栈指向OpenAiChatModel初始化。原因就是spring.ai.openai.api-key没配。解决在application.yml里随便填一个非空值比如sk-local-placeholder。本地 Ollama 场景下它只是占位不会真的发起 OpenAI 请求。报错二does not support tools现象是调用/time接口时返回 400提示模型不支持 tools。原因是当前chat.model指向的模型没有工具调用能力。解决换成支持 Tool Call 的模型比如llama3.2:3B然后ollama pull拉下来改配置重启。报错三依赖拉不下来spring-ai-ollama-spring-boot-starter找不到现象是 Maven 一直报Could not resolve dependencies。原因是阿里云镜像没有 Spring AI 的里程碑包。解决检查settings.xml的mirrorOf是否写成*,!spring-milestones确保spring-milestones仓库不被镜像拦截。报错四Connection refused: localhost:11434现象是启动能过但一调接口就连接被拒。原因是 Ollama 服务没启动或者端口不对。解决命令行执行ollama list能列出模型说明服务在跑如果没反应重新启动 Ollama。确认base-url端口是 11434。报错五模型名写错导致 404现象是调用返回模型不存在。原因是chat.model和ollama list里的名字不一致比如大小写、冒号后的 tag 写错。解决复制ollama list输出的完整名称粘贴到配置里。报错六Java 版本不匹配现象是编译报invalid target release: 17或类似。原因是本地 JDK 低于 17。解决在 IDEA 里把项目 SDK 和语言级别都设成 17 或更高pom.xml里java.version也确认是 17。排查顺序建议先确认 Ollama 服务活着再确认模型名对再看配置项拼写最后看依赖和 JDK。大部分“从入门到放弃”都卡在前两步。6. 继续往下走的方向跑通对话和 Tool Call 之后你手里就有了一套能用的 SpringBoot Spring AI Ollama 骨架。接下来可以往几个方向延伸接向量库做 RAG把文档读取、分段、向量化串成管道或者把 Tool Call 扩展成多个工具让模型根据用户意图自动选择调用哪个再或者把本地模型和云端模型做成可切换的配置按场景分流。如果你打算长期做编码类或 Agent 类项目可以了解一下 Coding Plan它更适合持续性的开发场景地址是https://taotoken.net/coding-plan。接入过程中遇到具体报错接入文档在https://taotoken.net/docAPI Keys 管理在https://taotoken.net/api-keys按需取用。最后留一个实用建议本地调试阶段把temperature调低一点比如 0.2工具调用的稳定性会好很多模型不容易“自由发挥”去编造工具名。这个参数在spring.ai.ollama.chat.options.temperature里改改完重启即可。