函数选择行为

函数选择行为是允许开发人员配置的位配置：

1. 向 AI 模型播发哪些函数。
2. 模型应如何选择它们进行调用。
3. 语义内核如何调用这些函数。

截至目前，函数选择行为由类的 FunctionChoiceBehavior 三种静态方法表示：

• 自动：允许 AI 模型决定从零个或多个提供的函数（s）中进行选择进行调用。
• 必需：强制 AI 模型选择提供的函数。
• 无：指示 AI 模型不选择任何函数。

警告

函数调用功能是实验性的，可能会更改。 预计到2024年11月中旬，它将正式发布。 请参阅 迁移指南 ，将代码迁移到最新的函数调用功能。

注意

到目前为止，函数调用功能仅受一些 AI 连接器支持，有关详细信息，请参阅 下面的“支持的 AI 连接器 ”部分。

函数广告

函数广告是向 AI 模型提供函数以进一步调用和调用的过程。 这三种函数选择行为都接受要播发为 functions 参数的函数列表。 默认情况下，它为 null，这意味着内核上注册的插件中的所有函数都提供给 AI 模型。

using Microsoft.SemanticKernel;

IKernelBuilder builder = Kernel.CreateBuilder(); 
builder.AddOpenAIChatCompletion("<model-id>", "<api-key>");
builder.Plugins.AddFromType<WeatherForecastUtils>();
builder.Plugins.AddFromType<DateTimeUtils>(); 

Kernel kernel = builder.Build();

// All functions from the DateTimeUtils and WeatherForecastUtils plugins will be sent to AI model together with the prompt.
PromptExecutionSettings settings = new() { FunctionChoiceBehavior = FunctionChoiceBehavior.Auto() }; 

await kernel.InvokePromptAsync("Given the current time of day and weather, what is the likely color of the sky in Boston?", new(settings));

如果提供了函数列表，则仅向 AI 模型发送这些函数：

using Microsoft.SemanticKernel;

IKernelBuilder builder = Kernel.CreateBuilder(); 
builder.AddOpenAIChatCompletion("<model-id>", "<api-key>");
builder.Plugins.AddFromType<WeatherForecastUtils>();
builder.Plugins.AddFromType<DateTimeUtils>(); 

Kernel kernel = builder.Build();

KernelFunction getWeatherForCity = kernel.Plugins.GetFunction("WeatherForecastUtils", "GetWeatherForCity");
KernelFunction getCurrentTime = kernel.Plugins.GetFunction("DateTimeUtils", "GetCurrentUtcDateTime");

// Only the specified getWeatherForCity and getCurrentTime functions will be sent to AI model alongside the prompt.
PromptExecutionSettings settings = new() { FunctionChoiceBehavior = FunctionChoiceBehavior.Auto(functions: [getWeatherForCity, getCurrentTime]) }; 

await kernel.InvokePromptAsync("Given the current time of day and weather, what is the likely color of the sky in Boston?", new(settings));

函数的空列表意味着没有向 AI 模型提供任何函数，这相当于禁用函数调用。

using Microsoft.SemanticKernel;

IKernelBuilder builder = Kernel.CreateBuilder(); 
builder.AddOpenAIChatCompletion("<model-id>", "<api-key>");
builder.Plugins.AddFromType<WeatherForecastUtils>();
builder.Plugins.AddFromType<DateTimeUtils>(); 

Kernel kernel = builder.Build();

// Disables function calling. Equivalent to var settings = new() { FunctionChoiceBehavior = null } or var settings = new() { }.
PromptExecutionSettings settings = new() { FunctionChoiceBehavior = FunctionChoiceBehavior.Auto(functions: []) }; 

await kernel.InvokePromptAsync("Given the current time of day and weather, what is the likely color of the sky in Boston?", new(settings));

使用自动函数选择行为

函数 Auto 选择行为指示 AI 模型决定从零个或多个提供的函数（s）中进行选择进行调用。

