Skip to content

Commit d014534

Browse files
.Net: Parallel function calls option (#9487)
### Motivation and Context This PR adds the `FunctionChoiceBehaviorOptions.AllowParallelCalls` option and updates {Azure} OpenAI AI connectors to support it. This option instructs the AI model to generate multiple function calls in a single response when set to true. _"This is especially useful if executing the given functions takes a long time. For example, the model may call functions to get the weather in three different locations at the same time, which will result in a message with three function calls in the tool_calls array."_ **Source** - [Configuring parallel function calling](https://platform.openai.com/docs/guides/function-calling/configuring-parallel-function-calling) Closes: #6636
1 parent 44b6762 commit d014534

10 files changed

Lines changed: 382 additions & 2 deletions

File tree

‎dotnet/samples/Concepts/FunctionCalling/FunctionCalling.cs‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,19 @@ namespace FunctionCalling;
4646
/// * The <see cref="FunctionChoiceBehaviorOptions.AllowConcurrentInvocation"/> option enables concurrent invocation of functions by SK.
4747
/// By default, this option is set to false, meaning that functions are invoked sequentially. Concurrent invocation is only possible if the AI model can
4848
/// call or select multiple functions for invocation in a single request; otherwise, there is no distinction between sequential and concurrent invocation.
49+
/// * The <see cref="FunctionChoiceBehaviorOptions.AllowParallelCalls"/> option instructs the AI model to call multiple functions in one request if the model supports parallel function calls.
50+
/// By default, this option is set to null, meaning that the AI model default value will be used.
4951
///
52+
/// The following table summarizes the effects of different combinations of these options:
53+
///
54+
/// | AllowParallelCalls | AllowConcurrentInvocation | AI function call requests | Concurrent Invocation |
55+
/// |---------------------|---------------------------|--------------------------------|-----------------------|
56+
/// | false | false | one request per call | false |
57+
/// | false | true | one request per call | false* |
58+
/// | true | false | one request per multiple calls | false |
59+
/// | true | true | one request per multiple calls | true |
60+
///
61+
/// `*` There's only one function to call
5062
/// </summary>
5163
public class FunctionCalling(ITestOutputHelper output) : BaseTest(output)
5264
{
@@ -458,6 +470,61 @@ public async Task RunNonStreamingChatCompletionApiWithConcurrentFunctionInvocati
458470
// Expected output: Good morning! The current UTC time is 07:47 on October 22, 2024. Here are the latest news headlines: 1. Squirrel Steals Show - Discover the unexpected star of a recent event. 2. Dog Wins Lottery - Unbelievably, a lucky canine has hit the jackpot.
459471
}
460472

473+
[Fact]
474+
/// <summary>
475+
/// This example demonstrates usage of the non-streaming chat completion API with <see cref="FunctionChoiceBehavior.Auto"/> that
476+
/// advertises all kernel functions to the AI model and instructs the model to call multiple functions in parallel.
477+
/// </summary>
478+
public async Task RunNonStreamingChatCompletionApiWithParallelFunctionCallOptionAsync()
479+
{
480+
Kernel kernel = CreateKernel();
481+
482+
// The `AllowParallelCalls` option instructs the AI model to call multiple functions in parallel if the model supports parallel function calls.
483+
FunctionChoiceBehaviorOptions options = new() { AllowParallelCalls = true };
484+
485+
OpenAIPromptExecutionSettings settings = new() { FunctionChoiceBehavior = FunctionChoiceBehavior.Auto(options: options) };
486+
487+
IChatCompletionService chatCompletionService = kernel.GetRequiredService<IChatCompletionService>();
488+
489+
ChatMessageContent result = await chatCompletionService.GetChatMessageContentAsync(
490+
"Good morning! What’s the current time and latest news headlines?",
491+
settings,
492+
kernel);
493+
494+
// Assert
495+
Console.WriteLine(result);
496+
497+
// Expected output: Good morning! The current UTC time is 07:47 on October 22, 2024. Here are the latest news headlines: 1. Squirrel Steals Show - Discover the unexpected star of a recent event. 2. Dog Wins Lottery - Unbelievably, a lucky canine has hit the jackpot.
498+
}
499+
500+
[Fact]
501+
/// <summary>
502+
/// This example demonstrates usage of the non-streaming chat completion API with <see cref="FunctionChoiceBehavior.Auto"/> that
503+
/// advertises all kernel functions to the AI model, instructs the model to call multiple functions in parallel, and invokes them concurrently.
504+
/// </summary>
505+
public async Task RunNonStreamingChatCompletionApiWithParallelFunctionCallAndConcurrentFunctionInvocationOptionsAsync()
506+
{
507+
Kernel kernel = CreateKernel();
508+
509+
// The `AllowParallelCalls` option instructs the AI model to call multiple functions in parallel if the model supports parallel function calls.
510+
// The `AllowConcurrentInvocation` option enables concurrent invocation of the functions.
511+
FunctionChoiceBehaviorOptions options = new() { AllowParallelCalls = true, AllowConcurrentInvocation = true };
512+
513+
OpenAIPromptExecutionSettings settings = new() { FunctionChoiceBehavior = FunctionChoiceBehavior.Auto(options: options) };
514+
515+
IChatCompletionService chatCompletionService = kernel.GetRequiredService<IChatCompletionService>();
516+
517+
ChatMessageContent result = await chatCompletionService.GetChatMessageContentAsync(
518+
"Good morning! What’s the current time and latest news headlines?",
519+
settings,
520+
kernel);
521+
522+
// Assert
523+
Console.WriteLine(result);
524+
525+
// Expected output: Good morning! The current UTC time is 07:47 on October 22, 2024. Here are the latest news headlines: 1. Squirrel Steals Show - Discover the unexpected star of a recent event. 2. Dog Wins Lottery - Unbelievably, a lucky canine has hit the jackpot.
526+
}
527+
461528
private static Kernel CreateKernel()
462529
{
463530
// Create kernel

‎dotnet/src/Connectors/Connectors.AzureOpenAI.UnitTests/Services/AzureOpenAIChatCompletionServiceTests.cs‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1342,6 +1342,61 @@ public async Task ItCreatesCorrectFunctionToolCallsWhenUsingRequiredFunctionChoi
13421342
Assert.Equal("required", optionsJson.GetProperty("tool_choice").ToString());
13431343
}
13441344

1345+
[Theory]
1346+
[InlineData("auto", true)]
1347+
[InlineData("auto", false)]
1348+
[InlineData("auto", null)]
1349+
[InlineData("required", true)]
1350+
[InlineData("required", false)]
1351+
[InlineData("required", null)]
1352+
public async Task ItPassesAllowParallelCallsOptionToLLMAsync(string choice, bool? optionValue)
1353+
{
1354+
// Arrange
1355+
var kernel = new Kernel();
1356+
kernel.Plugins.AddFromFunctions("TimePlugin", [
1357+
KernelFunctionFactory.CreateFromMethod(() => { }, "Date"),
1358+
KernelFunctionFactory.CreateFromMethod(() => { }, "Now")
1359+
]);
1360+
1361+
var sut = new AzureOpenAIChatCompletionService("deployment", "https://endpoint", "api-key", "model-id", this._httpClient);
1362+
1363+
using var responseMessage = new HttpResponseMessage(HttpStatusCode.OK)
1364+
{
1365+
Content = new StringContent(AzureOpenAITestHelper.GetTestResponse("chat_completion_test_response.json"))
1366+
};
1367+
this._messageHandlerStub.ResponsesToReturn.Add(responseMessage);
1368+
1369+
var chatHistory = new ChatHistory();
1370+
chatHistory.AddUserMessage("Fake prompt");
1371+
1372+
var functionChoiceBehaviorOptions = new FunctionChoiceBehaviorOptions() { AllowParallelCalls = optionValue };
1373+
1374+
var executionSettings = new OpenAIPromptExecutionSettings()
1375+
{
1376+
FunctionChoiceBehavior = choice switch
1377+
{
1378+
"auto" => FunctionChoiceBehavior.Auto(options: functionChoiceBehaviorOptions),
1379+
"required" => FunctionChoiceBehavior.Required(options: functionChoiceBehaviorOptions),
1380+
_ => throw new ArgumentException("Invalid choice", nameof(choice))
1381+
}
1382+
};
1383+
1384+
// Act
1385+
await sut.GetChatMessageContentsAsync(chatHistory, executionSettings, kernel);
1386+
1387+
// Assert
1388+
var optionsJson = JsonSerializer.Deserialize<JsonElement>(Encoding.UTF8.GetString(this._messageHandlerStub.RequestContents[0]!));
1389+
1390+
if (optionValue is null)
1391+
{
1392+
Assert.False(optionsJson.TryGetProperty("parallel_tool_calls", out _));
1393+
}
1394+
else
1395+
{
1396+
Assert.Equal(optionValue, optionsJson.GetProperty("parallel_tool_calls").GetBoolean());
1397+
}
1398+
}
1399+
13451400
[Fact]
13461401
public async Task ItDoesNotChangeDefaultsForToolsAndChoiceIfNeitherOfFunctionCallingConfigurationsSetAsync()
13471402
{

‎dotnet/src/Connectors/Connectors.AzureOpenAI/Core/AzureClientCore.ChatCompletion.cs‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -90,6 +90,11 @@ protected override ChatCompletionOptions CreateChatCompletionOptions(
9090
}
9191
}
9292

93+
if (toolCallingConfig.Options?.AllowParallelCalls is not null)
94+
{
95+
options.AllowParallelToolCalls = toolCallingConfig.Options.AllowParallelCalls;
96+
}
97+
9398
return options;
9499
}
95100
}

