Spring AI 1.0.0-SNAPSHOT集成OpenAI报response_format.schema未知参数错误

问题根源 #

Spring AI 1.0.0-SNAPSHOT属于开发快照版本，其OpenAI集成模块可能未适配OpenAI最新的结构化输出API参数规范，导致请求时抛出Unknown parameter: 'response_format.schema'错误。

修复方案 #

1. 升级Spring AI版本 #

快照版本存在API适配滞后的概率较高，建议切换至稳定正式版（如1.0.0正式版，若已发布）或更新至最新快照版本，确保OpenAI客户端已兼容新参数格式。

修改pom.xml中的依赖版本：

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-openai</artifactId>
    <version>1.0.0</version> <!-- 替换为最新稳定版或更新的SNAPSHOT -->
</dependency>

2. 使用Spring AI封装的结构化输出API #

避免手动指定response_format.schema，改用框架提供的封装类生成合规请求参数：

调整后的Controller示例代码

import org.springframework.ai.openai.OpenAiChatClient;
import org.springframework.ai.openai.api.OpenAiChatOptions;
import org.springframework.ai.openai.api.ResponseFormat;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.Map;

@RestController
public class AiController {

    private final OpenAiChatClient chatClient;

    public AiController(OpenAiChatClient chatClient) {
        this.chatClient = chatClient;
    }

    @GetMapping("/ai")
    public Map<String, Object> getStructuredResponse() {
        // 定义目标结构的JSON Schema
        String schema = """
                {
                    "type": "object",
                    "properties": {
                        "name": {"type": "string"},
                        "age": {"type": "integer"}
                    },
                    "required": ["name", "age"]
                }
                """;

        // 通过Spring AI封装类配置结构化输出
        OpenAiChatOptions options = OpenAiChatOptions.builder()
                .responseFormat(ResponseFormat.builder()
                        .type("json_schema")
                        .jsonSchema(Map.of(
                                "name", "UserInfo",
                                "schema", schema,
                                "strict", true
                        ))
                        .build())
                .build();

        return chatClient.call("生成一个用户信息", options);
    }
}

3. 验证基础配置正确性 #

确保application.properties中使用支持结构化输出的OpenAI模型，并配置正确的API密钥：

spring.ai.openai.api-key=your-api-key
spring.ai.openai.chat.options.model=gpt-4o

注：仅gpt-4o、gpt-4-turbo-2024-04-09及以上版本支持结构化输出功能

4. 排查请求体格式 #

若仍有问题，开启Spring AI的DEBUG日志，查看实际发送给OpenAI的请求体，确认参数是否符合官方规范。日志配置示例：

logging.level.org.springframework.ai.openai=DEBUG

内容的提问来源于stack exchange，提问作者SirBillyBobJoe