Mode Pemanggilan Fungsi

Ketika model AI menerima perintah yang berisi daftar fungsi, model AI dapat memilih satu atau beberapa fungsi untuk pemanggilan untuk menyelesaikan perintah. Ketika fungsi dipilih oleh model, fungsi perlu dipanggil oleh Kernel Semantik.

Fungsi memanggil subsistem dalam Kernel Semantik memiliki dua mode pemanggilan fungsi: otomatis dan manual.

Bergantung pada mode pemanggilan, Kernel Semantik либо menangani pemanggilan fungsi secara menyeluruh atau memberikan kendali kepada pemanggil atas proses pemanggilan fungsi.

Pemanggilan Fungsi Otomatis

Pemanggilan fungsi otomatis adalah mode default subsistem panggilan fungsi Kernel Semantik. Ketika model AI memilih satu atau beberapa fungsi, Kernel Semantik secara otomatis memanggil fungsi yang dipilih. Hasil pemanggilan fungsi ini ditambahkan ke riwayat obrolan dan dikirim ke model secara otomatis dalam permintaan berikutnya. Model kemudian beralasan tentang riwayat obrolan, memilih fungsi tambahan jika diperlukan, atau menghasilkan respons akhir. Pendekatan ini sepenuhnya otomatis dan tidak memerlukan intervensi manual dari pemanggil.

Tip

Pemanggilan fungsi otomatis berbeda dari perilaku pilihan fungsi otomatis. Yang pertama menentukan apakah fungsi harus dipanggil secara otomatis oleh Kernel Semantik, sementara yang terakhir menentukan apakah fungsi harus dipilih secara otomatis oleh model AI.

Contoh ini menunjukkan cara menggunakan pemanggilan fungsi otomatis di Kernel Semantik. Model AI memutuskan fungsi mana yang akan dipanggil untuk menyelesaikan perintah dan Kernel Semantik melakukan sisanya dan memanggilnya secara otomatis.

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

from semantic_kernel.connectors.ai.function_choice_behavior import FunctionChoiceBehavior
from semantic_kernel.connectors.ai.open_ai import OpenAIChatCompletion
from semantic_kernel.connectors.ai.prompt_execution_settings import PromptExecutionSettings
from semantic_kernel.functions.kernel_arguments import KernelArguments
from semantic_kernel.kernel import Kernel

kernel = Kernel()
kernel.add_service(OpenAIChatCompletion())

# Assuming that WeatherPlugin and DateTimePlugin are already implemented
kernel.add_plugin(WeatherPlugin(), "WeatherPlugin")
kernel.add_plugin(DateTimePlugin(), "DateTimePlugin")

query = "What is the weather in Seattle today?"
arguments = KernelArguments(
    settings=PromptExecutionSettings(
        # 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:
        # function_choice_behavior=FunctionChoiceBehavior.Auto(auto_invoke=True),
        function_choice_behavior=FunctionChoiceBehavior.Auto(),
    )
)

response = await kernel.invoke_prompt(query, arguments=arguments)

Tip

Pembaruan lainnya akan segera hadir di SDK Java.

Beberapa model AI mendukung panggilan fungsi paralel, di mana model memilih beberapa fungsi untuk pemanggilan. Ini dapat berguna dalam kasus ketika memanggil fungsi yang dipilih membutuhkan waktu lama. Misalnya, AI dapat memilih untuk mengambil berita terbaru dan waktu saat ini secara bersamaan, daripada melakukan perjalanan pulang pergi per fungsi.

Kernel Semantik dapat memanggil fungsi-fungsi ini dengan dua cara berbeda:

  • Secara berurutan: Fungsi dipanggil satu demi satu. Ini adalah perilaku default.
  • Secara bersamaan: Fungsi dipanggil secara bersamaan. Ini dapat diaktifkan dengan mengatur FunctionChoiceBehaviorOptions.AllowConcurrentInvocation properti ke true, seperti yang ditunjukkan pada contoh di bawah ini.
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));

Terkadang, model dapat memilih beberapa fungsi untuk dipanggil. Ini sering disebut sebagai panggilan fungsi paralel . Ketika beberapa fungsi dipilih oleh model AI, Kernel Semantik akan memanggilnya secara bersamaan.

Tip

Dengan konektor OpenAI atau Azure OpenAI, Anda dapat menonaktifkan panggilan fungsi paralel dengan melakukan hal berikut:

from semantic_kernel.connectors.ai.open_ai import OpenAIChatPromptExecutionSettings
from semantic_kernel.connectors.ai.function_choice_behavior import FunctionChoiceBehavior

settings = OpenAIChatPromptExecutionSettings(
    function_choice_behavior=FunctionChoiceBehavior.Auto(),
    parallel_tool_calls=False
)

Pemanggilan Fungsi Manual

Dalam kasus ketika penelepon ingin memiliki lebih banyak kontrol atas proses pemanggilan fungsi, pemanggilan fungsi manual dapat digunakan.

