"SpringAI ChatClient 请求 vLLM /v1/chat/completions 接口返回 400 错误"

Question

**问题描述：** 在使用 Spring AI 的 `ChatClient` 调用 vLLM 提供的 `/v1/chat/completions` 接口时，出现 **HTTP 400 Bad Request** 错误。常见原因包括请求格式不正确、模型参数不兼容、缺少必要字段（如 `model`、`messages`）、或输入内容格式不符合 vLLM 的预期。此外，Spring AI 默认的请求体构造方式可能与 vLLM 所需的结构存在差异，导致解析失败。如何正确配置 `ChatClient` 及其底层 `RestClient`，以确保请求体、请求头与 vLLM 接口规范完全匹配，是解决该问题的关键所在。

Answer 1

一、问题背景与初步分析

在使用 Spring AI 的 ChatClient 调用 vLLM 提供的 /v1/chat/completions 接口时，开发者常会遇到 HTTP 400 Bad Request 错误。这类错误通常意味着请求体或请求头的格式与服务端预期不符。vLLM 是一个高效的推理服务框架，其接口规范要求严格遵循 OpenAI 的 REST API 格式，而 Spring AI 的默认请求构造方式可能并不完全兼容。 初步排查时，应检查以下几点：

• 请求是否包含 model 字段
• messages 是否为符合格式的 JSON 数组
• 请求头中是否包含 Content-Type: application/json
• 是否设置了正确的 Authorization 头（如适用）

二、请求结构对比分析

Spring AI 的 ChatClient 默认使用 OpenAiChatClient 实现，它会构造符合 OpenAI 官方接口的请求体。而 vLLM 虽然兼容 OpenAI API，但在某些字段支持上可能略有差异，如对 temperature、max_tokens 等参数的处理方式不同。 以下是两个请求结构的对比：

字段	Spring AI 默认结构	vLLM 支持结构
model	required	required
messages	array of role/content	array of role/content
temperature	float	float
max_tokens	int	int
stream	boolean	boolean

从上表可以看出，虽然大多数字段是兼容的，但具体实现细节（如字段命名、默认值、类型转换）可能导致不一致。

三、深入排查与日志分析

为了更准确地定位问题，建议开启 Spring AI 的调试日志输出，尤其是底层 RestClient 的请求和响应信息。可以通过如下方式配置日志：

logging.level.org.springframework.ai.chat.client=DEBUG

通过日志可以观察到：

• 实际发送的请求体内容
• 请求头中的 Content-Type 和 Authorization 字段
• 服务器返回的具体错误信息（如缺失字段、非法参数等）

常见错误示例包括：

{"error": {"message": "Missing required field: messages", "type": "invalid_request_error"}}

这说明 messages 字段未正确构造或未被序列化。

四、解决方案与配置调整

为了解决该问题，需对 ChatClient 的底层 RestClient 进行自定义配置，确保其生成的请求完全符合 vLLM 的接口规范。 以下是一个完整的配置示例：

@Bean
public ChatClient chatClient(RestClient restClient) {
    return new OpenAiChatClient(restClient);
}

@Bean
public RestClient restClient() {
    return RestClient.builder()
        .baseUrl("http://localhost:8000/v1")
        .defaultHeader(HttpHeaders.CONTENT_TYPE, MediaType.APPLICATION_JSON_VALUE)
        .build();
}

此外，还需确保在调用时传入的参数结构与 vLLM 兼容：

var prompt = new Prompt("Hello, how are you?");
var response = chatClient.call(prompt);

如果仍然报错，建议手动构造请求体并使用 RestClient 直接调用接口进行测试：

var requestBody = Map.of(
    "model", "llama3",
    "messages", List.of(Map.of("role", "user", "content", "Hello, how are you?")),
    "temperature", 0.7,
    "max_tokens", 100
);

var response = restClient.post()
    .uri("/chat/completions")
    .body(requestBody)
    .retrieve()
    .body(String.class);

五、扩展建议与最佳实践

为了提升系统的兼容性和可维护性，建议采用以下做法：

• 使用 ObjectMapper 自定义序列化策略，确保 JSON 结构与 vLLM 一致
• 封装一个适配层，将 Spring AI 的请求参数转换为 vLLM 所需格式
• 使用 InterceptingClientHttpRequestFactory 拦截请求，进行日志记录或格式调整
• 在开发环境中使用 Postman 或 curl 手动模拟请求，验证接口是否正常工作

以下是一个简单的适配器流程图： graph TD A[Spring AI ChatClient] --> B(Adapter Layer) B --> C[RestClient] C --> D[vLLM /v1/chat/completions] D --> C C --> B B --> A