一、問題現象

在 Spring Boot 3.2.5 項目中使用 spring-ai-ollama-spring-boot-starter（版本 1.0.0-M6）連接本地 Ollama 部署的 qwen2.5:7b-instruct 模型時，調用聊天接口（例如 RAG 問答）會在約 10 秒后拋出以下異常：

org.springframework.web.client.ResourceAccessException: I/O error on POST request for "http://localhost:11434/api/chat": timeout
    at org.springframework.web.client.DefaultRestClient...
Caused by: java.net.SocketTimeoutException: timeout
    at okio.SocketAsyncTimeout.newTimeoutException(JvmOkio.kt:146)
    at okhttp3.internal.http1.Http1ExchangeCodec.readResponseHeaders(...)

盡管在 application.yml 中已經配置了 spring.ai.ollama.chat.options.timeout: 120s，超時仍然準時在 10 秒左右發(fā)生，導致模型生成未完成就被中斷。

二、問題場景

• 本地 Ollama 模型響應慢：使用 7B 或更大參數量的模型（如 qwen2.5:7b-instruct），或者提問復雜度較高時，Ollama 服務端需要較長時間（可能十幾秒甚至幾十秒）才能返回第一個 token 或完整響應。
• 只配置了服務端超時，未配置客戶端 HTTP 超時：開發(fā)者往往認為 spring.ai.ollama.chat.options.timeout 就足夠控制整個請求的超時，但實際它只控制發(fā)送給 Ollama API 的 timeout 參數（告訴服務端最多生成多久），并不影響 Java 客戶端等待響應的時長。
• 底層 HTTP 客戶端為 OkHttp：Spring AI Ollama 在無自定義配置時，默認通過 OkHttp3ClientHttpRequestFactory 使用 OkHttp 發(fā)起請求。OkHttp 的默認讀超時為 10 秒，這就是超時發(fā)生在 10 秒的根本原因。

三、根因分析

1. 兩層超時機制相互獨立

模型層超時（chat.options.timeout）
該值會被序列化到 POST /api/chat 請求體中的 options.timeout 字段，用于告知 Ollama 服務端允許的最長生成時間。服務端如果超時，會主動中斷生成并返回錯誤。

HTTP 客戶端層超時（OkHttp 讀超時）
這是 Java 應用等待服務器返回響應的最大時間。如果服務端處理慢（比如模型生成耗時較長），客戶端會在達到讀超時后直接拋出 SocketTimeoutException，無論服務端是否仍在正常工作。
OkHttp 默認 readTimeout = 10_000ms（10 秒）。

只有 HTTP 讀超時 > 模型生成所需時間時，請求才能正常完成。 反之，即使服務端允許生成更久，客戶端也會先斷開連接。

2. 常見配置為何不生效？

spring.restclient.read-timeout 無效
spring.restclient 屬性通過 RestClientCustomizer 全局修改 RestClient.Builder，但 Spring AI Ollama 自動配置內部是獨立創(chuàng)建 RestClient 的，并未應用全局定制器，因此該配置無法傳遞到 Ollama 所用客戶端。

SimpleClientHttpRequestFactory 無效
實際堆棧中顯示底層為 okhttp3.OkHttpClient，而非 JDK 默認的 HttpURLConnection（對應 SimpleClientHttpRequestFactory）。配置后者當然不起作用。

spring.okhttp.read-timeout 無效（或直接啟動報錯）
Spring Boot 對 OkHttp 的屬性前綴是 spring.okhttp，而非 okhttp。即使寫成正確前綴，Ollama 自動配置也可能沒有使用 Spring 管理的 OkHttpClient Bean，而是直接創(chuàng)建了一個默認 OkHttpClient，因此全局配置同樣不生效。

此外，若在 YAML 中不慎寫出兩個頂級 spring: 鍵，會觸發(fā) DuplicateKeyException 導致啟動失敗。

4. 自定義 Bean 時的常見坑

直接創(chuàng)建 OllamaApi Bean 時，需注意其構造函數簽名在 1.0.0-M6 版本中為：

public OllamaApi(String baseUrl, 
                 RestClient.Builder restClientBuilder, 
                 WebClient.Builder webClientBuilder)

而不是 (String, RestClient)。錯誤地調用構造函數會導致編譯失敗。

四、最終解決方案

自定義OllamaApiBean，顯式控制 OkHttp 超時

直接通過配置類覆蓋 OllamaApi Bean，創(chuàng)建一個具有足夠長讀超時的 OkHttpClient，并將其通過 RestClient.Builder 注入到 OllamaApi 中。此方案完全繞過 Spring 的全局 OkHttp 配置，從根源上解決問題。

