一、問題現(xiàn)象

在 Spring Boot 3.2.5 項目中使用 spring-ai-ollama-spring-boot-starter（版本 1.0.0-M6）連接本地 Ollama 部署的 qwen2.5:7b-instruct 模型時，調(diào)用聊天接口（例如 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 中已經(jīng)配置了 spring.ai.ollama.chat.options.timeout: 120s，超時仍然準(zhǔn)時在 10 秒左右發(fā)生，導(dǎo)致模型生成未完成就被中斷。

二、問題場景

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

三、根因分析

1. 兩層超時機(jī)制相互獨立

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

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

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

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

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

SimpleClientHttpRequestFactory 無效
實際堆棧中顯示底層為 okhttp3.OkHttpClient，而非 JDK 默認(rèn)的 HttpURLConnection（對應(yīng) SimpleClientHttpRequestFactory）。配置后者當(dāng)然不起作用。

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

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

4. 自定義 Bean 時的常見坑

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

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

而不是 (String, RestClient)。錯誤地調(diào)用構(gòu)造函數(shù)會導(dǎo)致編譯失敗。

四、最終解決方案

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

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

步驟：

1. 在項目中新增配置類 OllamaTimeoutConfig.java。
2. 使用 @Value 注入 spring.ai.ollama.base-url。
3. 構(gòu)建自定義超時的 OkHttpClient。
4. 創(chuàng)建 RestClient.Builder 并設(shè)置 OkHttp3ClientHttpRequestFactory（雖然已過時，但功能正常，可忽略警告）。
5. 提供空 WebClient.Builder 實例。
6. 調(diào)用正確的 OllamaApi 三參數(shù)構(gòu)造器并返回 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. 構(gòu)建 RestClient.Builder，注入自定義 factory
        RestClient.Builder restClientBuilder = RestClient.builder()
                .baseUrl(baseUrl)
                .requestFactory(factory);

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

        // 5. 調(diào)用 OllamaApi 實際構(gòu)造函數(shù)
        return new OllamaApi(baseUrl, restClientBuilder, webClientBuilder);
    }
}

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

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          # 服務(wù)端模型生成超時，依然建議保留
      embedding:
        options:
          model: nomic-embed-text
          timeout: 120s
  servlet:
    multipart:
      max-file-size: 10MB
      max-request-size: 10MB

關(guān)鍵要點

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

五、驗證效果

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

六、總結(jié)

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

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

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

最新評論