在此示例中，来自和WeatherForecastUtils插件的所有函数DateTimeUtils都将随提示一起提供给 AI 模型。 模型将首先选择 GetCurrentTime 用于调用的函数以获取当前日期和时间，因为需要此信息作为函数的 GetWeatherForCity 输入。 接下来，它将选择 GetWeatherForCity 用于调用的功能，以便使用获取的日期和时间获取波士顿市的天气预报。 通过此信息，模型将能够确定波士顿天空的可能颜色。

using Microsoft.SemanticKernel;

IKernelBuilder builder = Kernel.CreateBuilder(); 
builder.AddOpenAIChatCompletion("<model-id>", "<api-key>");
builder.Plugins.AddFromType<WeatherForecastUtils>();
builder.Plugins.AddFromType<DateTimeUtils>(); 

Kernel kernel = builder.Build();

// All functions from the DateTimeUtils and WeatherForecastUtils plugins will be provided to AI model alongside the prompt.
PromptExecutionSettings settings = new() { FunctionChoiceBehavior = FunctionChoiceBehavior.Auto() }; 

await kernel.InvokePromptAsync("Given the current time of day and weather, what is the likely color of the sky in Boston?", new(settings));

可以在 YAML 提示模板配置中轻松对同一示例进行建模：

using Microsoft.SemanticKernel;

IKernelBuilder builder = Kernel.CreateBuilder(); 
builder.AddOpenAIChatCompletion("<model-id>", "<api-key>");
builder.Plugins.AddFromType<WeatherForecastUtils>();
builder.Plugins.AddFromType<DateTimeUtils>(); 

Kernel kernel = builder.Build();

string promptTemplateConfig = """
    template_format: semantic-kernel
    template: Given the current time of day and weather, what is the likely color of the sky in Boston?
    execution_settings:
      default:
        function_choice_behavior:
          type: auto
    """;

KernelFunction promptFunction = KernelFunctionYaml.FromPromptYaml(promptTemplateConfig);

Console.WriteLine(await kernel.InvokeAsync(promptFunction));

使用必需的函数选择行为

该 Required 行为强制模型为调用选择提供的函数（s）。 这对于 AI 模型必须从指定函数获取所需信息，而不是从其自己的知识中获取所需信息的情况非常有用。

注意

该行为仅在第一个请求中播发函数，并停止在后续请求中发送函数，以防止无限循环，在该循环中模型会不断为调用选择相同的函数。

在这里，我们指定 AI 模型必须选择 GetWeatherForCity 调用函数以获取波士顿市的天气预报，而不是根据自己的知识来猜测它。 模型将首先选择 GetWeatherForCity 用于调用的函数来检索天气预报。 利用此信息，模型可以使用呼叫 GetWeatherForCity的响应来确定波士顿天空的可能颜色。

using Microsoft.SemanticKernel;

IKernelBuilder builder = Kernel.CreateBuilder(); 
builder.AddOpenAIChatCompletion("<model-id>", "<api-key>");
builder.Plugins.AddFromType<WeatherForecastUtils>();

Kernel kernel = builder.Build();

KernelFunction getWeatherForCity = kernel.Plugins.GetFunction("WeatherForecastUtils", "GetWeatherForCity");

PromptExecutionSettings settings = new() { FunctionChoiceBehavior = FunctionChoiceBehavior.Required(functions: [getWeatherFunction]) };

await kernel.InvokePromptAsync("Given that it is now the 10th of September 2024, 11:29 AM, what is the likely color of the sky in Boston?", new(settings));

YAML 模板配置中的相同示例：

using Microsoft.SemanticKernel;

IKernelBuilder builder = Kernel.CreateBuilder(); 
builder.AddOpenAIChatCompletion("<model-id>", "<api-key>");
builder.Plugins.AddFromType<WeatherForecastUtils>();

Kernel kernel = builder.Build();

string promptTemplateConfig = """
    template_format: semantic-kernel
    template: Given that it is now the 10th of September 2024, 11:29 AM, what is the likely color of the sky in Boston?
    execution_settings:
      default:
        function_choice_behavior:
          type: auto
          functions:
            - WeatherForecastUtils.GetWeatherForCity
    """;

KernelFunction promptFunction = KernelFunctionYaml.FromPromptYaml(promptTemplateConfig);

Console.WriteLine(await kernel.InvokeAsync(promptFunction));