‎dotnet/src/Connectors/Connectors.OpenAI.UnitTests/Services/OpenAIChatCompletionServiceTests.cs‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1371,6 +1371,58 @@ public async Task ItCreatesCorrectFunctionToolCallsWhenUsingRequiredFunctionChoi
13711371
Assert.Equal("required", optionsJson.GetProperty("tool_choice").ToString());
13721372
}
13731373

1374+
[Theory]
1375+
[InlineData("auto", true)]
1376+
[InlineData("auto", false)]
1377+
[InlineData("auto", null)]
1378+
[InlineData("required", true)]
1379+
[InlineData("required", false)]
1380+
[InlineData("required", null)]
1381+
public async Task ItPassesAllowParallelCallsOptionToLLMAsync(string choice, bool? optionValue)
1382+
{
1383+
// Arrange
1384+
var kernel = new Kernel();
1385+
kernel.Plugins.AddFromFunctions("TimePlugin", [
1386+
KernelFunctionFactory.CreateFromMethod(() => { }, "Date"),
1387+
KernelFunctionFactory.CreateFromMethod(() => { }, "Now")
1388+
]);
1389+
1390+
var chatCompletion = new OpenAIChatCompletionService(modelId: "gpt-3.5-turbo", apiKey: "NOKEY", httpClient: this._httpClient);
1391+
1392+
using var response = new HttpResponseMessage(HttpStatusCode.OK) { Content = new StringContent(File.ReadAllText("TestData/chat_completion_test_response.json")) };
1393+
this._messageHandlerStub.ResponseQueue.Enqueue(response);
1394+
1395+
var chatHistory = new ChatHistory();
1396+
chatHistory.AddUserMessage("Fake prompt");
1397+
1398+
var functionChoiceBehaviorOptions = new FunctionChoiceBehaviorOptions() { AllowParallelCalls = optionValue };
1399+
1400+
var executionSettings = new OpenAIPromptExecutionSettings()
1401+
{
1402+
FunctionChoiceBehavior = choice switch
1403+
{
1404+
"auto" => FunctionChoiceBehavior.Auto(options: functionChoiceBehaviorOptions),
1405+
"required" => FunctionChoiceBehavior.Required(options: functionChoiceBehaviorOptions),
1406+
_ => throw new ArgumentException("Invalid choice", nameof(choice))
1407+
}
1408+
};
1409+
1410+
// Act
1411+
await chatCompletion.GetChatMessageContentsAsync(chatHistory, executionSettings, kernel);
1412+
1413+
// Assert
1414+
var optionsJson = JsonSerializer.Deserialize<JsonElement>(Encoding.UTF8.GetString(this._messageHandlerStub.RequestContent!));
1415+
1416+
if (optionValue is null)
1417+
{
1418+
Assert.False(optionsJson.TryGetProperty("parallel_tool_calls", out _));
1419+
}
1420+
else
1421+
{
1422+
Assert.Equal(optionValue, optionsJson.GetProperty("parallel_tool_calls").GetBoolean());
1423+
}
1424+
}
1425+
13741426
[Fact]
13751427
public async Task ItDoesNotChangeDefaultsForToolsAndChoiceIfNeitherOfFunctionCallingConfigurationsSetAsync()
13761428
{

‎dotnet/src/Connectors/Connectors.OpenAI/Core/ClientCore.ChatCompletion.cs‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -468,7 +468,7 @@ protected virtual ChatCompletionOptions CreateChatCompletionOptions(
468468
#pragma warning restore OPENAI001 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
469469
EndUserId = executionSettings.User,
470470
TopLogProbabilityCount = executionSettings.TopLogprobs,
471-
IncludeLogProbabilities = executionSettings.Logprobs,
471+
IncludeLogProbabilities = executionSettings.Logprobs
472472
};
473473

474474
var responseFormat = GetResponseFormat(executionSettings);
@@ -503,6 +503,11 @@ protected virtual ChatCompletionOptions CreateChatCompletionOptions(
503503
}
504504
}
505505

