解析dotnet/extensions项目中AIFunction参数验证问题

问题背景

在dotnet/extensions项目的AI功能模块中，开发者MikeAlhayek遇到了一个关于AIFunction参数验证的问题。当尝试创建一个用于导入JSON配方的AIFunction时，系统抛出了一个关于参数schema验证的错误，提示"required"数组中包含了properties中不存在的键。

问题分析

原始代码问题

开发者最初实现的AIFunction定义了一个名为"import_recipe"的工具，期望接收一个JSON对象作为参数。关键问题出现在schema定义部分：

var metadata = new JsonObject
{
    {"type", "object"},
    {"properties", new JsonObject
        {
            { "recipe", new JsonObject
                {
                    {"type", "object" },
                    {"description", "A JSON object representing an OrchardCore recipe" },
                }
            }
        }
    },
    {"required", new JsonArray("recipe") },
    // 其他配置...
};

错误原因

根据微软团队成员的诊断，这个问题实际上是由两个因素共同导致的：

1. 缺少additionalProperties声明：在JSON Schema中，当type为object时，最佳实践是明确声明是否允许额外属性。这可以通过设置additionalProperties为true或false来实现。

2. 参数类型定义问题：将recipe参数的类型直接定义为"object"可能会导致一些验证问题，特别是在与AI服务交互时。

解决方案

临时解决方案

微软团队成员提供了两种临时解决方案：

1. 修改schema定义：将recipe参数的类型改为string，并添加additionalProperties声明：

JsonSchema = JsonSerializer.Deserialize<JsonElement>("""
    {
        "type": "object",
        "properties": {
            "recipe": {
                "type": "string",
                "description": "A JSON object representing an OrchardCore recipe"
            }
        },
        "additionalProperties": false,
        "required": ["recipe"]
    }
    """);

2. 禁用严格验证：通过设置AdditionalProperties来关闭严格验证模式：

public override IReadOnlyDictionary<string, object?> AdditionalProperties { get; } = new Dictionary<string, object?>()
{
    ["Strict"] = false,
};

根本解决方案

微软团队已经识别到这个问题是由于OpenAI服务默认开启了严格验证模式导致的，并已经在代码库中提交了修复（PR #6285），准备将strict模式的默认值改回false。

深入理解

JSON Schema验证

在实现AIFunction时，参数验证依赖于JSON Schema规范。一个完整的对象类型定义应该包含：

1. type声明
2. properties定义
3. additionalProperties声明
4. required数组（可选）

AIFunction调用机制

值得注意的是，即使解决了schema验证问题，开发者还需要正确处理函数调用请求。这通常需要：

1. 手动处理函数调用响应
2. 或者在管道中添加FunctionInvokingChatClient来自动处理

最佳实践建议

基于这个案例，我们可以总结出一些在dotnet/extensions项目中实现AIFunction的最佳实践：

1. 完整的schema定义：始终为对象类型参数提供完整的schema定义，包括additionalProperties声明。

2. 参数类型选择：对于复杂对象，考虑使用string类型接收JSON字符串，然后在代码中反序列化，这通常比直接使用object类型更可靠。

3. 错误处理：在InvokeCoreAsync方法中实现健壮的错误处理逻辑，特别是对于参数转换和验证。

4. 测试验证：在开发过程中充分测试各种边界情况，确保函数能够正确处理各种输入。

总结

这个案例展示了在dotnet/extensions项目中使用AIFunction时可能遇到的一个典型问题。通过理解JSON Schema的验证规则和AI服务的交互机制，开发者可以避免类似问题，构建更健壮的AI功能集成。微软团队已经识别并修复了相关问题，同时提供了临时解决方案，体现了开源社区协作解决问题的效率。