Modalità di chiamata di funzione

Quando il modello di intelligenza artificiale riceve un prompt contenente un elenco di funzioni, può scegliere uno o più di essi per completare la richiesta. Quando si seleziona una funzione dal modello, è necessario richiamarla dal kernel semantico.

La funzione che chiama il sottosistema nel kernel semantico ha due modalità di chiamata di funzione: auto e manuale.

A seconda della modalità di chiamata, il kernel semantico esegue una chiamata di funzione end-to-end o fornisce al chiamante il controllo sul processo di chiamata della funzione.

Chiamata di funzione automatica

La chiamata automatica della funzione è la modalità predefinita del sottosistema di chiamata a funzione del kernel semantico. Quando il modello di intelligenza artificiale sceglie una o più funzioni, il kernel semantico richiama automaticamente le funzioni scelte. I risultati di queste chiamate di funzione vengono aggiunti alla cronologia delle chat e inviati automaticamente al modello nelle richieste successive. Il modello quindi motivi sulla cronologia delle chat, sceglie funzioni aggiuntive, se necessario o genera la risposta finale. Questo approccio è completamente automatizzato e non richiede alcun intervento manuale del chiamante.

Questo esempio illustra come usare la chiamata alla funzione automatica nel kernel semantico. Il modello di intelligenza artificiale decide quali funzioni chiamare per completare il prompt e il kernel semantico esegue il resto e li richiama automaticamente.

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

// By default, functions are set to be automatically invoked.  
// If you want to explicitly enable this behavior, you can do so with the following code:  
// PromptExecutionSettings settings = new() { FunctionChoiceBehavior = FunctionChoiceBehavior.Auto(autoInvoke: true) };  
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));

Alcuni modelli di intelligenza artificiale supportano la chiamata a funzioni parallele, in cui il modello sceglie più funzioni per la chiamata. Ciò può essere utile nei casi in cui richiamare le funzioni scelte richiede molto tempo. Ad esempio, l'intelligenza artificiale può scegliere di recuperare le ultime notizie e l'ora corrente contemporaneamente, invece di effettuare un round trip per funzione.

Il kernel semantico può richiamare queste funzioni in due modi diversi:

• Sequenziale: le funzioni vengono richiamate una dopo l'altra. Questo è il comportamento predefinito.
• Simultaneamente: le funzioni vengono richiamate contemporaneamente. Questa opzione può essere abilitata impostando la FunctionChoiceBehaviorOptions.AllowConcurrentInvocation proprietà su true, come illustrato nell'esempio seguente.

using Microsoft.SemanticKernel;

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

Kernel kernel = builder.Build();

// Enable concurrent invocation of functions to get the latest news and the current time.
FunctionChoiceBehaviorOptions options = new() { AllowConcurrentInvocation = true };

PromptExecutionSettings settings = new() { FunctionChoiceBehavior = FunctionChoiceBehavior.Auto(options: options) }; 

await kernel.InvokePromptAsync("Good morning! What is the current time and latest news headlines?", new(settings));

Chiamata di funzione manuale

Nei casi in cui il chiamante vuole avere un maggiore controllo sul processo di chiamata della funzione, è possibile usare la chiamata manuale della funzione.

Quando la chiamata manuale della funzione è abilitata, il kernel semantico non richiama automaticamente le funzioni scelte dal modello di intelligenza artificiale. Restituisce invece un elenco di funzioni scelte al chiamante, che può quindi decidere quali funzioni richiamare, richiamarle in sequenza o in parallelo, gestire le eccezioni e così via. I risultati della chiamata della funzione devono essere aggiunti alla cronologia delle chat e restituiti al modello, che ne determinano i motivi e decidono se scegliere funzioni aggiuntive o generare la risposta finale.

L'esempio seguente illustra come usare la chiamata manuale della funzione.

using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.ChatCompletion;

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

Kernel kernel = builder.Build();

IChatCompletionService chatCompletionService = kernel.GetRequiredService<IChatCompletionService>();

// Manual function invocation needs to be enabled explicitly by setting autoInvoke to false.
PromptExecutionSettings settings = new() { FunctionChoiceBehavior = Microsoft.SemanticKernel.FunctionChoiceBehavior.Auto(autoInvoke: false) };

ChatHistory chatHistory = [];
chatHistory.AddUserMessage("Given the current time of day and weather, what is the likely color of the sky in Boston?");

while (true)
{
    ChatMessageContent result = await chatCompletionService.GetChatMessageContentAsync(chatHistory, settings, kernel);

    // Check if the AI model has generated a response.
    if (result.Content is not null)
    {
        Console.Write(result.Content);
        // Sample output: "Considering the current weather conditions in Boston with a tornado watch in effect resulting in potential severe thunderstorms,
        // the sky color is likely unusual such as green, yellow, or dark gray. Please stay safe and follow instructions from local authorities."
        break;
    }

    // Adding AI model response containing chosen functions to chat history as it's required by the models to preserve the context.
    chatHistory.Add(result); 

    // Check if the AI model has chosen any function for invocation.
    IEnumerable<FunctionCallContent> functionCalls = FunctionCallContent.GetFunctionCalls(result);
    if (!functionCalls.Any())
    {
        break;
    }

    // Sequentially iterating over each chosen function, invoke it, and add the result to the chat history.
    foreach (FunctionCallContent functionCall in functionCalls)
    {
        try
        {
            // Invoking the function
            FunctionResultContent resultContent = await functionCall.InvokeAsync(kernel);

            // Adding the function result to the chat history
            chatHistory.Add(resultContent.ToChatMessage());
        }
        catch (Exception ex)
        {
            // Adding function exception to the chat history.
            chatHistory.Add(new FunctionResultContent(functionCall, ex).ToChatMessage());
            // or
            //chatHistory.Add(new FunctionResultContent(functionCall, "Error details that the AI model can reason about.").ToChatMessage());
        }
    }
}

Nota

Le classi FunctionCallContent e FunctionResultContent vengono usate rispettivamente per rappresentare le chiamate di funzione del modello di intelligenza artificiale e i risultati della chiamata della funzione semantica del kernel. Contengono informazioni sulla funzione scelta, ad esempio l'ID funzione, il nome e gli argomenti e i risultati della chiamata di funzione, ad esempio l'ID della chiamata di funzione e il risultato.

Presto disponibile

Altre informazioni saranno presto disponibili.

Presto disponibile

Altre informazioni saranno presto disponibili.