506+
if (toolCallingConfig.Options?.AllowParallelCalls is not null)
507+
{
508+
options.AllowParallelToolCalls = toolCallingConfig.Options.AllowParallelCalls;
509+
}
510+
506511
return options;
507512
}
508513

‎dotnet/src/Functions/Functions.UnitTests/Yaml/PromptExecutionSettingsTypeConverterTests.cs‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -294,6 +294,50 @@ public void ItShouldDeserializedNoneFunctionChoiceBehaviorFromYamlWithSpecifiedF
294294
Assert.Contains(config.Functions, f => f.PluginName == "MyPlugin" && f.Name == "Function3");
295295
}
296296

297+
[Fact]
298+
public void ItShouldDeserializeAutoFunctionChoiceBehaviorFromJsonWithOptions()
299+
{
300+
// Arrange
301+
var yaml = """
302+
function_choice_behavior:
303+
type: auto
304+
options:
305+
allow_parallel_calls: true
306+
allow_concurrent_invocation: true
307+
""";
308+
309+
var executionSettings = this._deserializer.Deserialize<PromptExecutionSettings>(yaml);
310+
311+
// Act
312+
var config = executionSettings!.FunctionChoiceBehavior!.GetConfiguration(new(chatHistory: []) { Kernel = this._kernel });
313+
314+
// Assert
315+
Assert.True(config.Options.AllowParallelCalls);
316+
Assert.True(config.Options.AllowConcurrentInvocation);
317+
}
318+
319+
[Fact]
320+
public void ItShouldDeserializeRequiredFunctionChoiceBehaviorFromJsonWithOptions()
321+
{
322+
// Arrange
323+
var yaml = """
324+
function_choice_behavior:
325+
type: required
326+
options:
327+
allow_parallel_calls: true
328+
allow_concurrent_invocation: true
329+
""";
330+
331+
var executionSettings = this._deserializer.Deserialize<PromptExecutionSettings>(yaml);
332+
333+
// Act
334+
var config = executionSettings!.FunctionChoiceBehavior!.GetConfiguration(new(chatHistory: []) { Kernel = this._kernel });
335+
336+
// Assert
337+
Assert.True(config.Options.AllowParallelCalls);
338+
Assert.True(config.Options.AllowConcurrentInvocation);
339+
}
340+
297341
private readonly string _yaml = """
298342
template_format: semantic-kernel
299343
template: Say hello world to {{$name}} in {{$language}}

‎dotnet/src/IntegrationTests/Connectors/AzureOpenAI/AzureOpenAIChatCompletion_AutoFunctionChoiceBehaviorTests.cs‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -350,6 +350,53 @@ public async Task SpecifiedInCodeInstructsConnectorToInvokeKernelFunctionsAutoma
350350
Assert.True(requestIndexLog.All((item) => item == 0)); // Assert that all functions called by the AI model were executed within the same initial request.
351351
}
352352

353+
[Theory]
354+
[InlineData(true)]
355+
[InlineData(false)]
356+
public async Task SpecifiedInCodeInstructsAIModelToCallFunctionInParallelOrSequentiallyAsync(bool callInParallel)
357+
{
358+
// Arrange
359+
var requestIndexLog = new ConcurrentBag<int>();
360+
361+
this._kernel.ImportPluginFromType<DateTimeUtils>();
362+
this._kernel.ImportPluginFromFunctions("WeatherUtils", [KernelFunctionFactory.CreateFromMethod(() => "Rainy day magic!", "GetCurrentWeather")]);
363+
364+
var invokedFunctions = new ConcurrentBag<string>();
365+
366+
this._autoFunctionInvocationFilter.RegisterFunctionInvocationHandler(async (context, next) =>
367+
{
368+
requestIndexLog.Add(context.RequestSequenceIndex);
369+
invokedFunctions.Add(context.Function.Name);
370+
371+
await next(context);
372+
});
373+
374+
var settings = new AzureOpenAIPromptExecutionSettings() { FunctionChoiceBehavior = FunctionChoiceBehavior.Auto(options: new() { AllowParallelCalls = callInParallel }) };
375+
376+
var chatHistory = new ChatHistory();
377+
chatHistory.AddUserMessage("Give me today's date and weather.");
378+
379+
// Act
380+
var result = await this._chatCompletionService.GetChatMessageContentAsync(chatHistory, settings, this._kernel);
381+
382+
// Assert
383+
Assert.NotNull(result);
384+
385+
Assert.Contains("GetCurrentDate", invokedFunctions);
386+
Assert.Contains("GetCurrentWeather", invokedFunctions);
387+
388+
if (callInParallel)
389+
{
390+
// Assert that all functions are called within the same initial request.
391+
Assert.True(requestIndexLog.All((item) => item == 0));
392+
}
393+
else
394+
{
395+
// Assert that all functions are called in separate requests.
396+
Assert.Equal([0, 1], requestIndexLog);
397+
}
398+
}
399+
353400
private Kernel InitializeKernel()
354401
{
355402
var azureOpenAIConfiguration = this._configuration.GetSection("AzureOpenAI").Get<AzureOpenAIConfiguration>();

‎dotnet/src/IntegrationTests/Connectors/OpenAI/OpenAIChatCompletion_AutoFunctionChoiceBehaviorTests.cs‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -347,6 +347,53 @@ public async Task SpecifiedInCodeInstructsConnectorToInvokeKernelFunctionsAutoma
347347
Assert.True(requestIndexLog.All((item) => item == 0)); // Assert that all functions called by the AI model were executed within the same initial request.
348348
}
349349

350+
[Theory]
351+
[InlineData(true)]
352+
[InlineData(false)]
353+
public async Task SpecifiedInCodeInstructsAIModelToCallFunctionInParallelOrSequentiallyAsync(bool callInParallel)
354+
{
355+
// Arrange
356+
var requestIndexLog = new ConcurrentBag<int>();
357+
358+
this._kernel.ImportPluginFromType<DateTimeUtils>();
359+
this._kernel.ImportPluginFromFunctions("WeatherUtils", [KernelFunctionFactory.CreateFromMethod(() => "Rainy day magic!", "GetCurrentWeather")]);
360+
361+
var invokedFunctions = new ConcurrentBag<string>();
362+
363+
this._autoFunctionInvocationFilter.RegisterFunctionInvocationHandler(async (context, next) =>
364+
{
365+
requestIndexLog.Add(context.RequestSequenceIndex);
366+
invokedFunctions.Add(context.Function.Name);
367+
368+
await next(context);
369+
});
370+
371+
var settings = new OpenAIPromptExecutionSettings() { FunctionChoiceBehavior = FunctionChoiceBehavior.Auto(options: new() { AllowParallelCalls = callInParallel }) };
372+
373+
var chatHistory = new ChatHistory();
374+
chatHistory.AddUserMessage("Give me today's date and weather.");
375+
376+
// Act
377+
var result = await this._chatCompletionService.GetChatMessageContentAsync(chatHistory, settings, this._kernel);
378+
379+
// Assert
380+
Assert.NotNull(result);
381+
382+
Assert.Contains("GetCurrentDate", invokedFunctions);
383+
Assert.Contains("GetCurrentWeather", invokedFunctions);
384+
385+
if (callInParallel)
386+
{
387+
// Assert that all functions are called within the same initial request.
388+
Assert.True(requestIndexLog.All((item) => item == 0));
389+
}
390+
else
391+
{
392+
// Assert that all functions are called in separate requests.
393+
Assert.Equal([0, 1], requestIndexLog);
394+
}
395+
}
396+
350397
private Kernel InitializeKernel()
351398
{
352399
var openAIConfiguration = this._configuration.GetSection("OpenAI").Get<OpenAIConfiguration>();

0 commit comments

Comments
 (0)