Merge pull request #40205 from JakeRadMSFT/u/jakerad/add-sk-pivot

Add Semantic Kernel Pivot to Open AI Quick Starts
dotnet · Mar 26, 2024 · 0b0737d · 0b0737d
2 parents 71f5ee3 + 186e3b3
commit 0b0737d
Show file tree

Hide file tree

Showing 6 changed files with 436 additions and 5 deletions.
diff --git a/docs/ai/quickstarts/get-started-azure-openai.md b/docs/ai/quickstarts/get-started-azure-openai.md
@@ -1,18 +1,33 @@
 ---
 title: Quickstart - Build an Azure AI chat app with .NET
-description: Create a simple chat app using the .NET Azure OpenAI SDK.
+description: Create a simple chat app using Semantic Kernel or the .NET Azure OpenAI SDK.
 ms.date: 03/04/2024
 ms.topic: quickstart
 ms.custom: devx-track-dotnet, devx-track-dotnet-ai
 author: fboucher
 ms.author: frbouche
+zone_pivot_groups: openai-library
 # CustomerIntent: As a .NET developer new to Azure OpenAI, I want deploy and use sample code to interact to learn from the sample code.
 ---
 
 # Build an Azure AI chat app with .NET
 
+<!-- markdownlint-disable MD044 -->
+:::zone target="docs" pivot="semantic-kernel"
+<!-- markdownlint-enable MD044 -->
+
+Get started with the Semantic Kernel by creating a simple .NET 8 console chat application. The application will run locally and use the OpenAI `gpt-35-turbo` model deployed into an Azure OpenAI account. Follow these steps to provision Azure OpenAI and learn how to use Semantic Kernel.
+
+:::zone-end
+
+<!-- markdownlint-disable MD044 -->
+:::zone target="docs" pivot="azure-openai-sdk"
+<!-- markdownlint-enable MD044 -->
+
 Get started with the .NET Azure OpenAI SDK by creating a simple .NET 8 console chat application. The application will run locally and use the OpenAI `gpt-35-turbo` model deployed into an Azure OpenAI account. Follow these steps to provision Azure OpenAI and learn how to use the .NET Azure OpenAI SDK.
 
+:::zone-end
+
 [!INCLUDE [download-alert](includes/prerequisites-and-azure-deploy.md)]
 
 ## Trying HikerAI sample
@@ -26,6 +41,82 @@ Get started with the .NET Azure OpenAI SDK by creating a simple .NET 8 console c
 
     If you get an error message the Azure OpenAI resources may not have finished deploying. Wait a couple of minutes and try again.
 
