Azure.AI.OpenAI
1.0.0-beta.8
Prefix Reserved
See the version list below for details.
dotnet add package Azure.AI.OpenAI --version 1.0.0-beta.8
NuGet\Install-Package Azure.AI.OpenAI -Version 1.0.0-beta.8
<PackageReference Include="Azure.AI.OpenAI" Version="1.0.0-beta.8" />
paket add Azure.AI.OpenAI --version 1.0.0-beta.8
#r "nuget: Azure.AI.OpenAI, 1.0.0-beta.8"
// Install Azure.AI.OpenAI as a Cake Addin #addin nuget:?package=Azure.AI.OpenAI&version=1.0.0-beta.8&prerelease // Install Azure.AI.OpenAI as a Cake Tool #tool nuget:?package=Azure.AI.OpenAI&version=1.0.0-beta.8&prerelease
Azure OpenAI client library for .NET
The Azure OpenAI client library for .NET is an adaptation of OpenAI's REST APIs that provides an idiomatic interface and rich integration with the rest of the Azure SDK ecosystem. It can connect to Azure OpenAI resources or to the non-Azure OpenAI inference endpoint, making it a great choice for even non-Azure OpenAI development.
Use the client library for Azure OpenAI to:
Azure OpenAI is a managed service that allows developers to deploy, tune, and generate content from OpenAI models on Azure resources.
Source code | Package (NuGet) | API reference documentation | Product documentation | Samples
Getting started
Prerequisites
If you'd like to use an Azure OpenAI resource, you must have an Azure subscription and Azure OpenAI access. This will allow you to create an Azure OpenAI resource and get both a connection URL as well as API keys. For more information, see Quickstart: Get started generating text using Azure OpenAI Service.
If you'd like to use the Azure OpenAI .NET client library to connect to non-Azure OpenAI, you'll need an API key from a developer account at https://platform.openai.com/.
Install the package
Install the client library for .NET with NuGet:
dotnet add package Azure.AI.OpenAI --prerelease
Authenticate the client
In order to interact with Azure OpenAI or OpenAI, you'll need to create an instance of the OpenAIClient class. To configure a client for use with Azure OpenAI, provide a valid endpoint URI to an Azure OpenAI resource along with a corresponding key credential, token credential, or Azure identity credential that's authorized to use the Azure OpenAI resource. To instead configure the client to connect to OpenAI's service, provide an API key from OpenAI's developer portal.
OpenAIClient client = useAzureOpenAI
? new OpenAIClient(
new Uri("https://your-azure-openai-resource.com/"),
new AzureKeyCredential("your-azure-openai-resource-api-key"))
: new OpenAIClient("your-api-key-from-platform.openai.com");
Create OpenAIClient with an Azure Active Directory Credential
Client subscription key authentication is used in most of the examples in this getting started guide, but you can also authenticate with Azure Active Directory using the Azure Identity library. To use the DefaultAzureCredential provider shown below, or other credential providers provided with the Azure SDK, please install the Azure.Identity package:
dotnet add package Azure.Identity
string endpoint = "https://myaccount.openai.azure.com/";
var client = new OpenAIClient(new Uri(endpoint), new DefaultAzureCredential());
Key concepts
The main concept to understand is Completions. Briefly explained, completions provides its functionality in the form of a text prompt, which by using a specific model, will then attempt to match the context and patterns, providing an output text. The following code snippet provides a rough overview (more details can be found in the GenerateChatbotResponsesWithToken
sample code):
OpenAIClient client = useAzureOpenAI
? new OpenAIClient(
new Uri("https://your-azure-openai-resource.com/"),
new AzureKeyCredential("your-azure-openai-resource-api-key"))
: new OpenAIClient("your-api-key-from-platform.openai.com");
Response<Completions> response = await client.GetCompletionsAsync(
"text-davinci-003", // assumes a matching model deployment or model name
"Hello, world!");
foreach (Choice choice in response.Value.Choices)
{
Console.WriteLine(choice.Text);
}
Thread safety
We guarantee that all client instance methods are thread-safe and independent of each other (guideline). This ensures that the recommendation of reusing client instances is always safe, even across threads.
Additional concepts
Client options | Accessing the response | Long-running operations | Handling failures | Diagnostics | Mocking | Client lifetime
Examples
You can familiarize yourself with different APIs using Samples.
Generate Chatbot Response
The GenerateChatbotResponse
method authenticates using a DefaultAzureCredential, then generates text responses to input prompts.
string endpoint = "https://myaccount.openai.azure.com/";
var client = new OpenAIClient(new Uri(endpoint), new DefaultAzureCredential());
string deploymentName = "text-davinci-003";
string prompt = "What is Azure OpenAI?";
Console.Write($"Input: {prompt}");
Response<Completions> completionsResponse = client.GetCompletions(deploymentName, prompt);
string completion = completionsResponse.Value.Choices[0].Text;
Console.WriteLine($"Chatbot: {completion}");
Generate Multiple Chatbot Responses With Subscription Key
The GenerateMultipleChatbotResponsesWithSubscriptionKey
method gives an example of generating text responses to input prompts using an Azure subscription key
// Replace with your Azure OpenAI key
string key = "YOUR_AZURE_OPENAI_KEY";
string endpoint = "https://myaccount.openai.azure.com/";
var client = new OpenAIClient(new Uri(endpoint), new AzureKeyCredential(key));
List<string> examplePrompts = new(){
"How are you today?",
"What is Azure OpenAI?",
"Why do children love dinosaurs?",
"Generate a proof of Euler's identity",
"Describe in single words only the good things that come into your mind about your mother.",
};
string deploymentName = "text-davinci-003";
foreach (string prompt in examplePrompts)
{
Console.Write($"Input: {prompt}");
CompletionsOptions completionsOptions = new CompletionsOptions();
completionsOptions.Prompts.Add(prompt);
Response<Completions> completionsResponse = client.GetCompletions(deploymentName, completionsOptions);
string completion = completionsResponse.Value.Choices[0].Text;
Console.WriteLine($"Chatbot: {completion}");
}
Summarize Text with Completion
The SummarizeText
method generates a summarization of the given input prompt.
string endpoint = "https://myaccount.openai.azure.com/";
var client = new OpenAIClient(new Uri(endpoint), new DefaultAzureCredential());
string textToSummarize = @"
Two independent experiments reported their results this morning at CERN, Europe's high-energy physics laboratory near Geneva in Switzerland. Both show convincing evidence of a new boson particle weighing around 125 gigaelectronvolts, which so far fits predictions of the Higgs previously made by theoretical physicists.
""As a layman I would say: 'I think we have it'. Would you agree?"" Rolf-Dieter Heuer, CERN's director-general, asked the packed auditorium. The physicists assembled there burst into applause.
:";
string summarizationPrompt = @$"
Summarize the following text.
Text:
""""""
{textToSummarize}
""""""
Summary:
";
Console.Write($"Input: {summarizationPrompt}");
var completionsOptions = new CompletionsOptions()
{
Prompts = { summarizationPrompt },
};
string deploymentName = "text-davinci-003";
Response<Completions> completionsResponse = client.GetCompletions(deploymentName, completionsOptions);
string completion = completionsResponse.Value.Choices[0].Text;
Console.WriteLine($"Summarization: {completion}");
Stream Chat Messages with non-Azure OpenAI
string nonAzureOpenAIApiKey = "your-api-key-from-platform.openai.com";
var client = new OpenAIClient(nonAzureOpenAIApiKey, new OpenAIClientOptions());
var chatCompletionsOptions = new ChatCompletionsOptions()
{
Messages =
{
new ChatMessage(ChatRole.System, "You are a helpful assistant. You will talk like a pirate."),
new ChatMessage(ChatRole.User, "Can you help me?"),
new ChatMessage(ChatRole.Assistant, "Arrrr! Of course, me hearty! What can I do for ye?"),
new ChatMessage(ChatRole.User, "What's the best way to train a parrot?"),
}
};
Response<StreamingChatCompletions> response = await client.GetChatCompletionsStreamingAsync(
deploymentOrModelName: "gpt-3.5-turbo",
chatCompletionsOptions);
using StreamingChatCompletions streamingChatCompletions = response.Value;
await foreach (StreamingChatChoice choice in streamingChatCompletions.GetChoicesStreaming())
{
await foreach (ChatMessage message in choice.GetMessageStreaming())
{
Console.Write(message.Content);
}
Console.WriteLine();
}
Use Chat Functions
Chat Functions allow a caller of Chat Completions to define capabilities that the model can use to extend its functionality into external tools and data sources.
You can read more about Chat Functions on OpenAI's blog: https://openai.com/blog/function-calling-and-other-api-updates
NOTE: Chat Functions require model versions beginning with gpt-4 and gpt-3.5-turbo's -0613
labels. They are not
available with older versions of the models.
NOTE: The concurrent use of Chat Functions and Azure Chat Extensions on a single request is not yet supported. Supplying both will result in the Chat Functions information being ignored and the operation behaving as if only the Azure Chat Extensions were provided. To address this limitation, consider separating the evaluation of Chat Functions and Azure Chat Extensions across multiple requests in your solution design.
To use Chat Functions, you first define the function you'd like the model to be able to use when appropriate. Using the example from the linked blog post, above:
var getWeatherFuntionDefinition = new FunctionDefinition()
{
Name = "get_current_weather",
Description = "Get the current weather in a given location",
Parameters = BinaryData.FromObjectAsJson(
new
{
Type = "object",
Properties = new
{
Location = new
{
Type = "string",
Description = "The city and state, e.g. San Francisco, CA",
},
Unit = new
{
Type = "string",
Enum = new[] { "celsius", "fahrenheit" },
}
},
Required = new[] { "location" },
},
new JsonSerializerOptions() { PropertyNamingPolicy = JsonNamingPolicy.CamelCase }),
};
With the function defined, it can then be used in a Chat Completions request via its options. Function data is handled across multiple calls that build up data for subsequent stateless requests, so we maintain a list of chat messages as a form of conversation history.
var conversationMessages = new List<ChatMessage>()
{
new(ChatRole.User, "What is the weather like in Boston?"),
};
var chatCompletionsOptions = new ChatCompletionsOptions();
foreach (ChatMessage chatMessage in conversationMessages)
{
chatCompletionsOptions.Messages.Add(chatMessage);
}
chatCompletionsOptions.Functions.Add(getWeatherFuntionDefinition);
Response<ChatCompletions> response = await client.GetChatCompletionsAsync(
"gpt-35-turbo-0613",
chatCompletionsOptions);
If the model determines that it should call a Chat Function, a finish reason of 'FunctionCall' will be populated on
the choice and details will be present in the response message's FunctionCall
property. Usually, the name of the
function call will be one that was provided and the arguments will be a populated JSON document matching the schema
included in the FunctionDefinition
used; it is not guaranteed that this data is valid or even properly formatted,
however, so validation and error checking should always accompany function call processing.
To resolve the function call and continue the user-facing interaction, process the argument payload as needed and then
serialize appropriate response data into a new message with ChatRole.Function
. Then make a new request with all of
the messages so far -- the initial User
message, the first response's FunctionCall
message, and the resolving
Function
message generated in reply to the function call -- so the model can use the data to better formulate a chat
completions response.
Note that the function call response you provide does not need to follow any schema provided in the initial call. The model will infer usage of the response data based on inferred context of names and fields.
ChatChoice responseChoice = response.Value.Choices[0];
if (responseChoice.FinishReason == CompletionsFinishReason.FunctionCall)
{
// Include the FunctionCall message in the conversation history
conversationMessages.Add(responseChoice.Message);
if (responseChoice.Message.FunctionCall.Name == "get_current_weather")
{
// Validate and process the JSON arguments for the function call
string unvalidatedArguments = responseChoice.Message.FunctionCall.Arguments;
var functionResultData = (object)null; // GetYourFunctionResultData(unvalidatedArguments);
// Here, replacing with an example as if returned from GetYourFunctionResultData
functionResultData = new
{
Temperature = 31,
Unit = "celsius",
};
// Serialize the result data from the function into a new chat message with the 'Function' role,
// then add it to the messages after the first User message and initial response FunctionCall
var functionResponseMessage = new ChatMessage(
ChatRole.Function,
JsonSerializer.Serialize(
functionResultData,
new JsonSerializerOptions() { PropertyNamingPolicy = JsonNamingPolicy.CamelCase }))
{
Name = responseChoice.Message.FunctionCall.Name
};
conversationMessages.Add(functionResponseMessage);
// Now make a new request using all three messages in conversationMessages
}
}
Use your own data with Azure OpenAI
The use your own data feature is unique to Azure OpenAI and won't work with a client configured to use the non-Azure service. See the Azure OpenAI using your own data quickstart for conceptual background and detailed setup instructions.
NOTE: The concurrent use of Chat Functions and Azure Chat Extensions on a single request is not yet supported. Supplying both will result in the Chat Functions information being ignored and the operation behaving as if only the Azure Chat Extensions were provided. To address this limitation, consider separating the evaluation of Chat Functions and Azure Chat Extensions across multiple requests in your solution design.
var chatCompletionsOptions = new ChatCompletionsOptions()
{
Messages =
{
new ChatMessage(
ChatRole.System,
"You are a helpful assistant that answers questions about the Contoso product database."),
new ChatMessage(ChatRole.User, "What are the best-selling Contoso products this month?")
},
// The addition of AzureChatExtensionsOptions enables the use of Azure OpenAI capabilities that add to
// the behavior of Chat Completions, here the "using your own data" feature to supplement the context
// with information from an Azure Cognitive Search resource with documents that have been indexed.
AzureExtensionsOptions = new AzureChatExtensionsOptions()
{
Extensions =
{
new AzureCognitiveSearchChatExtensionConfiguration()
{
SearchEndpoint = new Uri("https://your-contoso-search-resource.search.windows.net"),
IndexName = "contoso-products-index",
SearchKey = new AzureKeyCredential("<your Cognitive Search resource API key>"),
}
}
}
};
Response<ChatCompletions> response = await client.GetChatCompletionsAsync(
"gpt-35-turbo-0613",
chatCompletionsOptions);
ChatMessage message = response.Value.Choices[0].Message;
// The final, data-informed response still appears in the ChatMessages as usual
Console.WriteLine($"{message.Role}: {message.Content}");
// Responses that used extensions will also have Context information that includes special Tool messages
// to explain extension activity and provide supplemental information like citations.
Console.WriteLine($"Citations and other information:");
foreach (ChatMessage contextMessage in message.AzureExtensionsContext.Messages)
{
// Note: citations and other extension payloads from the "tool" role are often encoded JSON documents
// and need to be parsed as such; that step is omitted here for brevity.
Console.WriteLine($"{contextMessage.Role}: {contextMessage.Content}");
}
Generate images with DALL-E image generation models
Response<ImageGenerations> imageGenerations = await client.GetImageGenerationsAsync(
new ImageGenerationOptions()
{
Prompt = "a happy monkey eating a banana, in watercolor",
Size = ImageSize.Size256x256,
});
// Image Generations responses provide URLs you can use to retrieve requested images
Uri imageUri = imageGenerations.Value.Data[0].Url;
Transcribe audio data with Whisper speech models
using Stream audioStreamFromFile = File.OpenRead("myAudioFile.mp3");
BinaryData audioFileData = BinaryData.FromStream(audioStreamFromFile);
var transcriptionOptions = new AudioTranscriptionOptions()
{
AudioData = BinaryData.FromStream(audioStreamFromFile),
ResponseFormat = AudioTranscriptionFormat.Verbose,
};
Response<AudioTranscription> transcriptionResponse = await client.GetAudioTranscriptionAsync(
deploymentId: "my-whisper-deployment", // whisper-1 as model name for non-Azure OpenAI
transcriptionOptions);
AudioTranscription transcription = transcriptionResponse.Value;
// When using Simple, SRT, or VTT formats, only transcription.Text will be populated
Console.WriteLine($"Transcription ({transcription.Duration.Value.TotalSeconds}s):");
Console.WriteLine(transcription.Text);
Translate audio data to English with Whisper speech models
using Stream audioStreamFromFile = File.OpenRead("mySpanishAudioFile.mp3");
BinaryData audioFileData = BinaryData.FromStream(audioStreamFromFile);
var translationOptions = new AudioTranslationOptions()
{
AudioData = BinaryData.FromStream(audioStreamFromFile),
ResponseFormat = AudioTranslationFormat.Verbose,
};
Response<AudioTranslation> translationResponse = await client.GetAudioTranslationAsync(
deploymentId: "my-whisper-deployment", // whisper-1 as model name for non-Azure OpenAI
translationOptions);
AudioTranslation translation = translationResponse.Value;
// When using Simple, SRT, or VTT formats, only translation.Text will be populated
Console.WriteLine($"Translation ({translation.Duration.Value.TotalSeconds}s):");
// .Text will be translated to English (ISO-639-1 "en")
Console.WriteLine(translation.Text);
Troubleshooting
When you interact with Azure OpenAI using the .NET SDK, errors returned by the service correspond to the same HTTP status codes returned for REST API requests.
For example, if you try to create a client using an endpoint that doesn't match your Azure OpenAI Resource endpoint, a 404
error is returned, indicating Resource Not Found
.
Next steps
- Provide a link to additional code examples, ideally to those sitting alongside the README in the package's
/samples
directory. - If appropriate, point users to other packages that might be useful.
- If you think there's a good chance that developers might stumble across your package in error (because they're searching for specific functionality and mistakenly think the package provides that functionality), point them to the packages they might be looking for.
Contributing
See the OpenAI CONTRIBUTING.md for details on building, testing, and contributing to this library.
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit cla.microsoft.com.
When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net5.0 was computed. net5.0-windows was computed. net6.0 was computed. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
.NET Core | netcoreapp2.0 was computed. netcoreapp2.1 was computed. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
.NET Standard | netstandard2.0 is compatible. netstandard2.1 was computed. |
.NET Framework | net461 was computed. net462 was computed. net463 was computed. net47 was computed. net471 was computed. net472 was computed. net48 was computed. net481 was computed. |
MonoAndroid | monoandroid was computed. |
MonoMac | monomac was computed. |
MonoTouch | monotouch was computed. |
Tizen | tizen40 was computed. tizen60 was computed. |
Xamarin.iOS | xamarinios was computed. |
Xamarin.Mac | xamarinmac was computed. |
Xamarin.TVOS | xamarintvos was computed. |
Xamarin.WatchOS | xamarinwatchos was computed. |
-
.NETStandard 2.0
- Azure.Core (>= 1.35.0)
- System.Text.Json (>= 4.7.2)
NuGet packages (78)
Showing the top 5 NuGet packages that depend on Azure.AI.OpenAI:
Package | Downloads |
---|---|
Omnia.Fx.Models
Package Description |
|
ImmediaC.SimpleCms
ASP.NET Core based CMS |
|
Microsoft.SemanticKernel.Connectors.AzureOpenAI
Semantic Kernel connectors for Azure OpenAI. Contains clients for chat completion, embedding and DALL-E text to image. |
|
Microsoft.Azure.Workflows.WebJobs.Extension
Extensions for running workflows in Azure Functions |
|
Rystem.PlayFramework
Rystem.PlayFramework helps you to use concepts like multi agent and openai. |
GitHub repositories (31)
Showing the top 5 popular GitHub repositories that depend on Azure.AI.OpenAI:
Repository | Stars |
---|---|
microsoft/PowerToys
Windows system utilities to maximize productivity
|
|
microsoft/semantic-kernel
Integrate cutting-edge LLM technology quickly and easily into your apps
|
|
Azure/azure-sdk-for-net
This repository is for active development of the Azure SDK for .NET. For consumers of the SDK we recommend visiting our public developer docs at https://learn.microsoft.com/dotnet/azure/ or our versioned developer docs at https://azure.github.io/azure-sdk-for-net.
|
|
dotnet/aspire
Tools, templates, and packages to accelerate building observable, production-ready apps
|
|
Azure-Samples/cognitive-services-speech-sdk
Sample code for the Microsoft Cognitive Services Speech SDK
|
Version | Downloads | Last updated |
---|---|---|
2.1.0-beta.2 | 56,842 | 11/5/2024 |
2.1.0-beta.1 | 240,029 | 10/2/2024 |
2.0.0 | 175,593 | 10/1/2024 |
2.0.0-beta.6 | 24,435 | 9/23/2024 |
2.0.0-beta.5 | 145,978 | 9/4/2024 |
2.0.0-beta.4 | 78,642 | 8/30/2024 |
2.0.0-beta.3 | 35,672 | 8/24/2024 |
2.0.0-beta.2 | 269,964 | 6/15/2024 |
2.0.0-beta.1 | 32,777 | 6/7/2024 |
1.0.0-beta.17 | 921,171 | 5/3/2024 |
1.0.0-beta.16 | 216,523 | 4/12/2024 |
1.0.0-beta.15 | 530,728 | 3/20/2024 |
1.0.0-beta.14 | 371,725 | 3/4/2024 |
1.0.0-beta.13 | 553,359 | 2/1/2024 |
1.0.0-beta.12 | 643,733 | 12/15/2023 |
1.0.0-beta.11 | 161,342 | 12/8/2023 |
1.0.0-beta.10 | 8,045 | 12/7/2023 |
1.0.0-beta.9 | 352,051 | 11/6/2023 |
1.0.0-beta.8 | 769,308 | 9/21/2023 |
1.0.0-beta.7 | 398,106 | 8/25/2023 |
1.0.0-beta.6 | 558,306 | 7/19/2023 |
1.0.0-beta.5 | 1,284,585 | 3/22/2023 |
1.0.0-beta.4 | 10,528 | 2/23/2023 |
1.0.0-beta.3 | 436 | 2/17/2023 |
1.0.0-beta.2 | 690 | 2/8/2023 |
1.0.0-beta.1 | 886 | 2/7/2023 |