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 Semantic Kernel 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:

• Automático: permite que o modelo de IA decida escolher entre zero ou mais das funções fornecidas para invocação.
• Obrigatório: força o modelo de IA a escolher as funções fornecidas.
• Nenhum: instrui o modelo de IA a não escolher nenhuma função.

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.

Observação

Os recursos de chamada de função só têm suporte em alguns conectores de IA até agora, consulte a seção Conectores de IA com suporte abaixo para obter mais detalhes.

Função Publicidade

A publicidade de funções é o processo de fornecer funções a modelos de IA para chamadas e invocações adicionais. Todos os três comportamentos de escolha de função aceitam uma lista de funções a serem anunciadas como um functions parâmetro. Por padrão, ele é nulo, o que significa que todas as funções de plug-ins registrados no Kernel são fornecidas ao 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, somente 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 desabilitar a chamada de função.

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 das funções fornecidas para invocação.

Neste exemplo, todas as funções dos DateTimeUtils plug-ins e WeatherForecastUtils serão fornecidas ao modelo de IA junto com o prompt. O modelo primeiro escolherá GetCurrentTime a função para invocação para obter a data e a 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 de 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ária

O Required comportamento força o modelo a escolher as funções fornecidas 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, e não de seu próprio conhecimento.

Observação

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 em que 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 primeiro escolherá a GetWeatherForCity função de invocação para recuperar a previsão do tempo. Com essas informações, o modelo pode 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));

Como alternativa, todas as funções registradas no kernel podem ser fornecidas ao modelo de IA conforme necessário. No entanto, apenas aqueles 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 ao modelo de IA em solicitações subsequentes para evitar um loop infinito, conforme 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 None

O None comportamento instrui o modelo de IA a usar as funções fornecidas sem escolher nenhuma delas para invocação para gerar uma resposta. Isso é útil para simulações quando o chamador pode querer ver quais funções o modelo escolheria sem realmente invocá-las. Também é útil quando você deseja que o modelo de IA extraia informações de uma pergunta do usuário, por exemplo, no exemplo abaixo, o modelo de IA descobriu corretamente que Boston era o nome da cidade.

Aqui, anunciamos todas as funções dos DateTimeUtils plug-ins e WeatherForecastUtils para o modelo de IA, mas o instruímos a não escolher nenhuma delas. Em vez disso, o modelo fornecerá uma resposta descrevendo quais funções ele 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 da 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 compatíveis

A partir de hoje, os seguintes conectores de IA no Kernel Semântico dão suporte ao modelo de chamada de função:

Conector de IA	FunctionChoiceBehavior	ToolCallBehavior
Anthropic	Planejado	❌
AzureAIInference	Em breve	❌
AzureOpenAI	✔️	✔️
Gemini	Planejado	✔️
HuggingFace	Planejado	❌
Mistral	Planejado	✔️
Ollama	Em breve	❌
ONNX	Em breve	❌
OpenAI	✔️	✔️

Em breve

Mais informações em breve.

Em breve

Mais informações em breve.