fixes

dotnet · Jul 18, 2024 · 17be75e · 17be75e
1 parent 94f4104
commit 17be75e
Show file tree

Hide file tree

Showing 10 changed files with 221 additions and 101 deletions.
diff --git a/docs/ai/quickstarts/get-started-openai.md b/docs/ai/quickstarts/get-started-openai.md
@@ -32,40 +32,52 @@ Get started with Semantic Kernel by creating a simple .NET 8 console chat applic
 
 :::zone-end
 
+## Get the sample project
+
+[!INCLUDE [clone-sample-repo](includes/clone-sample-repo.md)]
+
+:::zone target="docs" pivot="azure-openai"
+
+[!INCLUDE [deploy-azd](includes/deploy-azd.md)]
+
+:::zone-end
+
 ## Try the HikerAI sample
 
 <!-- markdownlint-disable MD029 MD044 -->
 :::zone target="docs" pivot="openai"
 
-1. Clone the repository: [dotnet/ai-samples](https://github.com/dotnet/ai-samples)
-
 1. From a terminal or command prompt, navigate to the `openai\02-HikerAI` directory.
 
-    [!INCLUDE [download-alert](includes/set-openai-secrets.md)]
+1. Run the following commands to configure your OpenAI API key as a secret for the sample app:
+
+    ```bash
+    dotnet user-secrets init
+    dotnet user-secrets set OpenAIKey <your-openai-key>
+    ```
+
+1. Use the `dotnet run` command to run the app:
+
+    ```dotnetcli
+    dotnet run
+    ```
 
 :::zone-end
 
 :::zone target="docs" pivot="azure-openai"
 
 1. From a terminal or command prompt, navigate to the `azure-openai\02-HikerAI` directory.
 
-:::zone-end
-
-2. Use the following to run the app:
+2. Use the `dotnet run` command to run the app:
 
     ```dotnetcli
     dotnet run
     ```
 
-    :::zone target="docs" pivot="azure-openai"
-    If you get an error message, the Azure OpenAI resources may not have finished deploying. Wait a couple of minutes and try again.
-    :::zone-end
-
-<!-- markdownlint-enable MD029 MD044  -->
+> [!NOTE]
+> 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="openai"
-<!-- markdownlint-enable MD044 -->
+:::zone-end
 
 ## Explore the code
 
@@ -122,15 +134,17 @@ Add a system prompt to provide more context to the model, which influences model
 ```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:
+    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.
+    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.
     """);
 ```
 
@@ -172,8 +186,11 @@ Remove the corresponding deployment and all resources when you no longer need th
 azd down
 ```
 
+[!INCLUDE [troubleshoot](includes/troubleshoot.md)]
+
 :::zone-end
 
+
 ## Next steps
 
 - [Quickstart - Get insight about your data from .NET AI chat app](quickstart-ai-chat-with-data.md)

diff --git a/docs/ai/quickstarts/includes/clone-sample-repo.md b/docs/ai/quickstarts/includes/clone-sample-repo.md
@@ -0,0 +1,12 @@
+---
+author: jmatthiesen
+ms.author: jomatthi
+ms.date: 07/03/2024
+ms.topic: include
+---
+
+A GitHub repository is available that contains all the sample apps for all of the quickstarts. Clone the repository using the following command:
+
+```bash
+git clone https://github.com/dotnet/ai-samples.git
+```
diff --git a/docs/ai/quickstarts/includes/deploy-azd.md b/docs/ai/quickstarts/includes/deploy-azd.md
@@ -0,0 +1,22 @@
+---
+author: jmatthiesen
+ms.author: jomatthi
+ms.date: 07/03/2024
+ms.topic: include
+---
+
+## Deploy the Azure resources
+
+Ensure that you follow the [Prerequisites](#prerequisites) to have access to Azure OpenAI Service as well as the Azure Developer CLI, and then follow the following guide to set started with the sample application.
+
+1. Clone the repository: [dotnet/ai-samples](https://github.com/dotnet/ai-samples)
+1. From a terminal or command prompt, navigate to the _src\quickstarts\azure-openai_ directory (on macOS or Linux, replace the '\\' character with a '/'.
+1. This provisions the Azure OpenAI resources. It may take several minutes to create the Azure OpenAI service and deploy the model.
+
+   ```azdeveloper
+   azd up
+   ```
+
+> [!NOTE]
+> If you encounter an error during the `azd up` deployment, visit the [troubleshooting](#troubleshoot) section.
+
diff --git a/docs/ai/quickstarts/includes/prerequisites-azure-openai.md b/docs/ai/quickstarts/includes/prerequisites-azure-openai.md
@@ -12,47 +12,3 @@ ms.topic: include
 - Azure Developer CLI - [Install or update the Azure Developer CLI](/azure/developer/azure-developer-cli/install-azd)
 - Access to [Azure OpenAI service](/azure/ai-services/openai/overview#how-do-i-get-access-to-azure-openai).
 - On Windows, PowerShell `v7+` is required. To validate your version, run `pwsh` in a terminal. It should return the current version. If it returns an error, execute the following command: `dotnet tool update --global PowerShell`.
-
-## Deploy the Azure resources
-
-Ensure that you follow the [Prerequisites](#prerequisites) to have access to Azure OpenAI Service as well as the Azure Developer CLI, and then follow the following guide to set started with the sample application.
-
-1. Clone the repository: [dotnet/ai-samples](https://github.com/dotnet/ai-samples)
-1. From a terminal or command prompt, navigate to the _src\quickstarts\azure-openai_ directory (on macOS or Linux, replace the '\\' character with a '/'.
-1. This provisions the Azure OpenAI resources. It may take several minutes to create the Azure OpenAI service and deploy the model.
-
-   ```azdeveloper
-   azd up
-   ```
-
-> [!NOTE]
-> If you already have an Azure OpenAI service available, you can skip the deployment and use that value in the _Program.cs_, preferably from an `IConfiguration`.
-
-## Troubleshoot
-
-On Windows, you might get the following error messages after running `azd up`:
-
-> *postprovision.ps1 is not digitally signed. The script will not execute on the system*
-
-The script **postprovision.ps1** is executed to set the .NET user secrets used in the application. To avoid this error, run the following PowerShell command:
-
-```powershell
-Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
-```
-
-Then re-run the `azd up` command.
-
-Another possible error:
-
-> 'pwsh' is not recognized as an internal or external command,
-> operable program or batch file.
-> WARNING: 'postprovision' hook failed with exit code: '1', Path: '.\infra\post-script\postprovision.ps1'. : exit code: 1
-> Execution will continue since ContinueOnError has been set to true.
-
-The script **postprovision.ps1** is executed to set the .NET user secrets used in the application. To avoid this error, manually run the script using the following PowerShell command:
-
-```powershell
-.\infra\post-script\postprovision.ps1
-```
-
-The .NET AI apps now have the user-secrets configured and they can be tested.
diff --git a/docs/ai/quickstarts/includes/set-openai-secrets.md b/docs/ai/quickstarts/includes/set-openai-secrets.md
@@ -4,7 +4,8 @@ ms.author: jomatthi
 ms.date: 07/03/2024
 ms.topic: include
 ---
-Run the following commands to configure your OpenAI API key to run the sample, using the key you previously got from OpenAI.
+
+Run the following commands to configure your OpenAI API key as a secret for the sample app:
 
 ```bash
 dotnet user-secrets init

diff --git a/docs/ai/quickstarts/includes/troubleshoot.md b/docs/ai/quickstarts/includes/troubleshoot.md
@@ -0,0 +1,28 @@
+## Troubleshoot
+
+On Windows, you might get the following error messages after running `azd up`:
+
+> *postprovision.ps1 is not digitally signed. The script will not execute on the system*
+
+The script **postprovision.ps1** is executed to set the .NET user secrets used in the application. To avoid this error, run the following PowerShell command:
+
+```powershell
+Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
+```
+
+Then re-run the `azd up` command.
+
+Another possible error:
+
+> 'pwsh' is not recognized as an internal or external command,
+> operable program or batch file.
+> WARNING: 'postprovision' hook failed with exit code: '1', Path: '.\infra\post-script\postprovision.ps1'. : exit code: 1
+> Execution will continue since ContinueOnError has been set to true.
+
+The script **postprovision.ps1** is executed to set the .NET user secrets used in the application. To avoid this error, manually run the script using the following PowerShell command:
+
+```powershell
+.\infra\post-script\postprovision.ps1
+```
+
+The .NET AI apps now have the user-secrets configured and they can be tested.
diff --git a/docs/ai/quickstarts/quickstart-ai-chat-with-data.md b/docs/ai/quickstarts/quickstart-ai-chat-with-data.md
@@ -30,34 +30,53 @@ Get started with AI development, using the `gpt-35-turbo` model from a simple .N
 [!INCLUDE [download-alert](includes/prerequisites-azure-openai.md)]
 :::zone-end
 
+## Get the sample project
+
+[!INCLUDE [clone-sample-repo](includes/clone-sample-repo.md)]
+
+:::zone target="docs" pivot="azure-openai"
+
+[!INCLUDE [deploy-azd](includes/deploy-azd.md)]
+
+:::zone-end
+
 ## Try the "Chatting About My Previous Hikes" sample
 
 <!-- markdownlint-disable MD029 MD044 -->
 :::zone target="docs" pivot="openai"
 
-1. Clone the repository: [dotnet/ai-samples](https://github.com/dotnet/ai-samples)
-
 1. From a terminal or command prompt, navigate to the `openai\03-ChattingAboutMyHikes` directory.
 
-    [!INCLUDE [download-alert](includes/set-openai-secrets.md)]
+1. Run the following commands to configure your OpenAI API key as a secret for the sample app:
 
-:::zone-end
+    ```bash
+    dotnet user-secrets init
+    dotnet user-secrets set OpenAIKey <your-openai-key>
+    ```
 
-:::zone target="docs" pivot="azure-openai"
+1. Use the `dotnet run` command to run the app:
 
-1. From a terminal or command prompt, navigate to the `azure-openai\03-ChattingAboutMyHikes` directory.
+    ```dotnetcli
+    dotnet run
+    ```
 
 :::zone-end
 
-2. It's now time to try the console application. Type in the following to run the app:
+:::zone target="docs" pivot="azure-openai"
+
+1. From a terminal or command prompt, navigate to the `azure-openai\02-HikerAI` directory.
+
+2. Use the `dotnet run` command to run the app:
 
     ```dotnetcli
     dotnet run
     ```
 
-    :::zone target="docs" pivot="azure-openai"
-    If you get an error message the Azure OpenAI resources may not have finished deploying. Wait a couple of minutes and try again.
-    :::zone-end
+> [!NOTE]
+> If you get an error message, the Azure OpenAI resources may not have finished deploying. Wait a couple of minutes and try again.
+
+:::zone-end
+
 <!-- markdownlint-enable MD029 MD044  -->
 
 ## Explore the code
@@ -161,8 +180,11 @@ When you no longer need the sample application or resources, remove the correspo
 azd down
 ```
 
+[!INCLUDE [troubleshoot](includes/troubleshoot.md)]
+
 :::zone-end
 
+
 ## Next steps
 
 - [Quickstart - Generate images using AI with .NET](quickstart-openai-generate-images.md)

diff --git a/docs/ai/quickstarts/quickstart-azure-openai-tool.md b/docs/ai/quickstarts/quickstart-azure-openai-tool.md
@@ -32,34 +32,52 @@ Get started with AI by creating a simple .NET 8 console chat application. The ap
 
 :::zone-end
 
+## Get the sample project
+
+[!INCLUDE [clone-sample-repo](includes/clone-sample-repo.md)]
+
+:::zone target="docs" pivot="azure-openai"
+
+[!INCLUDE [deploy-azd](includes/deploy-azd.md)]
+
+:::zone-end
+
 ## Try the the HikerAI Pro sample
 
 <!-- markdownlint-disable MD029 MD044 -->
 :::zone target="docs" pivot="openai"
 
-1. Clone the repository: [dotnet/ai-samples](https://github.com/dotnet/ai-samples)
+1. From a terminal or command prompt, navigate to the `azure-openai\04-HikerAIPro` directory.
 
-1. From a terminal or command prompt, navigate to the `openai\04-HikerAIPro` directory.
+1. Run the following commands to configure your OpenAI API key as a secret for the sample app:
+
+    ```bash
+    dotnet user-secrets init
+    dotnet user-secrets set OpenAIKey <your-openai-key>
+    ```
 
-    [!INCLUDE [download-alert](includes/set-openai-secrets.md)]
+1. Use the `dotnet run` command to run the app:
+
+    ```dotnetcli
+    dotnet run
+    ```
 
 :::zone-end
 
 :::zone target="docs" pivot="azure-openai"
 
 1. From a terminal or command prompt, navigate to the `azure-openai\04-HikerAIPro` directory.
 
-:::zone-end
-
-2. It's now time to try the console application. Type in the following to run the app:
+2. Use the `dotnet run` command to run the app:
 
     ```dotnetcli
     dotnet run
     ```
 
-    :::zone target="docs" pivot="azure-openai"
-    If you get an error message the Azure OpenAI resources may not have finished deploying. Wait a couple of minutes and try again.
-    :::zone-end
+> [!NOTE]
+> If you get an error message, the Azure OpenAI resources may not have finished deploying. Wait a couple of minutes and try again.
+
+:::zone-end
 <!-- markdownlint-enable MD029 MD044  -->
 
 ## Understand the code
@@ -184,6 +202,8 @@ When you no longer need the sample application or resources, remove the correspo
 azd down
 ```
 
+[!INCLUDE [troubleshoot](includes/troubleshoot.md)]
+
 :::zone-end
 
 ## Next steps