让LLM更懂函数返回类型

当前，在向AI模型提供函数返回类型元数据这一领域，尚未有清晰明确的行业标准。当出现返回类型属性的名称无法让大语言模型（LLM）准确推断其内容，或者需要关联其他上下文信息、处理指令到返回类型，以此来实现方案建模或增强方案效果的情况时，可考虑运用以下技术：

1. 在对函数进行描述的过程中，清晰地给出函数返回类型的相关信息。
2. 将函数返回类型的模式（schema）作为函数返回值的组成部分一并提供。

值得注意的是，在决定采用上述任何一种技术之前，最好先为返回类型属性拟定更具描述性的名称。这是因为这一举措是提升大语言模型（LLM）对返回类型理解程度的最直接途径，而且从令牌使用的角度来看，这种做法也能有效控制成本，具有较高的性价比。

准备工作

using PolyglotKernel= Microsoft.DotNet.Interactive.Kernel;// 引入交互式的内核命名空间，以便用户输入
using Microsoft.SemanticKernel.Connectors.OpenAI;

var aiProviderCode = await PolyglotKernel.GetInputAsync("请输入AI服务提供商编码：");

var kernel = GetKernel(aiProviderCode);
var chatCompletionService = kernel.GetRequiredService<IChatCompletionService>();

一、在函数描述中提供函数返回类型信息

有两种方法，但都需要手动添加返回类型元数据信息，当返回类型变更时需要同步更改，适用于返回类型比较稳定的场景。

1. 在函数中提供返回类型描述

以下定义了一个空气插件用于获取天气信息，包含温度、湿度、露点温度和风速信息。通过直接在[KernelFunction]中定义[Desciption]用自然语言直接描述返回值的单位信息。
此种情况适用于：

• 某些模型可能对函数描述的大小有限制
• 如果类型信息不重要
• 需要优先考虑最大限度地减少令牌消耗

using System.ComponentModel;

/// <summary>
/// A plugin that provides the current weather data and describes the return type in the function <see cref="DescriptionAttribute"/>.
/// </summary>
private sealed class WeatherPlugin1
{
    [KernelFunction]
    [Description("Returns current weather: Data1 - Temperature (°C), Data2 - Humidity (%), Data3 - Dew Point (°C), Data4 - Wind Speed (km/h)")]
    public WeatherData GetWeatherData()
    {
        return new WeatherData()
        {
            Data1 = 35.0,  // Temperature in degrees Celsius  
            Data2 = 20.0,  // Humidity in percentage  
            Data3 = 10.0,  // Dew point in degrees Celsius  
            Data4 = 15.0   // Wind speed in kilometers per hour
        };
    }
    public sealed class WeatherData
    {
        public double Data1 { get; set; }
        public double Data2 { get; set; }
        public double Data3 { get; set; }
        public double Data4 { get; set; }
    }
}

kernel.Plugins.Clear();
kernel.ImportPluginFromType<WeatherPlugin1>();

OpenAIPromptExecutionSettings settings = new() { FunctionChoiceBehavior = FunctionChoiceBehavior.Auto() };
FunctionResult result = await kernel.InvokePromptAsync("What is the current weather?", new(settings));
Console.Write(result);

The current weather is as follows:
- Temperature: 35°C
- Humidity: 20%
- Dew Point: 10°C
- Wind Speed: 15 km/h

查看日志，可以看出发出的请求数据包如下：
第一次请求的数据：

{
    "tools": [
        {
            "function": {
                "description": "Returns current weather: Data1 - Temperature (°C), Data2 - Humidity (%), Data3 - Dew Point (°C), Data4 - Wind Speed (km/h)",
                "name": "WeatherPlugin1-GetWeatherData",
                "strict": false,
                "parameters": {
                    "type": "object",
                    "required": [],
                    "properties": {}
                }
            },
            "type": "function"
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "What is the current weather?"
        },
    ],
    "model": "gpt-4o",
    "tool_choice": "auto"
}

第二次请求的数据：