或者，可以根据需要向 AI 模型提供内核中注册的所有函数。 但是，语义内核将只调用由 AI 模型选择的第一个请求的结果。 后续请求中不会将函数发送到 AI 模型，以防止无限循环，如上所述。

using Microsoft.SemanticKernel;

IKernelBuilder builder = Kernel.CreateBuilder(); 
builder.AddOpenAIChatCompletion("<model-id>", "<api-key>");
builder.Plugins.AddFromType<WeatherForecastUtils>();

Kernel kernel = builder.Build();

PromptExecutionSettings settings = new() { FunctionChoiceBehavior = FunctionChoiceBehavior.Required() };

await kernel.InvokePromptAsync("Given that it is now the 10th of September 2024, 11:29 AM, what is the likely color of the sky in Boston?", new(settings));

使用 None 函数选择行为

该 None 行为指示 AI 模型使用提供的函数（s），而无需选择其中任何函数来调用以生成响应。 当调用方可能想要查看模型选择哪些函数而不实际调用它们时，这对于干运行非常有用。 如果希望 AI 模型从用户请求中提取信息，例如在下面的示例中正确找出波士顿是城市名称，则它还很有用。

在这里，我们将所有函数从 DateTimeUtils 和 WeatherForecastUtils 插件播发到 AI 模型，但指示它不选择其中任何函数。 相反，模型将提供一个响应，描述它将选择哪些功能来确定波士顿指定日期的天空颜色。

using Microsoft.SemanticKernel;

IKernelBuilder builder = Kernel.CreateBuilder(); 
builder.AddOpenAIChatCompletion("<model-id>", "<api-key>");
builder.Plugins.AddFromType<WeatherForecastUtils>();
builder.Plugins.AddFromType<DateTimeUtils>(); 

Kernel kernel = builder.Build();

KernelFunction getWeatherForCity = kernel.Plugins.GetFunction("WeatherForecastUtils", "GetWeatherForCity");

PromptExecutionSettings settings = new() { FunctionChoiceBehavior = FunctionChoiceBehavior.None() };

await kernel.InvokePromptAsync("Specify which provided functions are needed to determine the color of the sky in Boston on a specified date.", new(settings))

// Sample response: To determine the color of the sky in Boston on a specified date, first call the DateTimeUtils-GetCurrentUtcDateTime function to obtain the 
// current date and time in UTC. Next, use the WeatherForecastUtils-GetWeatherForCity function, providing 'Boston' as the city name and the retrieved UTC date and time. 
// These functions do not directly provide the sky's color, but the GetWeatherForCity function offers weather data, which can be used to infer the general sky condition (e.g., clear, cloudy, rainy).

YAML 提示模板配置中的相应示例：

using Microsoft.SemanticKernel;

IKernelBuilder builder = Kernel.CreateBuilder(); 
builder.AddOpenAIChatCompletion("<model-id>", "<api-key>");
builder.Plugins.AddFromType<WeatherForecastUtils>();
builder.Plugins.AddFromType<DateTimeUtils>(); 

Kernel kernel = builder.Build();

string promptTemplateConfig = """
    template_format: semantic-kernel
    template: Specify which provided functions are needed to determine the color of the sky in Boston on a specified date.
    execution_settings:
      default:
        function_choice_behavior:
          type: none
    """;

KernelFunction promptFunction = KernelFunctionYaml.FromPromptYaml(promptTemplateConfig);

Console.WriteLine(await kernel.InvokeAsync(promptFunction));

函数调用

函数调用是 Sematic Kernel 调用 AI 模型选择的函数的过程。 有关函数调用的更多详细信息，请参阅 函数调用文章。

支持的 AI 连接器

截至目前，语义内核中的以下 AI 连接器支持函数调用模型：

AI 连接器	FunctionChoiceBehavior	ToolCallBehavior
Anthropic	已计划	❌
AzureAIInference	即将推出	❌
AzureOpenAI	✔️	✔️
双子座	已计划	✔️
HuggingFace	已计划	❌
Mistral	已计划	✔️
Ollama	即将推出	❌
Onnx	即将推出	❌
OpenAI	✔️	✔️

即将推出

更多信息即将推出。

即将推出

更多信息即将推出。