BeeAI框架中createStructure函数与Zod联合类型的兼容性问题分析

问题背景

在使用BeeAI框架(0.1.14版本)时，开发者遇到了一个关于createStructure函数与Zod联合类型(z.union)的兼容性问题。当尝试使用z.union定义响应结构时，系统会抛出"Invalid schema for function 'json'"的错误，提示schema必须是type为"object"的JSON Schema，而实际得到的是type为"None"。

问题现象

开发者尝试使用以下代码结构：

const response = await model.createStructure({
  schema: z.union([
    z.object({
      firstName: z.string().min(1),
      lastName: z.string().min(1),
      // 其他字段...
    }),
    z.object({
      error: z.string(),
    }),
  ]),
  messages: [new UserMessage("生成欧洲公民的个人资料")]
});

这段代码在BeeAI 0.1.13版本中可以正常工作，但在0.1.14版本中会抛出错误。

技术分析

根本原因

这个问题源于OpenAI API对JSON Schema的严格要求。根据OpenAI的文档，顶层对象不能使用anyOf结构（Zod的z.union在底层会转换为anyOf）。这是API设计上的限制，要求顶层schema必须是一个明确的对象类型。

解决方案探索

开发者尝试了几种解决方案：

1. 使用z.discriminatedUnion：理论上这是处理联合类型的推荐方式，但在实际测试中未能解决问题。

2. 使用单一对象加可选字段：开发者最终采用了这种变通方案：

z.object({
  status: z.literal('success'),
  // 其他字段...
  error: z.string().optional(),
}).refine(data => !!data.error || !!data.status, {
  message: "必须提供status或error"
})

3. 降级到0.1.13版本：确认在旧版本中可以正常工作，表明这是0.1.14引入的兼容性问题。

最佳实践建议

1. 避免顶层使用联合类型：遵循OpenAI API的限制，顶层schema应该始终是一个明确的对象类型。

2. 使用状态字段区分不同情况：如示例中所示，使用status字段和可选error字段来区分成功和错误情况。

3. 版本兼容性检查：在升级框架版本时，特别注意与现有schema定义的兼容性。

4. 错误处理策略：考虑将错误处理与正常响应分离到不同层级，而不是在同一层级使用联合类型。

总结

这个问题揭示了在使用AI模型结构化输出时，框架实现与底层API限制之间的微妙关系。开发者需要理解：

• OpenAI API对JSON Schema的特定要求
• Zod类型系统与JSON Schema之间的转换规则
• 框架版本升级可能带来的兼容性变化

通过采用状态字段模式而非联合类型，开发者可以创建既符合API要求又能表达业务逻辑的schema定义。这也提醒我们在设计AI应用的数据结构时，需要考虑底层技术栈的限制和最佳实践。