Spring AI 项目中OpenAI响应格式配置问题的分析与解决

在Spring AI项目的最新版本中，开发人员发现了一个关于OpenAI API响应格式配置的有趣问题。这个问题涉及到如何正确配置JSON Schema来约束OpenAI的响应输出格式。

问题背景

Spring AI项目为开发者提供了与OpenAI API交互的便捷方式。在1.0.0-M8版本中，文档指出可以通过配置文件来设置OpenAI的response_format参数，包括指定JSON Schema来约束返回数据的结构。然而，当开发者按照文档配置后，却收到了OpenAI API返回的400错误，提示"Unknown parameter: 'response_format.schema'"。

技术分析

深入分析问题根源，我们发现这与Spring AI内部对ResponseFormat类的处理方式有关。这个类承担了双重职责：

1. 作为配置属性的反序列化目标
2. 作为OpenAI API请求体的组成部分

在实现上，ResponseFormat类内部有一个schema字段，它会被用来构建最终的jsonSchema对象。问题在于，当这个schema字段被设置后，它也会被包含在最终发送给OpenAI API的请求中，而OpenAI API并不识别这个参数。

解决方案

经过社区讨论，确定了两种解决方案：

1. 临时解决方案：通过编程方式构建ResponseFormat对象，直接设置jsonSchema而绕过schema字段的设置。

ChatClient chatClient = builder
    .defaultOptions(OpenAiChatOptions.builder()
        .responseFormat(ResponseFormat.builder()
            .type(ResponseFormat.Type.JSON_SCHEMA)
            .jsonSchema(ResponseFormat.JsonSchema.builder()
                .schema("{\"type\":\"object\",...}")
                .strict(true)
                .build())
            .build())
        .build())
    .build();

2. 永久修复方案：在ResponseFormat类中为schema字段添加@JsonIgnore注解，确保它不会被序列化到API请求中。这个方案已经被合并到主分支中。

技术启示

这个案例给我们几个重要的技术启示：

1. DTO设计原则：当一个类同时用于配置反序列化和API请求时，需要特别注意字段的序列化行为。

2. API兼容性：在封装第三方API时，必须严格遵循其参数规范，任何额外的参数都可能导致请求失败。

3. 配置与运行时分离：配置阶段使用的数据结构可能需要与运行时API请求的数据结构有所不同，需要考虑如何优雅地转换。

最佳实践建议

对于需要在Spring AI中使用OpenAI JSON Schema功能的开发者，建议：

1. 如果使用最新版本，可以直接通过配置文件设置
2. 如果使用1.0.0-M8版本，可以采用编程式配置作为临时解决方案
3. 在定义复杂JSON Schema时，注意验证Schema本身的正确性
4. 考虑将大型Schema定义放在单独的文件中，而不是直接写在配置里

这个问题展示了开源社区如何协作解决技术问题的典型过程，从问题发现、分析到最终修复，体现了Spring生态系统的活力和响应能力。