步驟：

1. 在項目中新增配置類 OllamaTimeoutConfig.java。
2. 使用 @Value 注入 spring.ai.ollama.base-url。
3. 構建自定義超時的 OkHttpClient。
4. 創(chuàng)建 RestClient.Builder 并設置 OkHttp3ClientHttpRequestFactory（雖然已過時，但功能正常，可忽略警告）。
5. 提供空 WebClient.Builder 實例。
6. 調用正確的 OllamaApi 三參數構造器并返回 Bean。

完整代碼：

package com.badao.ai.config;

import okhttp3.OkHttpClient;
import org.springframework.ai.ollama.api.OllamaApi;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.client.OkHttp3ClientHttpRequestFactory;
import org.springframework.web.client.RestClient;
import org.springframework.web.reactive.function.client.WebClient;

import java.time.Duration;

@Configuration
public class OllamaTimeoutConfig {

    @Value("${spring.ai.ollama.base-url}")
    private String baseUrl;

    @Bean
    public OllamaApi ollamaApi() {
        // 1. 自定義 OkHttpClient 超時
        OkHttpClient okHttpClient = new OkHttpClient.Builder()
                .connectTimeout(Duration.ofSeconds(30))       // 連接超時
                .readTimeout(Duration.ofMinutes(3))           // 讀超時 3 分鐘，大于模型 timeout
                .writeTimeout(Duration.ofSeconds(60))         // 寫超時
                .build();

        // 2. 創(chuàng)建 OkHttp3ClientHttpRequestFactory（已過時但可用）
        OkHttp3ClientHttpRequestFactory factory =
                new OkHttp3ClientHttpRequestFactory(okHttpClient);

        // 3. 構建 RestClient.Builder，注入自定義 factory
        RestClient.Builder restClientBuilder = RestClient.builder()
                .baseUrl(baseUrl)
                .requestFactory(factory);

        // 4. 提供 WebClient.Builder（必須，傳默認空 builder 即可）
        WebClient.Builder webClientBuilder = WebClient.builder();

        // 5. 調用 OllamaApi 實際構造函數
        return new OllamaApi(baseUrl, restClientBuilder, webClientBuilder);
    }
}

YAML 配置精簡：
既然已經通過代碼完全掌控了 HTTP 客戶端超時，就可以移除 application.yml 中的 spring.restclient、spring.okhttp 等無關超時配置，保持清晰：

server:
  port: 885
logging:
  level:
    com.badao: debug
    org.springframework.ai: debug
spring:
  ai:
    ollama:
      base-url: http://localhost:11434
      chat:
        options:
          model: qwen2.5:7b-instruct
          temperature: 0.5
          timeout: 120s          # 服務端模型生成超時，依然建議保留
      embedding:
        options:
          model: nomic-embed-text
          timeout: 120s
  servlet:
    multipart:
      max-file-size: 10MB
      max-request-size: 10MB

關鍵要點

• 讀超時必須大于模型超時：這里 readTimeout = 3 分鐘，而 chat.options.timeout = 2 分鐘，留有充足緩沖。
• OkHttp3ClientHttpRequestFactory 過時警告：不影響功能，可忽略。如需消除，需整體切換到其他 HTTP 客戶端（如 JDK HttpClient），但會增加配置復雜度，不值得。
• 不要添加額外的 YAML OkHttp 配置，避免干擾。

五、驗證效果

1. 重新編譯并啟動應用。
2. 發(fā)送之前會導致超時的 RAG 請求。
3. 觀察日志，不再出現 Read timed out 或 SocketTimeoutException。
4. 模型正常返回生成結果，即使耗時超過 10 秒、甚至 1 分鐘，也能順利完成。

六、總結

本次問題的本質是 Spring AI Ollama 使用的底層 OkHttp 讀超時默認過短，且 YAML 配置中的服務端超時選項無法控制客戶端行為，加上 Spring Boot 全局 OkHttp 屬性與 Ollama 自動配置并不互通，導致常規(guī)配置嘗試全部失效。

最終通過自定義 OllamaApi Bean 直接構建帶超時的 OkHttpClient，并依其正確的構造函數注入，徹底解決了超時問題。該方案穩(wěn)定可靠，推薦遇到同類問題的開發(fā)者采用。

以上就是Spring AI Ollama連接本地模型超時問題完全解決指南的詳細內容，更多關于Spring AI Ollama連接超時問題的資料請關注腳本之家其它相關文章！

最新評論