SpringAI 实战：解除 Netty 超时难题，优化 OpenAiApi 配置

在使用 SpringAI 对接 OpenAI 等大模型接口时，很多开发者会遇到一个常见问题：接口调用过程中突然抛出 Netty 超时异常。这一问题往往与默认配置的超时时间不匹配实际业务场景有关，今天就带大家从问题分析到解决方案，完整搞定 SpringAI 的超时配置优化。

一、问题背景：为什么会出现 Netty 超时？

SpringAI 中默认提供的 OpenAiApi 实例化方式，会使用框架内置的默认超时参数。对于简单的短文本交互（如单轮问答），默认超时可能足够，但如果遇到长文本生成（如万字报告）、复杂逻辑计算（如代码生成 + 解释）或网络波动场景，默认的短超时就会触发 Netty 底层的连接超时 / 读取超时，直接导致接口调用失败。

先看大家常用的默认配置（也是问题配置）：

@Bean
public OpenAiApi openAiApi() {   // 仅传入 apiKey 和 baseUrl，使用全部默认配置   return new OpenAiApi(apiKey, baseUrl);
}

上述配置的隐患在于：SpringAI 默认的 HTTP 客户端（基于 Netty）超时时间较短，而大模型生成复杂内容时，响应时间很容易超过这个阈值，最终抛出 io.netty.handler.timeout.ReadTimeoutException 异常。

二、解决方案：自定义超时配置

核心思路是：通过 RestClient.Builder 手动配置 HTTP 客户端的超时参数（重点是读取超时），再将自定义的 RestClient.Builder 注入到 OpenAiApi 中，覆盖默认配置。

优化后的完整代码如下：

@Bean   public OpenAiApi openAiApi() {       RestClient.Builder customRestClientBuilder = RestClient.builder()               .requestFactory(ClientHttpRequestFactoryBuilder.simple()                       .build(ClientHttpRequestFactorySettings.defaults()                               .withReadTimeout(Duration.ofSeconds(60))));
​       OpenAiApi api = OpenAiApi.builder().apiKey(apiKey).baseUrl(baseUrl)               .restClientBuilder(customRestClientBuilder)               .build();       return api;
​   }

三、关键参数说明与注意事项

1. 核心超时参数解读

• ConnectTimeout（连接超时）：客户端与大模型服务建立 TCP 连接的最大等待时间，建议设置为 10-15 秒。过短容易因网络波动导致连接失败，过长则会增加无效等待时间。

• ReadTimeout（读取超时）：建立连接后，等待服务端返回响应的最大时间，这是解决 Netty 超时的核心。根据业务场景调整：

• 短文本交互（如单轮问答）：30-60 秒足够；

• 长文本生成（如报告、小说）：建议 60-120 秒；

• 超复杂任务（如多轮对话 + 代码生成）：可酌情设为 180 秒，但需注意服务端是否有超时限制（如 OpenAI 部分接口默认 5 分钟超时）。

• WriteTimeout（写入超时）：客户端向服务端发送请求体的最大时间，一般设置为 30 秒即可，极少触发。

2. 避免硬编码，从配置文件读取参数

建议实际项目中api-key和base-url需在 application.yml 或 application.properties 中配置，示例（yml 格式）：

spring:ai:   openai:     api-key: sk-your-api-key     base-url: https://api.openai.com/v1 # 若用代理，替换为代理地址