Comportamentos de escolha de função

Os comportamentos de escolha de função são bits de configuração que permitem que um desenvolvedor configure:

1. Quais funções são anunciadas para modelos de IA.
2. Como os modelos devem escolhê-los para invocação.
3. Como o Kernel Semântico pode invocar essas funções.

A partir de hoje, os comportamentos de escolha de função são representados por três métodos estáticos da FunctionChoiceBehavior classe:

• Auto: Permite que o modelo de IA decida escolher entre zero ou mais da(s) função(ões) fornecida(s) para invocação.
• Necessário: força o modelo de IA a escolher a(s) função(ões) fornecida(s).
• Nenhuma: instrui o modelo de IA a não escolher nenhuma função(ões).

Aviso

A capacidade de chamada de função é experimental e está sujeita a alterações. Espera-se que atinja a disponibilidade geral (GA) em meados de novembro de 2024. Consulte o guia de migração para migrar seu código para os recursos de chamada de função mais recentes.

Nota

Os recursos de chamada de função são suportados apenas por alguns conectores AI até agora, consulte a seção Conectores AI suportados abaixo para obter mais detalhes.

Função Publicidade

A publicidade de funções é o processo de fornecer funções a modelos de IA para posterior chamada e invocação. Todos os três comportamentos de escolha de função aceitam uma lista de funções para anunciar como parâmetro functions . Por padrão, é null, o que significa que todas as funções de plugins registrados no Kernel são fornecidas para o modelo de IA.

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));

Se uma lista de funções for fornecida, apenas essas funções serão enviadas para o modelo de IA:

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));

Uma lista vazia de funções significa que nenhuma função é fornecida ao modelo de IA, o que equivale a desativar a chamada de funções.

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));

Usando o comportamento de escolha automática de função

O Auto comportamento de escolha de função instrui o modelo de IA a decidir escolher entre zero ou mais da(s) função(ões) fornecida(s) para invocação.

Neste exemplo, todas as funções do e WeatherForecastUtils plugins serão fornecidas ao modelo de DateTimeUtils IA juntamente com o prompt. O modelo primeiro escolherá GetCurrentTime a função para invocação para obter a data e hora atuais, pois essas informações são necessárias como entrada para a GetWeatherForCity função. Em seguida, ele escolherá GetWeatherForCity a função para invocação para obter a previsão do tempo para a cidade de Boston usando a data e hora obtidas. Com essas informações, o modelo será capaz de determinar a cor provável do céu em Boston.

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));

O mesmo exemplo pode ser facilmente modelado em uma configuração de modelo de prompt 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));

Usando o comportamento de escolha de função necessário

O Required comportamento força o modelo a escolher a(s) função(ões) fornecida(s) para a invocação. Isso é útil para cenários em que o modelo de IA deve obter as informações necessárias das funções especificadas em vez de seu próprio conhecimento.

Nota

O comportamento anuncia funções na primeira solicitação apenas para o modelo de IA e para de enviá-las em solicitações subsequentes para evitar um loop infinito onde o modelo continua escolhendo as mesmas funções para invocação repetidamente.

Aqui, especificamos que o modelo de IA deve escolher a GetWeatherForCity função de invocação para obter a previsão do tempo para a cidade de Boston, em vez de adivinhá-la com base em seu próprio conhecimento. O modelo escolherá primeiro a GetWeatherForCity função de invocação para recuperar a previsão do tempo. Com essas informações, o modelo pode então determinar a cor provável do céu em Boston usando a resposta da chamada para 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));

Um exemplo idêntico em uma configuração de modelo 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));

Alternativamente, todas as funções registradas no kernel podem ser fornecidas ao modelo de IA, conforme necessário. No entanto, apenas os escolhidos pelo modelo de IA como resultado da primeira solicitação serão invocados pelo Kernel Semântico. As funções não serão enviadas para o modelo de IA em solicitações subsequentes para evitar um loop infinito, como mencionado acima.

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));

Usando o comportamento de escolha de função nenhuma

O None comportamento instrui o modelo de IA a usar a(s) função(ões) fornecida(s) sem escolher nenhuma delas para invocação para gerar uma resposta. Isso é útil para execuções secas quando o chamador pode querer ver quais funções o modelo escolheria sem realmente invocá-las. Também é útil quando você quer que o modelo de IA extraia informações de um usuário pergunte, por exemplo, na amostra abaixo do modelo de IA corretamente trabalhado que Boston era o nome da cidade.

Aqui, anunciamos todas as funções, desde o DateTimeUtils e WeatherForecastUtils plugins até o modelo de IA, mas instruímos a não escolher nenhuma delas. Em vez disso, o modelo fornecerá uma resposta descrevendo quais funções escolheria para determinar a cor do céu em Boston em uma data especificada.

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).

Um exemplo correspondente em uma configuração de modelo de prompt 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));

Invocação de função

A invocação de função é o processo pelo qual o Sematic Kernel invoca funções escolhidas pelo modelo de IA. Para obter mais detalhes sobre a invocação de função, consulte o artigo de invocação de função.

Conectores AI suportados

A partir de hoje, os seguintes conectores AI no Kernel Semântico suportam o modelo de chamada de função:

Conector AI	FunctionChoiceBehavior	ToolCallBehavior
Anthropic	Planeado	❌
AzureAIInference	Brevemente	❌
AzureOpenAI	✔️	✔️
Gêmeos	Planeado	✔️
HuggingFace	Planeado	❌
Mistral	Planeado	✔️
Ollama	Brevemente	❌
Onnx	Brevemente	❌
OpenAI	✔️	✔️

Brevemente

Mais informações em breve.

Brevemente

Mais informações em breve.