+<!-- markdownlint-disable MD044 -->
+:::zone target="docs" pivot="semantic-kernel"
+<!-- markdownlint-enable MD044 -->
+
+## Understanding the code
+
+Our application uses the `Microsoft.SemanticKernel` package, which is available on [NuGet](https://www.nuget.org/packages/Microsoft.SemanticKernel), to send and receive requests to an Azure OpenAI service deployed in Azure.
+
+The `AzureOpenAIChatCompletionService` service facilitates the requests and responses.
+
+```csharp
+// == Create the Azure OpenAI Chat Completion Service  ==========
+AzureOpenAIChatCompletionService service = new(deployment, endpoint, key);
+```
+
+The entire application is contained within the **Program.cs** file. The first several lines of code loads up secrets and configuration values that were set in the `dotnet user-secrets` for you during the application provisioning.
+
+```csharp
+// == Retrieve the local secrets saved during the Azure deployment ==========
+var config = new ConfigurationBuilder().AddUserSecrets<Program>().Build();
+string endpoint = config["AZURE_OPENAI_ENDPOINT"];
+string deployment = config["AZURE_OPENAI_GPT_NAME"];
+string key = config["AZURE_OPENAI_KEY"];
+```
+
+Once the `AzureOpenAIChatCompletionService` service is created, we provide more context to the model by adding a system prompt. This instructs the model how you'd like it to act during the conversation.
+
+```csharp
+// Start the conversation with context for the AI model
+ChatHistory chatHistory = new("""
+    You are a hiking enthusiast who helps people discover fun hikes in their area. You are upbeat and friendly. 
+    You introduce yourself when first saying hello. When helping people out, you always ask them 
+    for this information to inform the hiking recommendation you provide:
+
+    1. Where they are located
+    2. What hiking intensity they are looking for
+
+    You will then provide three suggestions for nearby hikes that vary in length after you get that information. 
+    You will also share an interesting fact about the local nature on the hikes when making a recommendation.
+    """);
+```
+
+Then you can add a user message to the model by using the `AddUserMessage` function.
+
+To have the model generate a response based off the system prompt and the user request, use the `GetChatMessageContentAsync` function.
+
+```csharp
+
+// Add user message to chat history
+chatHistory.AddUserMessage("Hi! Apparently you can help me find a hike that I will like?");
+
+// Print User Message to console
+Console.WriteLine($"{chatHistory.Last().Role} >>> {chatHistory.Last().Content}");
+
+// Get response
+var response = await service.GetChatMessageContentAsync(chatHistory, new OpenAIPromptExecutionSettings() { MaxTokens = 400 });
+```
+
+To maintain the chat history, make sure you add the response from the model.
+
+```csharp
+// Add response to chat history
+chatHistory.Add(response);
+
+// Print Response to console
+Console.WriteLine($"{chatHistory.Last().Role} >>> {chatHistory.Last().Content}");
+```
+
+Customize the system prompt and user message to see how the model responds to help you find a hike that you'll like.
+
+:::zone-end
+
+<!-- markdownlint-disable MD044 -->
+:::zone target="docs" pivot="azure-openai-sdk"
+<!-- markdownlint-enable MD044 -->
+
 ## Understanding the code
 
 Our application uses the `Azure.AI.OpenAI` client SDK, which is available on [NuGet](https://www.nuget.org/packages/Azure.AI.OpenAI), to send and receive requests to an Azure OpenAI service deployed in Azure.
@@ -102,6 +193,8 @@ To maintain the chat history or context, make sure you add the response from the
 
 Customize the system prompt and user message to see how the model responds to help you find a hike that you'll like.
 
+:::zone-end
+
 ## Clean up resources
 
 When you no longer need the sample application or resources, remove the corresponding deployment and all resources.

diff --git a/docs/ai/quickstarts/quickstart-ai-chat-with-data.md b/docs/ai/quickstarts/quickstart-ai-chat-with-data.md
@@ -1,18 +1,32 @@
 ---
 title: Quickstart - Get insight about your data from an .NET Azure AI chat app
-description: Create a simple chat app using your data and the .NET Azure OpenAI SDK.
+description: Create a simple chat app using your data and Semantic Kernel or the .NET Azure OpenAI SDK.
 ms.date: 03/04/2024
 ms.topic: quickstart
 ms.custom: devx-track-dotnet, devx-track-dotnet-ai
 author: fboucher
 ms.author: frbouche
+zone_pivot_groups: openai-library
 # CustomerIntent: As a .NET developer new to Azure OpenAI, I want deploy and use sample code and data to interact to learn from the sample code.
 ---
 
 # Get insight about your data from an .NET Azure AI chat app
 
+<!-- markdownlint-disable MD044 -->
+:::zone target="docs" pivot="semantic-kernel"
+<!-- markdownlint-enable MD044 -->
+
+Get started with Semantic Kernel and the `gpt-35-turbo` model, from a simple .NET 8.0 console application. Use the AI model to get analytics and information about your previous hikes. It consists of a simple console application, running locally, that will read the file `hikes.md` and send request to an Azure OpenAI service deployed in your Azure subscription and provide the result in the console. Follow these steps to provision Azure OpenAI and learn how to use Semantic Kernel.
+:::zone-end
+
+<!-- markdownlint-disable MD044 -->
+:::zone target="docs" pivot="azure-openai-sdk"
+<!-- markdownlint-enable MD044 -->
+
 Get started with the .NET Azure OpenAI with a `gpt-35-turbo` model, from a simple .NET 8.0 console application. Use the AI model to get analytics and information about your previous hikes. It consists of a simple console application, running locally, that will read the file `hikes.md` and send request to an Azure OpenAI service deployed in your Azure subscription and provide the result in the console. Follow these steps to provision Azure OpenAI and learn how to use the .NET Azure OpenAI SDK.
 
+:::zone-end
+
 [!INCLUDE [download-alert](includes/prerequisites-and-azure-deploy.md)]
 
 ## Try "Chatting About My Previous Hikes" sample
@@ -26,6 +40,76 @@ Get started with the .NET Azure OpenAI with a `gpt-35-turbo` model, from a simpl
 
     If you get an error message the Azure OpenAI resources may not have finished deploying. Wait a couple of minutes and try again.
 
+<!-- markdownlint-disable MD044 -->
+:::zone target="docs" pivot="semantic-kernel"
+<!-- markdownlint-enable MD044 -->
+
+## Explore the code
+
+Our application uses the `Microsoft.SemanticKernel` package, which is available on [NuGet](https://www.nuget.org/packages/Microsoft.SemanticKernel), to send and receive requests to an Azure OpenAI service deployed in Azure.
+
+The `AzureOpenAIChatCompletionService` service facilitates the requests and responses.
+
+```csharp
+// == Create the Azure OpenAI Chat Completion Service  ==========
+AzureOpenAIChatCompletionService service = new(deployment, endpoint, key);
+```
+
+The entire application is contained within the **Program.cs** file. The first several lines of code loads up secrets and configuration values that were set in the `dotnet user-secrets` for you during the application provisioning.
+
+```csharp
+// == Retrieve the local secrets saved during the Azure deployment ==========
+var config = new ConfigurationBuilder().AddUserSecrets<Program>().Build();
+string endpoint = config["AZURE_OPENAI_ENDPOINT"];
+string deployment = config["AZURE_OPENAI_GPT_NAME"];
+string key = config["AZURE_OPENAI_KEY"];
+```
+
+Once the `AzureOpenAIChatCompletionService` client is created, we read the content of the file `hikes.md` and use it to provide more context to the model by adding a system prompt. This instructs the model how you'd like it to act during the conversation.
+
+```csharp
+// Provide context for the AI model
+ChatHistory chatHistory = new($"""
+    You are upbeat and friendly. You introduce yourself when first saying hello. 
+    Provide a short answer only based on the user hiking records below:  
+
+    {File.ReadAllText("hikes.md")}
+    """);
+Console.WriteLine($"{chatHistory.Last().Role} >>> {chatHistory.Last().Content}");
+```
+
+Then you can add a user message to the model by using the `AddUserMessage` function.
+
+To have the model generate a response based off the system prompt and the user request, use the `GetChatMessageContentAsync` function.
+
+```csharp
+// Start the conversation
+chatHistory.AddUserMessage("Hi!");
+Console.WriteLine($"{chatHistory.Last().Role} >>> {chatHistory.Last().Content}");
+
+chatHistory.Add(await service.GetChatMessageContentAsync(chatHistory, new OpenAIPromptExecutionSettings() { MaxTokens = 400 }));
+Console.WriteLine($"{chatHistory.Last().Role} >>> {chatHistory.Last().Content}");
+```
+
+To maintain the chat history or context, make sure you add the response from the model to the `chatHistory`. It's time to make our user request about our data again using the `AddUserMessage` and `GetChatMessageContentAsync` function.
+
+```csharp
+// Continue the conversation with a question.
+chatHistory.AddUserMessage("I would like to know the ratio of the hikes I've done in Canada compared to other countries.");
+Console.WriteLine($"{chatHistory.Last().Role} >>> {chatHistory.Last().Content}");
+
+chatHistory.Add(await service.GetChatMessageContentAsync(chatHistory, new OpenAIPromptExecutionSettings() { MaxTokens = 400 }));
+Console.WriteLine($"{chatHistory.Last().Role} >>> {chatHistory.Last().Content}");
+```
+
+Customize the system prompt and change the request, asking for different questions (ex: How many times did you hiked when it was raining? How many times did you hiked in 2021? etc.) to see how the model responds.
+
+:::zone-end
+
+<!-- markdownlint-disable MD044 -->
+:::zone target="docs" pivot="azure-openai-sdk"
+<!-- markdownlint-enable MD044 -->
+
 ## Explore the code
 
 Our application uses the `Azure.AI.OpenAI` client SDK, which is available on [NuGet](https://www.nuget.org/packages/Azure.AI.OpenAI), to send and receive requests to an Azure OpenAI service deployed in Azure.
@@ -109,6 +193,8 @@ response = await openAIClient.GetChatCompletionsAsync(completionOptions);
 
 Customize the system prompt and change the request, asking for different questions (ex: How many times did you hiked when it was raining? How many times did you hiked in 2021? etc.) to see how the model responds.
 
+:::zone-end
+
 ## Clean up resources
 
 When you no longer need the sample application or resources, remove the corresponding deployment and all resources.

diff --git a/docs/ai/quickstarts/quickstart-azure-openai-tool.md b/docs/ai/quickstarts/quickstart-azure-openai-tool.md
@@ -1,18 +1,33 @@
 ---
 title: Quickstart - Extend Azure AI using Tools and execute a local Function with .NET 
-description: Create a simple chat app using the .NET Azure OpenAI SDK and extend the model to execute a local function.
+description: Create a simple chat app using Semantic Kernel or the .NET Azure OpenAI SDK and extend the model to execute a local function.
 ms.date: 03/04/2024
 ms.topic: quickstart
 ms.custom: devx-track-dotnet, devx-track-dotnet-ai
 author: fboucher
 ms.author: frbouche
+zone_pivot_groups: openai-library
 # CustomerIntent: As a .NET developer new to Azure OpenAI, I want deploy and use sample code to interact to learn from the sample code how to extend the model using Tools.
 ---
 
 # Extend Azure AI using Tools and execute a local Function with .NET
 
+<!-- markdownlint-disable MD044 -->
+:::zone target="docs" pivot="semantic-kernel"
+<!-- markdownlint-enable MD044 -->
+
+Get started with Semantic Kernel by creating a simple .NET 8 console chat application. The application will run locally and use the OpenAI `gpt-35-turbo` model deployed into an Azure OpenAI account, however using Tool to extend the model capabilities it will call a local function. Follow these steps to provision Azure OpenAI and learn how to use Semantic Kernel.
+
+:::zone-end
+
+<!-- markdownlint-disable MD044 -->
+:::zone target="docs" pivot="azure-openai-sdk"
+<!-- markdownlint-enable MD044 -->
+
 Get started with the .NET Azure OpenAI SDK by creating a simple .NET 8 console chat application. The application will run locally and use the OpenAI `gpt-35-turbo` model deployed into an Azure OpenAI account, however using Tool to extend the model capabilities it will call a local function. Follow these steps to provision Azure OpenAI and learn how to use the .NET Azure OpenAI SDK.
 
+:::zone-end
+
 [!INCLUDE [download-alert](includes/prerequisites-and-azure-deploy.md)]
 
 ## Try HikerAI Pro sample
@@ -26,6 +41,91 @@ Get started with the .NET Azure OpenAI SDK by creating a simple .NET 8 console c
 
     If you get an error message the Azure OpenAI resources may not have finished deploying. Wait a couple of minutes and try again.
 
+<!-- markdownlint-disable MD044 -->
+:::zone target="docs" pivot="semantic-kernel"
+<!-- markdownlint-enable MD044 -->
+
+## Understand the code
+
+Our application uses the `Microsoft.SemanticKernel` package, which is available on [NuGet](https://www.nuget.org/packages/Microsoft.SemanticKernel), to send and receive requests to an Azure OpenAI service deployed in Azure.
+
+```csharp
+// Add a new plugin with a local .NET function that should be available to the AI model
+// For convenience and clarity of into the code, this standalone local method handles tool call responses. It will fake a call to a weather API and return the current weather for the specified location.
+kernel.ImportPluginFromFunctions("WeatherPlugin",
+[
+    KernelFunctionFactory.CreateFromMethod(([Description("The city, e.g. Montreal, Sidney")] string location, string unit = null) =>
+    {
+        // Here you would call a weather API to get the weather for the location
+        return "Periods of rain or drizzle, 15 C";
+    }, "get_current_weather", "Get the current weather in a given location")
+]);
+```
+
+The `Kernel` class facilitates the requests and responses with the help of `AddAzureOpenAIChatCompletion` service.
+
+```csharp
+// Create a Kernel containing the Azure OpenAI Chat Completion Service
+IKernelBuilder b = Kernel.CreateBuilder();
+
+Kernel kernel = b
+    .AddAzureOpenAIChatCompletion(deployment, endpoint, key)
+    .Build();
+```
+
+The entire application is contained within the **Program.cs** file. The first several lines of code loads up secrets and configuration values that were set in the `dotnet user-secrets` for you during the application provisioning.
+
+```csharp
+var config = new ConfigurationBuilder().AddUserSecrets<Program>().Build();
+string endpoint = config["AZURE_OPENAI_ENDPOINT"];
+string deployment = config["AZURE_OPENAI_GPT_NAME"];
+string key = config["AZURE_OPENAI_KEY"];
+```
+
+Once the `kernel` client is created, we provide more context to the model by adding a system prompt. This instructs the model how you'd like it to act during the conversation. Note how the weather is emphasized in the system prompt.
+
+```csharp
+ChatHistory chatHistory = new("""
+    You are a hiking enthusiast who helps people discover fun hikes in their area. You are upbeat and friendly.
+    A good weather is important for a good hike. Only make recommendations if the weather is good or if people insist.
+    You introduce yourself when first saying hello. When helping people out, you always ask them 
+    for this information to inform the hiking recommendation you provide:
+
+    1. Where they are located
+    2. What hiking intensity they are looking for
+
+    You will then provide three suggestions for nearby hikes that vary in length after you get that information. 
+    You will also share an interesting fact about the local nature on the hikes when making a recommendation.
+    """);
+```
+
+Then you can add a user message to the model by using the `AddUserMessage` functon.
+
+To have the model generate a response based off the system prompt and the user request, use the `GetChatMessageContentAsync` function.
+
+```csharp
+chatHistory.AddUserMessage("""
+    Is the weather is good today for a hike?
+    If yes, I live in the greater Montreal area and would like an easy hike. I don't mind driving a bit to get there.
+    I don't want the hike to be over 10 miles round trip. I'd consider a point-to-point hike.
+    I want the hike to be as isolated as possible. I don't want to see many people.
+    I would like it to be as bug free as possible.
+    """);
+
+Console.WriteLine($"{chatHistory.Last().Role} >>> {chatHistory.Last().Content}");
+
+chatHistory.Add(await service.GetChatMessageContentAsync(chatHistory, new OpenAIPromptExecutionSettings() { MaxTokens = 400 }));
+Console.WriteLine($"{chatHistory.Last().Role} >>> {chatHistory.Last().Content}");
+```
+
+Customize the system prompt and user message to see how the model responds to help you find a hike that you'll like.
+
+:::zone-end
+
+<!-- markdownlint-disable MD044 -->
+:::zone target="docs" pivot="azure-openai-sdk"
+<!-- markdownlint-enable MD044 -->
+
 ## Understand the code
 
 Our application uses the `Azure.AI.OpenAI` client SDK, which is available on [NuGet](https://www.nuget.org/packages/Azure.AI.OpenAI), to send and receive requests to an Azure OpenAI service deployed in Azure.
@@ -179,6 +279,8 @@ Console.WriteLine($"\n\nAssistant >>> {assistantResponse.Content}");
 
 Customize the system prompt and user message to see how the model responds to help you find a hike that you'll like.
 
+:::zone-end
+
 ## Clean up resources
 
 When you no longer need the sample application or resources, remove the corresponding deployment and all resources.