Skip to content

Latest commit

 

History

History
217 lines (154 loc) · 11.5 KB

README.md

File metadata and controls

217 lines (154 loc) · 11.5 KB
Raw

Azure OpenAI client library for .NET

Azure OpenAI is a managed service that allows developers to deploy, tune, and generate content from OpenAI models on Azure resouces.

Use the client library for Azure OpenAI to:

Getting started

Install the package

Install the client library for .NET with NuGet:

dotnet add package Azure.AI.OpenAI --prerelease

Prerequisites

You must have an Azure subscription and OpenAI access.

Authenticate the client

In order to interact with the Azure OpenAI service, you'll need to create an instance of the OpenAIClient class. To make this possible, you'll need the endpoint URI for your Azure OpenAI resource and an API key to access that resource.

Get credentials

You can obtain the endpoint string and subscription key from the Azure OpenAI Portal.

Create OpenAIClient

Once you have the value of the endpoint string and subscription key, you can create the OpenAIClient:

// Replace with your Azure OpenAI key
string key = "YOUR_AZURE_OPENAI_KEY";
string endpoint = "https://myaccount.openai.azure.com/";
OpenAIClient client = new OpenAIClient(new Uri(endpoint), new AzureKeyCredential(key));

Create OpenAIClient with 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/";
OpenAIClient 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 = new OpenAIClient(new Uri(endpoint), new DefaultAzureCredential());

CompletionsOptions completionsOptions = new CompletionsOptions()
{
    Prompt =
    {
        "What is Azure OpenAI?",
    }
};
completionsOptions.Prompt.Add(prompt);

Response<Completions> completionsResponse = client.GetCompletions("myModelDeployment", completionsOptions);
string completion = completionsResponse.Value.Choices[0].Text;
Console.WriteLine($"Chatbot: {completion}");

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/";
OpenAIClient client = new OpenAIClient(new Uri(endpoint), new DefaultAzureCredential());

string prompt = "What is Azure OpenAI?";
Console.Write($"Input: {prompt}");

Response<Completions> completionsResponse = client.GetCompletions("myDeploymentId", 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/";
OpenAIClient 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.",
};

foreach (string prompt in examplePrompts)
{
    Console.Write($"Input: {prompt}");
    CompletionsOptions completionsOptions = new CompletionsOptions();
    completionsOptions.Prompt.Add(prompt);

    Response<Completions> completionsResponse = client.GetCompletions("myModelDeployment", 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/";
OpenAIClient 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}");
CompletionsOptions completionsOptions = new CompletionsOptions();
completionsOptions.Prompt.Add(summarizationPrompt);

Response<Completions> completionsResponse = client.GetCompletions("myModelDeployment", completionsOptions);
string completion = completionsResponse.Value.Choices[0].Text;
Console.WriteLine($"Summarization: {completion}");

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.

Impressions