Spring AI 调用VLLM模型时的HTTP协议兼容性问题解析

问题背景

在使用Spring AI框架调用VLLM模型服务时，开发者遇到了一个典型的HTTP协议兼容性问题。当通过Spring AI的OpenAiChatModel组件与VLLM服务交互时，系统返回400 Bad Request错误，而直接使用API POST调用相同接口却能正常工作。

问题现象分析

从日志中可以观察到以下关键信息：

1. 请求通过Spring WebFlux的WebClient发送到VLLM服务端点
2. 服务端返回了400错误状态码
3. 相同的请求参数通过直接API调用却能成功执行

这种差异表明问题并非出在请求内容本身，而是与传输协议或客户端配置相关。

根本原因

经过深入分析，发现问题根源在于HTTP协议版本的兼容性。Spring AI默认使用的HTTP客户端可能尝试使用HTTP/2协议与VLLM服务通信，而VLLM的OpenAI兼容API端点对HTTP/2支持不完善，导致协议协商失败。

解决方案

针对这一问题，可以通过强制客户端使用HTTP/1.1协议来解决。具体实现方案如下：

配置HTTP客户端

import java.net.http.HttpClient;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Primary;
import org.springframework.http.client.JdkClientHttpRequestFactory;
import org.springframework.http.client.reactive.JdkClientHttpConnector;
import org.springframework.web.client.RestClient;
import org.springframework.web.reactive.function.client.WebClient;

@Configuration
public class HttpClientConfiguration {
  private HttpClient client() {
    return HttpClient.newBuilder()
        .version(HttpClient.Version.HTTP_1_1)  // 强制使用HTTP/1.1协议
        .build();
  }

  @Bean
  @Primary
  public RestClient.Builder restClientBuilder() {
    return RestClient.builder()
        .requestFactory(new JdkClientHttpRequestFactory(client()));
  }

  @Bean
  @Primary
  public WebClient.Builder webClientBuilder() {
    return WebClient.builder()
        .clientConnector(new JdkClientHttpConnector(client()));
  }
}

方案说明

1. HTTP协议版本控制：通过HttpClient.Builder明确指定使用HTTP/1.1协议
2. 客户端覆盖：配置覆盖了Spring默认的RestClient和WebClient构建器
3. 主配置标记：使用@Primary注解确保这些配置优先被采用

技术原理

HTTP/2和HTTP/1.1在协议实现上有显著差异：

• HTTP/2采用二进制分帧层，支持多路复用
• HTTP/1.1基于文本，每个请求需要独立连接
• 某些服务端实现可能对HTTP/2支持不完整

VLLM的OpenAI兼容API端点可能基于较简单的HTTP服务器实现，对HTTP/2协议支持有限，强制降级到HTTP/1.1可以确保兼容性。

最佳实践建议

1. 协议兼容性测试：在集成新服务时，应测试不同HTTP协议版本
2. 客户端配置灵活性：保持客户端协议版本可配置
3. 错误监控：对400类错误应增加详细日志记录
4. 服务端验证：确认服务端支持的协议版本

总结

Spring AI与VLLM集成时的协议兼容性问题是一个典型的中间件交互问题。通过理解HTTP协议版本差异和适当配置客户端，可以有效解决这类问题。这一解决方案不仅适用于当前场景，也为处理类似的技术集成问题提供了参考模式。