{
    "tools": [
        {
            "function": {
                "description": "Returns current weather: Data1 - Temperature (°C), Data2 - Humidity (%), Data3 - Dew Point (°C), Data4 - Wind Speed (km/h)",
                "name": "WeatherPlugin1-GetWeatherData",
                "strict": false,
                "parameters": {
                    "type": "object",
                    "required": [],
                    "properties": {}
                }
            },
            "type": "function"
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "What is the current weather?"
        },
        {
            "role": "assistant",
            "content": "",
            "tool_calls": [
                {
                    "id": "call_M9mfYHD8nLiFTiF0HOiLT2r2",
                    "function": {
                        "name": "WeatherPlugin1-GetWeatherData",
                        "arguments": "{}"
                    },
                    "type": "function"
                }
            ]
        },
        {
            "role": "tool",
            "tool_call_id": "call_M9mfYHD8nLiFTiF0HOiLT2r2",
            "content": "{"Data1":35,"Data2":20,"Data3":10,"Data4":15}"
        }
    ],
    "model": "gpt-4o",
    "tool_choice": "auto"
}

2. 在函数描述中添加返回类型元数据

以下定义了一个空气插件用于获取天气信息，包含温度、湿度、露点温度和风速信息。通过直接在[KernelFunction]中定义[Description]来描述返回值的单位信息，其中[Description]中包含返回值的元数据信息：

{
    "type": "object",
    "properties": {
        "Data1": {
            "description": "Temperature (°C)",
            "type": "number"
        },
        "Data2": {
            "description": "Humidity(%)",
            "type": "number"
        },
        "Data3": {
            "description": "Dew point (°C)",
            "type": "number"
        },
        "Data4": {
            "description": "Wind speed (km/h)",
            "type": "number"
        }
    }
}

using System.ComponentModel;

/// <summary>
/// A plugin that provides the current weather data and specifies the return type schema in the function <see cref="DescriptionAttribute"/>.
/// </summary>
private sealed class WeatherPlugin2
{
    [KernelFunction]
    [Description("""Returns current weather: {"type":"object","properties":{"Data1":{"description":"Temperature (°C)","type":"number"},"Data2":{"description":"Humidity(%)","type":"number"}, "Data3":{"description":"Dew point (°C)","type":"number"},"Data4":{"description":"Wind speed (km/h)","type":"number"}}}""")]
    public WeatherData GetWeatherData()
    {
        return new WeatherData()
        {
            Data1 = 35.0,  // Temperature in degrees Celsius  
            Data2 = 20.0,  // Humidity in percentage  
            Data3 = 10.0,  // Dew point in degrees Celsius  
            Data4 = 15.0   // Wind speed in kilometers per hour
        };
    }
    public sealed class WeatherData
    {
        public double Data1 { get; set; }
        public double Data2 { get; set; }
        public double Data3 { get; set; }
        public double Data4 { get; set; }
    }
}

kernel.Plugins.Clear();
kernel.ImportPluginFromType<WeatherPlugin2>();

OpenAIPromptExecutionSettings settings = new() { FunctionChoiceBehavior = FunctionChoiceBehavior.Auto() };
FunctionResult result = await kernel.InvokePromptAsync("What is the current weather?", new(settings));
Console.WriteLine(result);

The current weather is as follows:
- Temperature: 35°C
- Humidity: 20%
- Dew point: 10°C
- Wind speed: 15 km/h

查看日志，可以看出发出的请求数据包如下：

{
    "tools": [
        {
            "function": {
                "description": "Returns current weather: {"type":"object","properties":{"Data1":{"description":"Temperature (°C)","type":"number"},"Data2":{"description":"Humidity(%)","type":"number"}, "Data3":{"description":"Dew point (°C)","type":"number"},"Data4":{"description":"Wind speed (km/h)","type":"number"}}}",
                "name": "WeatherPlugin2-GetWeatherData",
                "strict": false,
                "parameters": {
                    "type": "object",
                    "required": [],
                    "properties": {}
                }
            },
            "type": "function"
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "What is the current weather?"
        },
        {
            "role": "assistant",
            "content": "",
            "tool_calls": [
                {
                    "id": "call_HjCyu9atNmesxuOc0cAyeafP",
                    "function": {
                        "name": "WeatherPlugin2-GetWeatherData",
                        "arguments": "{}"
                    },
                    "type": "function"
                }
            ]
        },
        {
            "role": "tool",
            "tool_call_id": "call_HjCyu9atNmesxuOc0cAyeafP",
            "content": "{"Data1":35,"Data2":20,"Data3":10,"Data4":15}"
        }
    ],
    "model": "gpt-4o",
    "tool_choice": "auto"
}

二、实现函数返回值重写过滤器