Ketika pemanggilan fungsi manual diaktifkan, Kernel Semantik tidak secara otomatis memanggil fungsi yang dipilih oleh model AI. Sebaliknya, ia mengembalikan daftar fungsi yang dipilih ke pemanggil, yang kemudian dapat memutuskan fungsi mana yang akan dipanggil, memanggilnya secara berurutan atau paralel, menangani pengecualian, dan sebagainya. Hasil pemanggilan fungsi perlu ditambahkan ke riwayat obrolan dan dikembalikan ke model, yang akan beralasan tentang mereka dan memutuskan apakah akan memilih fungsi tambahan atau menghasilkan respons akhir.

Contoh di bawah ini menunjukkan cara menggunakan pemanggilan fungsi manual.

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

Catatan

Kelas FunctionCallContent dan FunctionResultContent digunakan untuk mewakili panggilan fungsi model AI dan hasil pemanggilan fungsi Kernel Semantik. Mereka berisi informasi tentang fungsi yang dipilih, seperti ID fungsi, nama, dan argumen, dan hasil pemanggilan fungsi, seperti ID panggilan fungsi dan hasil.

Contoh berikut menunjukkan cara menggunakan pemanggilan fungsi manual dengan API penyelesaian obrolan streaming. Perhatikan penggunaan kelas FunctionCallContentBuilder untuk menyusun panggilan fungsi dari konten streaming. Karena sifat streaming API, panggilan fungsi juga dialirkan. Ini berarti bahwa pemanggil harus menyusun pemanggilan fungsi dari konten streaming sebelum mengeksekusinya.

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)
{
    AuthorRole? authorRole = null;
    FunctionCallContentBuilder fccBuilder = new ();

    // Start or continue streaming chat based on the chat history
    await foreach (StreamingChatMessageContent streamingContent in chatCompletionService.GetStreamingChatMessageContentsAsync(chatHistory, settings, kernel))
    {
        // Check if the AI model has generated a response.
        if (streamingContent.Content is not null)
        {
            Console.Write(streamingContent.Content);
            // Sample streamed output: "The color of the sky in Boston is likely to be gray due to the rainy weather."
        }
        authorRole ??= streamingContent.Role;

        // Collect function calls details from the streaming content
        fccBuilder.Append(streamingContent);
    }

    // Build the function calls from the streaming content and quit the chat loop if no function calls are found
    IReadOnlyList<FunctionCallContent> functionCalls = fccBuilder.Build();
    if (!functionCalls.Any())
    {
        break;
    }

    // Creating and adding chat message content to preserve the original function calls in the chat history.
    // The function calls are added to the chat message a few lines below.
    ChatMessageContent fcContent = new ChatMessageContent(role: authorRole ?? default, content: null);
    chatHistory.Add(fcContent);

    // Iterating over the requested function calls and invoking them.
    // The code can easily be modified to invoke functions concurrently if needed.
    foreach (FunctionCallContent functionCall in functionCalls)
    {
        // Adding the original function call to the chat message content
        fcContent.Items.Add(functionCall);

        // Invoking the function
        FunctionResultContent functionResult = await functionCall.InvokeAsync(kernel);

        // Adding the function result to the chat history
        chatHistory.Add(functionResult.ToChatMessage());
    }
}

from semantic_kernel.connectors.ai.function_choice_behavior import FunctionChoiceBehavior
from semantic_kernel.connectors.ai.open_ai import OpenAIChatCompletion
from semantic_kernel.connectors.ai.prompt_execution_settings import PromptExecutionSettings
from semantic_kernel.contents.chat_history import ChatHistory
from semantic_kernel.contents.function_call_content import FunctionCallContent
from semantic_kernel.contents.function_result_content import FunctionResultContent
from semantic_kernel.kernel import Kernel

kernel = Kernel()
chat_completion_service = OpenAIChatCompletion()

# Assuming that WeatherPlugin is already implemented
kernel.add_plugin(WeatherPlugin(), "WeatherPlugin")

settings = PromptExecutionSettings(
    function_choice_behavior=FunctionChoiceBehavior.Auto(auto_invoke=False),
)

chat_history = ChatHistory()
chat_history.add_user_message("What is the weather in Seattle on 10th of September 2024 at 11:29 AM?")

response = await chat_completion_service.get_chat_message_content(chat_history, settings, kernel=kernel)
function_call_content = response.items[0]
assert isinstance(function_call_content, FunctionCallContent)

# Need to add the response to the chat history to preserve the context
chat_history.add_message(response)

function = kernel.get_function(function_call_content.plugin_name, function_call_content.function_name)
function_result = await function(kernel, function_call_content.to_kernel_arguments())

function_result_content = FunctionResultContent.from_function_call_content_and_result(
    function_call_content, function_result
)

# Adding the function result to the chat history
chat_history.add_message(function_result_content.to_chat_message_content())

# Invoke the model again with the function result
response = await chat_completion_service.get_chat_message_content(chat_history, settings, kernel=kernel)
print(response)
# The weather in Seattle on September 10th, 2024, is expected to be [weather condition].

Catatan

Kelas FunctionCallContent dan FunctionResultContent digunakan untuk mewakili panggilan fungsi model AI dan hasil pemanggilan fungsi Kernel Semantik. Mereka berisi informasi tentang fungsi yang dipilih, seperti ID fungsi, nama, dan argumen, dan hasil pemanggilan fungsi, seperti ID panggilan fungsi dan hasil.

Tip

Pembaruan lainnya akan segera hadir di SDK Java.

  • Last updated on