OpenAI Swift库中JSON Schema与函数调用功能更新解析

背景概述

OpenAI官方Swift库近期对函数调用功能进行了重要更新，主要涉及JSON Schema的结构调整。这一变更导致原有文档中的示例代码出现兼容性问题，特别是ChatFunctionDeclaration和JSONSchema相关接口发生了显著变化。

核心变更点

1. 接口重构：

   • 原ChatFunctionDeclaration结构已被重新设计
   • JSONSchema类型系统进行了全面升级
   • 函数参数定义方式发生了本质性改变

2. 新版实现方案： 现在推荐使用FunctionDefinition结构来声明函数，其参数规范采用新的JSON Schema系统。示例代码如下：

let functions = [
    FunctionDefinition(
        name: "get_current_weather",
        description: "获取指定位置的当前天气",
        parameters: JSONSchema(
            type: .object,
            properties: [
                "location": .string(description: "城市和州，例如：San Francisco, CA"),
                "unit": .string(enum: ["celsius", "fahrenheit"])
            ],
            required: ["location"]
        )
    )
]

迁移建议

对于正在使用旧版本代码的开发者，建议进行以下调整：

1. 将ChatFunctionDeclaration替换为FunctionDefinition

2. 更新JSON Schema的构建方式，注意：

   • 基础类型直接使用类型枚举（如.string）
   • 枚举值通过.string(enum:)方式声明
   • 描述文本改为参数形式传递

3. 确保使用的模型版本支持函数调用功能（如gpt-3.5-turbo-0613及以上）

技术细节解析

新的JSON Schema系统采用更符合Swift语言习惯的设计：

• 类型安全：通过枚举确保参数类型正确
• 链式语法：支持更流畅的参数定义方式
• 更好的文档支持：每个参数都可以附加详细描述

最佳实践

1. 始终检查使用的库版本是否包含最新函数调用实现
2. 复杂参数结构建议分层定义：

let locationSchema = JSONSchema.object(properties: [
    "city": .string(),
    "country": .string()
])

3. 对于可选参数，可以不包含在required数组中

总结

OpenAI Swift库的函数调用功能经过此次重构，在类型安全和易用性方面都有显著提升。开发者需要及时更新实现代码以适应新的API设计。这种改进虽然带来短期适配成本，但从长期看将提高代码的可靠性和可维护性。