ASP.NET Extensions项目中AIFunctionFactory的CancellationToken序列化问题解析

背景

在ASP.NET Extensions项目的AI功能模块中，AIFunctionFactory是一个用于将.NET方法转换为AI可调用函数的重要组件。最近发现了一个值得开发者注意的实现细节问题：当处理包含CancellationToken参数的异步方法时，该工厂会不必要地将CancellationToken参数序列化为JSON Schema。

问题现象

当开发者使用AIFunctionFactory.Create()方法包装一个包含CancellationToken参数的异步方法时，例如：

[Description("获取书籍页面内容")]
public static Task<string> GetBookPageContentAsync(string bookName, int bookPageNumber, CancellationToken cancellationToken = default)
{
    return Task.FromResult("示例内容");
}

生成的JSON Schema会包含完整的CancellationToken结构信息，包括isCancellationRequested、canBeCanceled和waitHandle等内部属性。这些信息对于AI功能调用而言是完全不需要的，反而会增加通信负担并可能引起混淆。

技术影响

这种序列化行为会带来几个实际问题：

1. 无效数据传输：CancellationToken是用于控制异步操作取消的机制，AI模型根本不需要了解其内部结构
2. Schema冗余：生成的JSON Schema变得臃肿，增加了不必要的网络传输量
3. 潜在混淆：AI模型可能会误认为这些参数是需要它处理的输入

解决方案

项目团队已经识别并修复了这个问题。修复方案的核心思想是：

1. 在生成函数签名时，自动忽略CancellationToken类型的参数
2. 确保这些运行时控制参数不会出现在最终暴露给AI的接口定义中

最佳实践

开发者在设计AI可调用函数时应注意：

1. 将CancellationToken参数放在方法参数列表的最后位置
2. 为其提供默认值(default)
3. 避免在方法签名中包含其他运行时特有的参数类型
4. 专注于定义AI真正需要了解和处理的业务参数

总结

这个问题的发现和修复体现了ASP.NET Extensions项目对细节的关注。对于开发者而言，理解这类底层机制有助于编写更高效的AI集成代码。虽然CancellationToken在异步编程中很重要，但在AI函数接口的场景下，它应该被视为实现细节而非接口契约的一部分。