関数の選択の動作

関数の選択動作は、開発者が構成できる構成のビットです。

1. AI モデルにアドバタイズされる関数。
2. モデルが呼び出しのためにそれらを選択する方法。
3. セマンティック カーネルがこれらの関数を呼び出す方法。

現在、関数の選択動作は、 FunctionChoiceBehavior クラスの 3 つの静的メソッドによって表されています。

• 自動: AI モデルが、指定された関数の 0 個以上から呼び出しを選択することを決定できるようにします。
• 必須: 提供された関数を選択するように AI モデルに強制します。
• なし: AI モデルに対して、関数を選択しないように指示します。

警告

関数呼び出し機能は試験段階であり、変更される可能性があります。 2024 年 11 月中旬までに一般公開 (GA) に達する予定です。 コードを最新の関数呼び出し機能に移行するには移行ガイドを参照してください。

Note

関数呼び出し機能は、これまでにいくつかの AI コネクタでのみサポートされています。詳細については、後述の「 サポートされている AI コネクタ 」セクションを参照してください。

関数のアドバタイズ

関数のアドバタイズは、さらに呼び出しと呼び出しのために AI モデルに関数を提供するプロセスです。 3 つの関数選択動作はすべて、 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関数の選択動作は、呼び出し用に指定された 0 個以上の関数から選択することを AI モデルに指示します。

この例では、 DateTimeUtils プラグインと WeatherForecastUtils プラグインのすべての関数が、プロンプトと共に AI モデルに提供されます。 この情報はGetWeatherForCity関数の入力として必要であるため、モデルは最初に呼び出しGetCurrentTime関数を選択して現在の日時を取得します。 次に、呼び出し 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動作により、モデルは呼び出し用に指定された関数を選択するように強制されます。 これは、AI モデルが独自の知識からではなく、指定された関数から必要な情報を取得する必要があるシナリオに役立ちます。

Note

この動作は、最初の要求の関数を 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 モデルに指示します。応答を生成するために呼び出し用に関数を選択する必要はありません。 これは、呼び出し元が実際に呼び出さずにモデルが選択する関数を確認したい場合に、ドライ ランに役立ちます。 また、AI モデルがユーザーからの質問から情報を抽出する場合にも役立ちます。たとえば、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	計画済み	❌
ミストラル	計画済み	✔️
Ollama	間もなく利用できます	❌
Onnx	間もなく利用できます	❌
OpenAI	✔️	✔️

間もなく利用できます

詳細については、近日公開予定です。

間もなく利用できます

詳細については、近日公開予定です。