之前介绍了可以通过实现自定义IAutoFunctionInvocationFilter接口来实现请求重写。
以下定义了一个空气插件用于获取天气信息，包含温度、湿度、露点温度和风速信息。并没有在[KernelFucntion]中添加返回值描述，而是在返回类型中定义[Description]来描述各个属性，然后通过过滤器来重写返回值，将返回类型的元数据包含在其中。

    /// <summary>
    /// A plugin that provides the current weather data and provides descriptions for the return type properties.
    /// </summary>
    private sealed class WeatherPlugin3
    {
        [KernelFunction]
        public WeatherData GetWeatherData()
        {
            return new WeatherData()
            {
                Data1 = 35.0,  // Temperature in degrees Celsius  
                Data2 = 20.0,  // Humidity in percentage  
                Data3 = 10.0,  // Dew point in degrees Celsius  
                Data4 = 15.0   // Wind speed in kilometers per hour
            };
        }

        public sealed class WeatherData
        {
            [Description("Temp (°C)")]
            public double Data1 { get; set; }

            [Description("Humidity (%)")]
            public double Data2 { get; set; }

            [Description("Dew point (°C)")]
            public double Data3 { get; set; }

            [Description("Wind speed (km/h)")]
            public double Data4 { get; set; }
        }
    }

/// <summary>
/// A auto function invocation filter that replaces the original function's result with a new result that includes both the original result and its schema.
/// </summary>
private sealed class AddReturnTypeSchemaFilter : IAutoFunctionInvocationFilter
{
    public async Task OnAutoFunctionInvocationAsync(AutoFunctionInvocationContext context, Func<AutoFunctionInvocationContext, Task> next)
    {
        // Invoke the function
        await next(context);
        // Crete the result with the schema
        FunctionResultWithSchema resultWithSchema = new()
        {
            Value = context.Result.GetValue<object>(),                  // Get the original result
            Schema = context.Function.Metadata.ReturnParameter?.Schema  // Get the function return type schema
        };
        // Return the result with the schema instead of the original one
        context.Result = new FunctionResult(context.Result, resultWithSchema);
    }
    private sealed class FunctionResultWithSchema
    {
        public object? Value { get; set; }
        public KernelJsonSchema? Schema { get; set; }
    }
}

kernel.AutoFunctionInvocationFilters.Add(new AddReturnTypeSchemaFilter());
// Import the plugin that provides descriptions for the return type properties.   
// This additional information is used when extracting the schema from the return type.
kernel.Plugins.Clear();
kernel.ImportPluginFromType<WeatherPlugin3>();
OpenAIPromptExecutionSettings settings = new() { FunctionChoiceBehavior = FunctionChoiceBehavior.Auto() };
FunctionResult result = await kernel.InvokePromptAsync("What is the current weather?", new(settings));
Console.WriteLine(result);

The current weather is as follows:
- Temperature: 35°C
- Humidity: 20%
- Dew Point: 10°C
- Wind Speed: 15 km/h

查看日志，可以看出发出的请求如下：
第一次请求：

{
    "tools": [
        {
            "function": {
                "description": "",
                "name": "WeatherPlugin3-GetWeatherData",
                "strict": false,
                "parameters": {
                    "type": "object",
                    "required": [],
                    "properties": {}
                }
            },
            "type": "function"
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "What is the current weather?"
        }
    ],
    "model": "gpt-4o",
    "tool_choice": "auto"
}

第二次请求：

{
    "tools": [
        {
            "function": {
                "description": "",
                "name": "WeatherPlugin3-GetWeatherData",
                "strict": false,
                "parameters": {
                    "type": "object",
                    "required": [],
                    "properties": {}
                }
            },
            "type": "function"
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "What is the current weather?"
        },
        {
            "role": "assistant",
            "content": "",
            "tool_calls": [
                {
                    "id": "call_wb7JgQOZ8e4jXgkclXmR7pik",
                    "function": {
                        "name": "WeatherPlugin3-GetWeatherData",
                        "arguments": "{}"
                    },
                    "type": "function"
                }
            ]
        },
        {
            "role": "tool",
            "tool_call_id": "call_wb7JgQOZ8e4jXgkclXmR7pik",
            "content": "{"Value":{"Data1":35,"Data2":20,"Data3":10,"Data4":15},"Schema":{"type":"object","properties":{"Data1":{"description":"Temp (°C)","type":"number"},"Data2":{"description":"Humidity (%)","type":"number"},"Data3":{"description":"Dew point (°C)","type":"number"},"Data4":{"description":"Wind speed (km/h)","type":"number"}}}}"
        }
    ],
    "model": "gpt-4o",
    "tool_choice": "auto"
}