在使用 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 # 若用代理，替换为代理地址