1. 项目概述：Spring AI与Ollama的本地大模型集成
最近在搞一个内部知识库问答系统，不想把敏感数据送到云端，就琢磨着在本地部署大模型。Ollama这个工具挺火的，能一键拉取和运行各种开源模型，而Spring AI作为Spring生态的AI集成框架，提供了统一的操作接口。把这两者结合起来，就能在熟悉的Spring Boot应用里，轻松调用本地部署的LLM，实现聊天、推理、多模态甚至工具调用这些高级功能。这不仅仅是技术选型，更是一种架构思路：将强大的AI能力以“基础设施”的方式，低成本、高可控地集成到现有Java应用中。无论是快速验证一个AI点子，还是构建严肃的生产级智能应用，这个组合都提供了极大的灵活性。
2. 核心思路与架构设计
2.1 为什么是Spring AI + Ollama？
选择这个组合，背后有几个核心考量。首先是技术栈统一，团队主力是Java/Spring技术栈，引入Python或Node.js的AI服务会增加运维和集成的复杂度。Spring AI抽象了底层模型差异，提供了一套统一的ChatModel、EmbeddingModel等API，让开发者可以用同一种方式调用Ollama、OpenAI、Azure OpenAI等不同后端的模型，极大降低了切换成本。
其次是数据安全与成本可控。所有数据在本地流转，完全规避了敏感数据上云的风险和合规问题。Ollama支持在消费级硬件（甚至带GPU的笔记本）上运行量化后的模型，推理成本几乎为零，特别适合对响应延迟要求不高、但数据隐私要求极高的内部工具或原型验证阶段。
再者是开发体验与生态整合。Spring Boot的自动配置、外部化配置（application.yml）、依赖注入等特性，让集成变得异常简单。你可以像配置一个数据库连接池一样配置你的AI模型服务。同时，Spring AI天然支持与Spring生态的其他组件（如Spring Data Vector Store用于RAG，Spring Integration用于流程编排）无缝集成，为构建复杂的AI应用提供了坚实基础。
2.2 整体架构与数据流
一个典型的Spring AI + Ollama应用架构可以分为三层。应用层是你的Spring Boot服务，包含业务逻辑、控制器和Spring AI的ChatClient或ChatModelBean。AI抽象层由Spring AI提供，它定义了标准的接口（如ChatModel），并提供了Ollama的具体实现（OllamaChatModel）。这一层负责将你的请求（Prompt）转换为Ollama API能理解的格式，并将响应解析回来。模型服务层就是Ollama本身，它作为一个独立的进程（或容器）运行，管理着本地的模型文件，并提供HTTP API供Spring AI调用。
数据流也很清晰：用户请求到达Spring MVC控制器 -> 控制器调用注入的OllamaChatModel.call(Prompt)-> Spring AI的Ollama客户端将请求封装为JSON，通过HTTP发送到localhost:11434-> Ollama服务加载模型并进行推理 -> 推理结果通过HTTP返回 -> Spring AI解析响应，封装为ChatResponse对象 -> 控制器将结果返回给用户。整个过程对开发者是透明的，你只需要关心业务Prompt和结果处理。
3. 环境准备与项目初始化
3.1 Ollama的安装与模型部署
第一步是在你的开发或服务器环境安装Ollama。访问Ollama官网下载对应操作系统的安装包是最直接的方式。对于国内用户，从官网下载可能比较慢，可以考虑使用国内镜像源加速。例如，在Linux/macOS上，可以通过修改环境变量来指定镜像源进行下载和拉取模型。安装完成后，在终端运行ollama --version验证是否成功。
Ollama安装好后，核心操作是拉取模型。使用ollama pull <model-name>命令，例如ollama pull llama3.2:3b。这里有几个实操要点：一是模型选择，对于入门和大多数应用场景，llama3.2:3b、qwen2.5:3b这类较小的模型在8G内存的机器上就能流畅运行，响应速度也较快。如果硬件资源充足（如有NVIDIA GPU且显存>=8G），可以尝试llama3.2:7b、qwen2.5:7b或deepseek-r1:7b等更大模型以获得更好效果。二是版本标签，llama3.2:3b指定了模型家族和参数量，你也可以拉取llama3.2:latest获取最新版本，但在生产环境建议固定版本以避免不可预期的行为变化。
注意：首次拉取模型可能会耗时较长，取决于模型大小和网络。建议在项目开发初期就提前下载好所需模型。可以通过
ollama list查看已下载的模型。
3.2 Spring Boot项目创建与依赖引入
接下来创建Spring Boot项目。使用你最熟悉的工具，比如Spring Initializr（start.spring.io），选择最新的Spring Boot 3.x版本，打包方式选Maven或Gradle，语言选Java，并添加Spring Web依赖。
关键一步是添加Spring AI的Ollama starter依赖。由于Spring AI的版本管理独立于Spring Boot，我们需要在pom.xml中先引入Spring AI的BOM（物料清单）来统一管理版本，然后再添加具体依赖。
Maven配置示例 (pom.xml):
<dependencyManagement> <dependencies> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-bom</artifactId> <version>1.0.0-M5</version> <!-- 使用最新稳定版 --> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement> <dependencies> <!-- 其他依赖，如 spring-boot-starter-web --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <!-- Spring AI Ollama Starter --> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-ollama-spring-boot-starter</artifactId> </dependency> </dependencies>Gradle配置示例 (build.gradle):
dependencyManagement { imports { mavenBom "org.springframework.ai:spring-ai-bom:1.0.0-M5" } } dependencies { implementation 'org.springframework.boot:spring-boot-starter-web' implementation 'org.springframework.ai:spring-ai-ollama-spring-boot-starter' }引入BOM后，所有Spring AI相关依赖的版本都会自动对齐，避免版本冲突。添加完依赖，一个基础的Spring AI + Ollama项目骨架就准备好了。
4. 核心配置详解与最佳实践
4.1 基础连接与模型配置
配置是发挥Spring Boot威力的地方。在application.yml（或application.properties）中，我们可以细致地控制Ollama连接和模型行为。
spring: ai: ollama: # Ollama服务地址，默认本地11434端口 base-url: http://localhost:11434 # 初始化配置：控制模型自动拉取行为 init: pull-model-strategy: when_missing # 可选: never, when_missing, always timeout: 10m # 拉取模型超时时间 max-retries: 1 # 拉取失败重试次数 # 聊天模型配置 chat: # 启用Ollama作为默认聊天模型 (Spring AI 1.x 配置方式) enabled: true # 指定使用的模型名称，必须与ollama list中的名称一致 model: llama3.2:3b # 模型运行时参数 options: temperature: 0.7 # 创造性，越高越随机 num-predict: 512 # 生成的最大token数，-1表示无限制 top-k: 40 # 采样范围，影响多样性 top-p: 0.9 # 核采样，影响聚焦程度 repeat-penalty: 1.1 # 重复惩罚，降低重复内容 num-ctx: 2048 # 上下文窗口大小这里有几个关键配置项需要理解。spring.ai.ollama.init.pull-model-strategy决定了应用启动时模型不存在怎么办。never（默认）要求模型必须已存在，适合生产环境；when_missing会在模型不存在时自动拉取，适合开发；always则每次启动都拉取，确保是最新版，但会严重拖慢启动速度。
model参数必须与Ollama中拉取的模型名称完全一致。模型参数如temperature、top-p等直接影响生成质量。temperature（温度）控制随机性：0.1-0.3适合事实性问答，输出稳定；0.7-0.9适合创意写作，输出多样。num-predict限制生成长度，防止模型“话痨”。num-ctx是上下文窗口，决定了模型能“记住”多长的对话历史，更大的窗口能处理更长的文档，但也消耗更多内存。
4.2 高级特性配置：思考模式与结构化输出
Ollama和Spring AI支持一些高级特性，能显著提升应用能力。
思考模式：对于qwen3、deepseek-r1这类具备“思维链”能力的模型，可以启用思考模式，让模型先输出推理过程，再给出最终答案。这在解决数学、逻辑问题时非常有用，也便于调试。
spring: ai: ollama: chat: options: model: deepseek-r1:7b # 启用思考模式（仅支持该特性的模型） think: true在代码中，你可以从响应元数据中提取思考内容：
ChatResponse response = chatModel.call(prompt); String thinking = response.getResult().getMetadata().get("thinking"); String finalAnswer = response.getResult().getOutput().getText();结构化输出：这是生产级应用的关键。你可以要求模型严格按照指定的JSON Schema格式返回数据，方便后端直接解析成对象。例如，让模型总结一篇文章，并返回标题、作者、关键点列表等结构化信息。
spring: ai: ollama: chat: options: model: llama3.2:7b # 指定输出格式为JSON（简单模式） format: json # 或者，使用JSON Schema强制结构（推荐） # 配置需通过代码中的OllamaChatOptions设置在代码中，通过OllamaChatOptions的outputSchema方法设置JSON Schema字符串，可以确保输出格式的确定性。
4.3 多模型与运行时配置覆盖
一个应用可能需要根据场景切换不同模型。Spring AI允许你定义多个ChatModelBean，或者更灵活地，在运行时通过Prompt的选项来覆盖默认配置。
定义多个模型Bean：
@Configuration public class OllamaConfig { @Bean @Primary public OllamaChatModel defaultChatModel(OllamaApi ollamaApi) { return new OllamaChatModel(ollamaApi, OllamaChatOptions.builder() .model("llama3.2:3b") .temperature(0.7) .build()); } @Bean public OllamaChatModel creativeChatModel(OllamaApi ollamaApi) { return new OllamaChatModel(ollamaApi, OllamaChatOptions.builder() .model("qwen2.5:7b") .temperature(0.9) // 更高的温度用于创意任务 .build()); } }运行时动态覆盖：这是更常见的模式。在每次调用时，通过Prompt传递特定的OllamaChatOptions来临时改变模型或参数。
// 使用默认配置的模型进行一般对话 ChatResponse response1 = chatModel.call(new Prompt("你好！")); // 针对需要严谨回答的问题，临时切换到更合适的模型并降低温度 OllamaChatOptions preciseOptions = OllamaChatOptions.builder() .model("deepseek-r1:7b") // 切换模型 .temperature(0.2) // 降低随机性 .enableThinking() // 启用思考模式 .build(); Prompt precisePrompt = new Prompt("计算15的平方根是多少？", preciseOptions); ChatResponse response2 = chatModel.call(precisePrompt);这种设计模式非常强大，它允许你根据用户查询的意图、复杂度或领域，动态选择最合适的模型和参数，在效果和成本之间取得平衡。
5. 核心API使用与代码实战
5.1 基础聊天与流式响应
Spring AI提供了同步和异步两种调用方式。同步调用call()会阻塞直到收到完整响应，适合简单的问答。流式响应stream()则返回一个Flux<ChatResponse>，可以实时获取模型生成的每一个token，适合需要逐步显示结果的场景，如聊天界面。
同步调用示例：
@RestController @RequestMapping("/api/chat") public class ChatController { private final ChatModel chatModel; // 由Spring自动注入OllamaChatModel @PostMapping("/simple") public String simpleChat(@RequestParam String message) { // 最简单的调用：直接传入用户消息字符串 // Spring AI会将其包装为UserMessage并创建默认的Prompt String responseText = chatModel.call(message); return responseText; } @PostMapping("/advanced") public ChatResponse advancedChat(@RequestBody ChatRequest request) { // 构建完整的Prompt，包含系统指令和对话历史 SystemMessage systemMsg = new SystemMessage("你是一个专业的Java开发助手。"); UserMessage userMsg = new UserMessage(request.getMessage()); // 如果有历史消息，可以构建一个消息列表 List<Message> messages = new ArrayList<>(); messages.add(systemMsg); messages.add(userMsg); Prompt prompt = new Prompt(messages); ChatResponse response = chatModel.call(prompt); // ChatResponse包含更丰富的信息：输出内容、元数据、使用情况等 return response; } }流式响应示例：
@GetMapping(value = "/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE) public Flux<String> streamChat(@RequestParam String query) { Prompt prompt = new Prompt(new UserMessage(query)); return chatModel.stream(prompt) .map(ChatResponse::getResults) // 获取结果列表 .flatMap(List::stream) // 展开结果流 .map(Generation::getOutput) // 获取每个Generation的输出 .map(AssistantMessage::getContent) // 获取内容文本 .doOnNext(content -> { // 可以在这里处理每个token，如发送SSE事件 System.out.print(content); // 模拟实时输出 }); }流式响应需要客户端支持Server-Sent Events (SSE)或WebSocket。在浏览器中，可以使用EventSourceAPI来接收这些数据块并实时更新UI。
5.2 工具调用与函数执行
工具调用是让大模型与现实世界交互的关键。Spring AI通过ToolCallingAdvisor和ChatClient提供了优雅的抽象。基本思路是：你定义一些工具函数（比如查询天气、搜索数据库、调用外部API），将这些工具注册给模型，模型在理解用户意图后，会决定是否需要调用工具，并以结构化格式请求调用，你执行工具后把结果返回给模型，模型再生成最终回答。
定义工具函数：首先，创建一个工具类，其中的方法就是模型可以调用的工具。
@Component public class WeatherService { @ToolFunction(name = "getCurrentWeather", description = "根据城市名称获取当前天气") public String getCurrentWeather( @ToolParameter(description = "城市名称，例如：北京、上海") String city) { // 这里模拟调用天气API Map<String, String> weatherData = Map.of( "北京", "晴，25°C", "上海", "多云，23°C", "广州", "阵雨，28°C" ); return weatherData.getOrDefault(city, "未找到该城市天气信息"); } @ToolFunction(name = "searchKnowledgeBase", description = "在内部知识库中搜索相关信息") public String searchKnowledgeBase( @ToolParameter(description = "搜索关键词") String keyword) { // 模拟搜索逻辑 return "找到关于\"" + keyword + "\"的3条相关记录：..."; } }配置与使用工具调用：在Spring配置中，将工具服务注册为ToolCallback，然后通过ChatClient使用。
@Configuration public class ToolConfig { @Bean public ToolCallingAdvisor toolCallingAdvisor(WeatherService weatherService) { // 将工具服务转换为ToolCallback ToolCallback weatherCallback = FunctionToolCallback.builder() .name("getCurrentWeather") .description("获取指定城市的当前天气") .inputType(String.class) // 工具参数类型 .function(weatherService::getCurrentWeather) .build(); return new ToolCallingAdvisor(List.of(weatherCallback)); } @Bean public ChatClient chatClient(ChatModel chatModel, ToolCallingAdvisor advisor) { return ChatClient.builder(chatModel) .defaultAdvisors(advisor) // 注册工具调用顾问 .build(); } }在控制器中使用：
@RestController public class ToolChatController { private final ChatClient chatClient; @PostMapping("/chat-with-tools") public String chatWithTools(@RequestParam String question) { // ChatClient会自动处理工具调用循环 String response = chatClient.prompt() .user(question) .call() .content(); return response; } }当用户询问“北京和上海的天气怎么样？”时，模型会先识别出需要调用getCurrentWeather工具，并分别请求北京和上海的天气。ChatClient会拦截这个工具调用请求，执行实际的WeatherService.getCurrentWeather()方法，将结果返回给模型，模型再综合这些信息生成最终回答：“北京晴，25°C；上海多云，23°C。”整个过程对开发者基本透明，大大简化了工具集成的复杂度。
5.3 多模态处理与图像理解
Ollama支持多模态模型（如LLaVA），可以处理图像输入。Spring AI通过Media类支持多模态消息。
处理图像输入的示例：
@PostMapping(value = "/analyze-image", consumes = MediaType.MULTIPART_FORM_DATA_VALUE) public String analyzeImage(@RequestParam("file") MultipartFile imageFile, @RequestParam("question") String question) throws IOException { // 将上传的图像文件转换为Spring AI的Media对象 Media imageMedia = new Media( MediaType.parseMediaType(imageFile.getContentType()), new ByteArrayResource(imageFile.getBytes()) ); // 构建包含图像和文本的多模态用户消息 UserMessage userMessage = new UserMessage(question, List.of(imageMedia)); Prompt prompt = new Prompt(userMessage); // 重要：必须使用支持多模态的模型，如llava OllamaChatOptions options = OllamaChatOptions.builder() .model("llava:7b") // 指定多模态模型 .build(); prompt = new Prompt(userMessage, options); ChatResponse response = chatModel.call(prompt); return response.getResult().getOutput().getText(); }在这个例子中，用户可以上传一张图片并提问“图片里有什么？”或“描述一下这张图的内容”。模型会同时分析图像和文本，生成结合视觉信息的回答。这对于构建图像描述、视觉问答、文档分析等应用非常有用。
实操心得：多模态模型通常比纯文本模型更大，推理速度更慢，且更耗资源。在实际应用中，可以考虑异步处理图像分析请求，或者提供进度提示。另外，图像需要转换为base64编码或合适的资源格式传递给Ollama，Spring AI的
Media类帮我们处理了这些细节。
6. 生产环境部署与优化策略
6.1 性能调优与参数配置
将Spring AI + Ollama应用到生产环境，性能是关键。以下是一些经过验证的优化策略。
Ollama服务端优化：
- GPU加速：如果服务器有NVIDIA GPU，确保Ollama使用了CUDA。安装时选择带GPU支持的版本，运行时Ollama会自动检测并使用GPU。可以通过环境变量
OLLAMA_NUM_GPU=1强制指定，或在模型配置中设置num_gpu参数。 - 模型量化与选择：生产环境优先考虑量化模型（如
llama3.2:7b-q4_K_M）。这些模型在精度损失极小的情况下，大幅减少了内存占用和计算需求。使用ollama pull llama3.2:7b-q4_K_M拉取量化版本。 - 上下文长度与批处理：根据实际需要调整
num_ctx。不是越大越好，2048对于大多数对话场景足够，4096或8192适合长文档分析，但会显著增加内存使用和推理时间。num_batch控制批处理大小，增加它可以提高GPU利用率，但也会增加显存压力，需要根据硬件调整。 - 保持模型常驻：通过设置
keep_alive参数（如keep_alive: 30m），让模型在请求后一段时间内保持在内存中，避免频繁加载卸载的开销。对于高并发场景，可以设置为较大的值或-1（永久保持）。
Spring AI应用层优化：
- 连接池与超时：Spring AI的Ollama客户端基于WebClient，可以配置连接池和超时设置。在
application.yml中：
spring: ai: ollama: base-url: http://localhost:11434 # 客户端配置 client: connect-timeout: 10s response-timeout: 60s # 长文本生成需要更长时间 read-timeout: 60s- 异步与非阻塞：对于耗时较长的生成任务，使用Spring WebFlux实现异步非阻塞响应，避免阻塞Tomcat线程池。结合流式响应，可以边生成边返回，提升用户体验。
- 缓存策略：对于常见问题或模板化回答，可以在应用层实现缓存。使用Spring Cache抽象，将
Prompt的哈希值作为key，缓存ChatResponse。
6.2 监控、日志与健康检查
生产系统需要可观测性。Spring Boot Actuator提供了现成的监控端点，可以轻松集成。
添加Actuator依赖：
<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-actuator</artifactId> </dependency>配置健康检查：Spring AI Ollama starter会自动注册一个健康指示器，检查Ollama服务是否可达。
management: endpoints: web: exposure: include: health,info,metrics endpoint: health: show-details: when_authorized访问/actuator/health可以看到Ollama连接状态。你还可以自定义健康检查，比如测试模型是否正常响应。
日志与追踪：为了调试和审计，需要记录详细的AI调用日志。可以配置一个ClientLogger拦截器：
@Component public class OllamaRequestLogger implements ClientLogger { private static final Logger log = LoggerFactory.getLogger(OllamaRequestLogger.class); @Override public void log(String requestId, String request, String response) { // 注意：生产环境不要记录完整的请求响应，可能包含敏感数据 log.info("Ollama Request ID: {}, Model: {}", requestId, extractModel(request)); log.debug("Full request: {}", request); log.debug("Full response: {}", response); // 可以记录指标：请求耗时、token使用量等 Metrics.counter("ai.requests.total").increment(); } private String extractModel(String requestJson) { try { JsonNode root = new ObjectMapper().readTree(requestJson); return root.path("model").asText("unknown"); } catch (Exception e) { return "parse_error"; } } }指标收集：使用Micrometer集成Prometheus或OpenTelemetry，收集关键指标：
- 请求速率（QPS）
- 平均响应时间、P95/P99延迟
- Token消耗速率（输入/输出）
- 错误率（4xx/5xx响应）
- 模型加载/卸载次数
这些指标能帮助你了解系统负载，做出扩容或优化决策。
6.3 安全与权限控制
虽然Ollama在本地部署，但安全仍然重要，特别是当服务暴露给内部网络或多用户时。
API认证与授权：为你的Spring Boot应用添加安全层。使用Spring Security保护AI端点：
@Configuration @EnableWebSecurity public class SecurityConfig { @Bean public SecurityFilterChain filterChain(HttpSecurity http) throws Exception { http .authorizeHttpRequests(authz -> authz .requestMatchers("/api/chat/**").authenticated() .requestMatchers("/api/admin/**").hasRole("ADMIN") .anyRequest().permitAll() ) .oauth2ResourceServer(OAuth2ResourceServerConfigurer::jwt) // 使用JWT .csrf(csrf -> csrf.ignoringRequestMatchers("/api/chat/stream")); // 流式端点可能需要特殊处理 return http.build(); } }输入验证与防护：对用户输入进行清理和验证，防止Prompt注入攻击。
@Service public class PromptSanitizer { private static final Set<String> BLACKLISTED_PHRASES = Set.of( "ignore previous instructions", "system prompt", "扮演", "模拟" // 根据业务需要添加更多 ); public String sanitize(String userInput) { if (userInput == null || userInput.trim().isEmpty()) { throw new IllegalArgumentException("输入不能为空"); } // 检查黑名单短语 String lowerInput = userInput.toLowerCase(); for (String phrase : BLACKLISTED_PHRASES) { if (lowerInput.contains(phrase.toLowerCase())) { throw new SecurityException("输入包含不允许的指令"); } } // 限制长度 if (userInput.length() > 4000) { userInput = userInput.substring(0, 4000) + "...[已截断]"; } // 移除控制字符（可选） userInput = userInput.replaceAll("[\\p{Cntrl}&&[^\r\n\t]]", ""); return userInput; } }速率限制：防止滥用，为API添加速率限制。可以使用Spring的@RateLimit注解或集成Resilience4j：
@RestController public class RateLimitedChatController { private final RateLimiter rateLimiter; public RateLimitedChatController() { // 每个用户每分钟最多10次请求 this.rateLimiter = RateLimiter.of("chat-api", RateLimiterConfig.custom() .limitForPeriod(10) .limitRefreshPeriod(Duration.ofMinutes(1)) .build()); } @PostMapping("/api/chat") public ResponseEntity<String> chat(@RequestParam String message, @RequestHeader("X-User-ID") String userId) { // 基于用户ID的速率限制 if (!rateLimiter.acquirePermission(userId)) { return ResponseEntity.status(429) .header("Retry-After", "60") .body("请求过于频繁，请稍后再试"); } // 正常处理逻辑 String response = chatModel.call(message); return ResponseEntity.ok(response); } }模型隔离：在多租户场景，可以为不同用户或组织分配不同的Ollama实例或使用不同的模型，实现资源隔离。可以通过在请求头中指定模型，动态创建OllamaChatModel实例。
7. 常见问题排查与调试技巧
7.1 连接与启动问题
问题1：应用启动时报错“Connection refused”或“Connect timed out”这通常表示Spring Boot应用无法连接到Ollama服务。首先检查Ollama是否正在运行：在终端执行ollama serve或ollama run llama3.2，看服务能否正常启动。然后验证端口：Ollama默认使用11434端口，确保没有被防火墙或其它进程占用。最后检查Spring配置：确认application.yml中的spring.ai.ollama.base-url正确指向了Ollama服务地址。如果是Docker部署，注意容器网络配置，可能需要使用host网络或正确配置端口映射。
问题2：模型加载失败，提示“model not found”这表示Ollama实例中没有你配置的模型。首先用ollama list确认模型是否存在。如果不存在，使用ollama pull <model-name>拉取。注意模型名称大小写敏感，必须完全匹配。如果是在集群或容器环境，确保每个节点都有模型文件。对于生产环境，建议将模型文件放在共享存储或使用初始化脚本预先拉取。
问题3：应用启动时卡在“Pulling model...”很久这是配置了spring.ai.ollama.init.pull-model-strategy: always或when_missing，且模型需要下载。大型模型（如7B、13B）下载可能需要数十分钟，取决于网络。对于生产环境，建议设置为never，并通过运维流程确保模型已预先存在。开发环境可以设置为when_missing，但第一次启动要有耐心。可以查看Ollama服务的日志（ollama serve的输出）了解下载进度。
7.2 运行时性能与稳定性问题
问题4：响应速度慢，特别是首次请求首次请求慢是因为Ollama需要从磁盘加载模型到内存（或GPU显存）。可以通过设置keep_alive参数让模型常驻内存。在application.yml中配置spring.ai.ollama.chat.options.keep-alive: 30m，这样模型在最后一次请求后30分钟内会保持在内存中。对于需要快速响应的生产服务，可以设置为-1（永久保持），但要注意内存占用。
问题5：生成内容重复或质量差这通常与模型参数配置有关。调整以下参数可以改善：
- 降低
temperature（如从0.8降到0.3）减少随机性 - 增加
repeat-penalty（如从1.1升到1.5）加强重复惩罚 - 调整
top-p和top-k：top-p: 0.9配合top-k: 40是平衡点，想要更确定性的输出可以降低top-p到0.5 - 确保
num-predict设置合理，太短可能截断回答，太长可能产生无关内容
问题6：内存不足或OOM错误Ollama模型运行需要足够内存。3B模型约需要3-4GB，7B模型需要7-8GB，13B模型需要13GB以上。如果使用GPU，部分层会加载到显存。解决方案：
- 使用量化版本模型（如
-q4_K_M后缀） - 增加系统交换空间（swap）
- 调整Ollama参数：减少
num_ctx（上下文长度），减少num_batch（批处理大小） - 升级硬件或使用更小模型
7.3 高级功能与集成问题
问题7：工具调用不工作，模型不识别工具首先确认Ollama版本至少是0.2.8（工具调用功能的最低要求）。使用ollama --version检查。然后检查工具函数定义：确保@ToolFunction注解正确，参数有@ToolParameter描述。在代码中，确保ToolCallingAdvisor正确配置并注册到了ChatClient。可以通过开启DEBUG日志查看工具注册和调用过程：logging.level.org.springframework.ai=DEBUG。
问题8：结构化输出不符合预期结构化输出依赖模型的JSON生成能力。首先确保使用的是较新、能力强的模型（如llama3.2、qwen2.5）。其次，JSON Schema要尽可能简单明确，复杂的嵌套结构可能让模型困惑。可以先从简单结构开始测试。另外，可以在Prompt中明确指示输出格式，例如：“请严格按照以下JSON格式回答：{"answer": "你的回答"}”。如果问题依旧，尝试调整temperature到更低值（如0.1），让输出更确定。
问题9：流式响应在客户端接收不完整这通常是客户端处理问题。确保客户端正确处理Server-Sent Events（SSE）：
- 检查响应头：
Content-Type: text/event-stream - 检查连接保持：SSE连接是长连接，不能设置超时太短
- 客户端实现：使用标准的
EventSourceAPI，正确处理onmessage、onerror事件 - 网络代理：某些代理或负载均衡器可能不支持SSE，需要特殊配置
在服务端，确保没有过滤器或拦截器修改了响应。Spring Security默认会缓存响应，需要为流式端点禁用：
@Configuration @EnableWebSecurity public class SecurityConfig extends WebSecurityConfigurerAdapter { @Override protected void configure(HttpSecurity http) throws Exception { http .headers() .cacheControl().disable() // 禁用缓存 .and() // ... 其他配置 } }7.4 监控与日志调试技巧
启用详细日志：在application.yml中添加：
logging: level: org.springframework.ai: DEBUG org.springframework.web: DEBUG org.apache.http: DEBUG这会打印HTTP请求/响应详情，包括发送给Ollama的完整Prompt和收到的原始响应，对于调试复杂问题非常有用。
使用Ollama API直接测试：当问题难以定位时，绕过Spring AI，直接用curl测试Ollama API：
curl http://localhost:11434/api/generate -d '{ "model": "llama3.2:3b", "prompt": "你好", "stream": false }'这能快速判断是Ollama问题还是Spring AI集成问题。
性能分析工具：使用JVM工具（如VisualVM、JConsole）监控应用内存和CPU使用。使用nvidia-smi（如有GPU）监控显存使用。对于Ollama本身，可以查看其日志：在Linux上，Ollama日志通常在~/.ollama/logs/；在Windows上，在%USERPROFILE%\.ollama\logs\。
编写集成测试：为关键功能编写自动化集成测试，确保升级或配置变更后核心功能正常：
@SpringBootTest class OllamaIntegrationTest { @Autowired private OllamaChatModel chatModel; @Test void testBasicChat() { String response = chatModel.call("你好，请简单介绍一下你自己"); assertNotNull(response); assertTrue(response.length() > 10); } @Test void testStreaming() { Prompt prompt = new Prompt("写一首关于春天的短诗"); Flux<ChatResponse> stream = chatModel.stream(prompt); List<String> chunks = stream .map(resp -> resp.getResult().getOutput().getContent()) .collectList() .block(); assertNotNull(chunks); assertFalse(chunks.isEmpty()); } }定期运行这些测试，可以在问题影响用户前及时发现。
