Merge pull request #283759 from eric-urban/eur/studo-doc-user-feedback

incorporate feedback from customers

Author: denrea

articles/ai-studio/includes/chat-with-data.md

@@ -10,7 +10,7 @@ ms.date: 5/21/2024
 ms.custom: include, build-2024
 ---
 
-To complete this section, you need a local copy of product data. The [Azure-Samples/aistudio-python-quickstart-sample repository on GitHub](https://github.com/Azure-Samples/aistudio-python-quickstart-sample/tree/main/data) contains sample retail customer and product information that's relevant for this tutorial scenario. Clone the repository or copy the files from [3-product-info](https://github.com/Azure-Samples/aistudio-python-quickstart-sample/tree/main/data/3-product-info). 
+To complete this section, you need a local copy of product data. The [Azure-Samples/rag-data-openai-python-promptflow repository on GitHub](https://github.com/Azure-Samples/rag-data-openai-python-promptflow/) contains sample retail product information that's relevant for this tutorial scenario. Specifically, the `product_info_11.md` file contains product information about the TrailWalker hiking shoes that's relevant for this tutorial example. [Download the example Contoso Trek retail product data in a ZIP file](https://github.com/Azure-Samples/rag-data-openai-python-promptflow/raw/main/tutorial/data.zip) to your local machine.
 
 > [!IMPORTANT]
 > The **Add your data** feature in the Azure AI Studio playground doesn't support using a virtual network or private endpoint on the following resources:
@@ -36,7 +36,7 @@ Follow these steps to add your data in the chat playground to help the assistant
 
 1. Select **Upload** > **Upload files** to browse your local files. 
 
-1. Select the files you want to upload. Select the product information files ([3-product-info](https://github.com/Azure-Samples/aistudio-python-quickstart-sample/tree/main/data/3-product-info)) that you downloaded or created earlier. Add all of the files now. You won't be able to add more files later in the same playground session.
+1. Select the files you want to upload. Select the product information files that you [downloaded](https://github.com/Azure-Samples/rag-data-openai-python-promptflow/raw/main/tutorial/data.zip) or created earlier. Add all of the files now. You won't be able to add more files later in the same playground session. 
 
 1. Select **Upload** to upload the file to your Azure Blob storage account. Then select **Next**.
 
@@ -63,8 +63,4 @@ Follow these steps to add your data in the chat playground to help the assistant
 
    :::image type="content" source="../media/tutorials/chat/add-your-data-ingestion-in-progress.png" alt-text="Screenshot of the chat playground with the status of data ingestion in view." lightbox="../media/tutorials/chat/add-your-data-ingestion-in-progress.png":::
 
-1. Enter a name for the playground configuration and select **Save** > **Save configuration**. All configuration items are saved by default. Items include deployment, system message, safety message, parameters, added data, examples, and variables. Saving a configuration with the same name will save over the previous version.
-
-   :::image type="content" source="../media/tutorials/chat/playground-configuration-save.png" alt-text="Screenshot of the playground configuration name and Save button." lightbox="../media/tutorials/chat/playground-configuration-save.png":::
-
 1. You can now chat with the model asking the same question as before ("How much are the TrailWalker hiking shoes"), and this time it uses information from your data to construct the response. You can expand the **references** button to see the data that was used.

articles/ai-studio/includes/deploy-chat-model.md

@@ -6,15 +6,15 @@ ms.reviewer: eur
 ms.author: eric-urban
 ms.service: azure-ai-studio
 ms.topic: include
-ms.date: 5/21/2024
+ms.date: 8/8/2024
 ms.custom: include, build-2024
 ---
 
 Follow these steps to deploy an Azure OpenAI chat model for your copilot. 
 
 1. Sign in to [Azure AI Studio](https://ai.azure.com) and go to the **Home** page.
 1. Go to your hub by selecting it from the list of hubs via **Home** > **All hubs**. If you don't have a hub, create one. For more information, see [how to create a hub](../how-to/create-azure-ai-resource.md).
-1. From the left pane, select **Deployments** > **+ Create deployment**.
+1. From the left pane, select **Deployments** > **+ Deploy model**.
 
     :::image type="content" source="../media/tutorials/chat/deploy-create.png" alt-text="Screenshot of the deployments page with a button to create a new deployment." lightbox="../media/tutorials/chat/deploy-create.png":::
 

articles/ai-studio/media/tutorials/chat/playground-configuration-save.png

@@ -1,33 +1,35 @@
 ---
 title: Get started building a chat app using the prompt flow SDK
 titleSuffix: Azure AI Studio
-description: This article provides instructions on how to set up your development environment for Azure AI SDKs.
+description: This article provides instructions on how to build a custom chat app in Python using the prompt flow SDK.
 manager: nitinme
 ms.service: azure-ai-studio
 ms.custom: build-2024, devx-track-azurecli, devx-track-python
 ms.topic: how-to
-ms.date: 5/30/2024
+ms.date: 8/6/2024
 ms.reviewer: dantaylo
 ms.author: eur
 author: eric-urban
 ---
 
 # Build a custom chat app in Python using the prompt flow SDK
+
 [!INCLUDE [Feature preview](~/reusable-content/ce-skilling/azure/includes/ai-studio/includes/feature-preview.md)]
 
 In this quickstart, we walk you through setting up your local development environment with the prompt flow SDK. We write a prompt, run it as part of your app code, trace the LLM calls being made, and run a basic evaluation on the outputs of the LLM.
 
 ## Prerequisites
 
+> [!IMPORTANT]
+> You must have the necessary permissions to add role assignments for storage accounts in your Azure subscription. Granting permissions (adding role assignment) is only allowed by the **Owner** of the specific Azure resources. You might need to ask your IT admin for help to [grant access to call Azure OpenAI Service using your identity](#grant-access-to-call-azure-openai-service-using-your-identity).
+
 Before you can follow this quickstart, create the resources that you need for your application:
 - An [AI Studio hub](../how-to/create-azure-ai-resource.md) for connecting to external resources.
 - A [project](../how-to/create-projects.md) for organizing your project artifacts and sharing traces and evaluation runs.
 - A [deployed Azure OpenAI](../how-to/deploy-models-openai.md) chat model (gpt-35-turbo or gpt-4)
 
 Complete the [AI Studio playground quickstart](../quickstarts/get-started-playground.md) to create these resources if you haven't already. You can also create these resources by following the [SDK guide to create a hub and project](../how-to/develop/create-hub-project-sdk.md) article.
 
-Also, you must have the necessary permissions to add role assignments for storage accounts in your Azure subscription. Granting permissions (adding role assignment) is only allowed by the **Owner** of the specific Azure resources. You might need to ask your IT admin for help to [grant access to call Azure OpenAI Service using your identity](#grant-access-to-call-azure-openai-service-using-your-identity).
-
 ## Grant access to call Azure OpenAI Service using your identity
 
 To use security best practices, instead of API keys we use [Microsoft Entra ID](/entra/fundamentals/whatis) to authenticate with Azure OpenAI using your user identity. 
@@ -62,9 +64,9 @@ To grant yourself access to the Azure AI Services resource that you're using:
 
 1. Continue through the wizard and select **Review + assign** to add the role assignment. 
 
-## Install the Azure CLI and login 
+## Install the Azure CLI and sign in 
 
-Now we install the Azure CLI and login from your local development environment, so that you can use your user credentials to call the Azure OpenAI service.
+You install the Azure CLI and sign in from your local development environment, so that you can use your user credentials to call the Azure OpenAI service.
 
 In most cases you can install the Azure CLI from your terminal using the following command: 
 # [Windows](#tab/windows)
@@ -89,7 +91,7 @@ brew update && brew install azure-cli
 
 You can follow instructions [How to install the Azure CLI](/cli/azure/install-azure-cli) if these commands don't work for your particular operating system or setup.
 
-After you install the Azure CLI, login using the ``az login`` command and sign-in using the browser:
+After you install the Azure CLI, sign in using the ``az login`` command and sign-in using the browser:
 ```
 az login
 ```
@@ -131,7 +133,7 @@ source .venv/bin/activate
 
 ---
 
-Activating the Python environment means that when you run ```python``` or ```pip``` from the command line, you'll be using the Python interpreter contained in the ```.venv``` folder of your application.
+Activating the Python environment means that when you run ```python``` or ```pip``` from the command line, you then use the Python interpreter contained in the ```.venv``` folder of your application.
 
 > [!NOTE]
 > You can use the ```deactivate``` command to exit the python virtual environment, and can later reactivate it when needed.
@@ -181,7 +183,7 @@ Your AI services endpoint and deployment name are required to call the Azure Ope
 
 ## Create a basic chat prompt and app
 
-First create a prompt template file, for this we'll use **Prompty** which is the prompt template format supported by prompt flow.
+First create a **Prompty** file, which is the prompt template format supported by prompt flow.
 
 Create a ```chat.prompty``` file and copy the following code into it:
 
@@ -350,4 +352,4 @@ For more information on how to use prompt flow evaluators, including how to make
 ## Next step
 
 > [!div class="nextstepaction"]
-> [Augment the model with data for retrieval augmented generation (RAG)](../tutorials/copilot-sdk-build-rag.md)
+> [Add data and use retrieval augmented generation (RAG) to build a copilot](../tutorials/copilot-sdk-build-rag.md)

articles/ai-studio/quickstarts/get-started-code.md

@@ -5,7 +5,7 @@ description:  Learn how to build a RAG-based copilot using the prompt flow SDK.
 manager: scottpolly
 ms.service: azure-ai-studio
 ms.topic: tutorial
-ms.date: 7/18/2024
+ms.date: 8/6/2024
 ms.reviewer: lebaro
 ms.author: sgilley
 author: sdgilley
@@ -19,9 +19,9 @@ In this [Azure AI Studio](https://ai.azure.com) tutorial, you use the prompt flo
 This tutorial is part one of a two-part tutorial.
 
 > [!TIP]
-> This tutorial is based on code in the sample repo for a [copilot application that implements RAG](https://github.com/Azure-Samples/rag-data-openai-python-promptflow).
+> Be sure to set aside enough time to complete the prerequisites before starting this tutorial. If you're new to Azure AI Studio, you might need to spend additional time to get familiar with the platform. 
 
-This part one shows you how to enhance a basic chat application by adding retrieval augmented generation (RAG) to ground the responses in your custom data.
+This part one shows you how to enhance a basic chat application by adding [retrieval augmented generation (RAG)](../concepts/retrieval-augmented-generation.md) to ground the responses in your custom data.
 
 In this part one, you learn how to:
 
@@ -34,14 +34,15 @@ In this part one, you learn how to:
 
 ## Prerequisites
 
+> [!IMPORTANT]
+> You must have the necessary permissions to add role assignments in your Azure subscription. Granting permissions by role assignment is only allowed by the **Owner** of the specific Azure resources. You might need to ask your IT admin for help with completing the [assign access](#configure-access-for-the-azure-ai-search-service) section.
+
 - You need to complete the [Build a custom chat app in Python using the prompt flow SDK quickstart](../quickstarts/get-started-code.md) to set up your environment. 
 
     > [!IMPORTANT]
     > This tutorial builds on the code and environment you set up in the quickstart.
 
-- You need a local copy of product data. The [Azure-Samples/rag-data-openai-python-promptflow repository on GitHub](https://github.com/Azure-Samples/rag-data-openai-python-promptflow/) contains sample retail product information that's relevant for this tutorial scenario. Clone the repository or [download the example Contoso Trek retail product data in a ZIP file](https://github.com/Azure-Samples/rag-data-openai-python-promptflow/raw/main/tutorial/data.zip) to your local machine.
-
-- You must have the necessary permissions to add role assignments in your Azure subscription. Granting permissions by role assignment is only allowed by the **Owner** of the specific Azure resources. You might need to ask your IT admin for help with completing the [assign access](#configure-access-for-the-azure-ai-search-service) section.
+- You need a local copy of product data. The [Azure-Samples/rag-data-openai-python-promptflow repository on GitHub](https://github.com/Azure-Samples/rag-data-openai-python-promptflow/) contains sample retail product information that's relevant for this tutorial scenario. [Download the example Contoso Trek retail product data in a ZIP file](https://github.com/Azure-Samples/rag-data-openai-python-promptflow/raw/main/tutorial/data.zip) to your local machine.
 
 ## Application code structure
 
@@ -110,7 +111,7 @@ AZURE_OPENAI_CONNECTION_NAME=<your AIServices or Azure OpenAI connection name>
 
 ## Deploy an embedding model
 
-For the RAG capability, we need to be able to embed the search query to search the Azure AI Search index we create. 
+For the [retrieval augmented generation (RAG)](../concepts/retrieval-augmented-generation.md) capability, we need to be able to embed the search query to search the Azure AI Search index we create. 
 
 1. Deploy an Azure OpenAI embedding model. Follow the [deploy Azure OpenAI models guide](../how-to/deploy-models-openai.md) and deploy the **text-embedding-ada-002** model. Use the same **AIServices** or **Azure OpenAI** connection that you used [to deploy the chat model](../quickstarts/get-started-playground.md#deploy-a-chat-model). 
 2. Add embedding model environment variables in your *.env* file. For the *AZURE_OPENAI_EMBEDDING_DEPLOYMENT* value, enter the name of the embedding model that you deployed. 
@@ -119,14 +120,16 @@ For the RAG capability, we need to be able to embed the search query to search t
     AZURE_OPENAI_EMBEDDING_DEPLOYMENT=embedding_model_deployment_name
     ```
 
+For more information about the embedding model, see the [Azure OpenAI Service embeddings documentation](../../ai-services/openai/how-to/embeddings.md).
+
 ## Create an Azure AI Search index
 
 The goal with this RAG-based application is to ground the model responses in your custom data. You use an Azure AI Search index that stores vectorized data from the embeddings model. The search index is used to retrieve relevant documents based on the user's question.
 
 You need an Azure AI Search service and connection in order to create a search index.
 
 > [!NOTE]
-> Creating an Azure AI Search service and subsequent search indexes has associated costs. You can see details about pricing and pricing tiers for the Azure AI Search service on the creation page, to confirm cost before creating the resource.
+> Creating an [Azure AI Search service](../../search/index.yml) and subsequent search indexes has associated costs. You can see details about pricing and pricing tiers for the Azure AI Search service on the creation page, to confirm cost before creating the resource.
 
 ### Create an Azure AI Search service
 
@@ -148,7 +151,7 @@ Otherwise, you can create an Azure AI Search service using the [Azure portal](ht
 ## [Azure CLI](#tab/cli)
 
 1. Open a terminal on your local machine.
-1. Type `az` and then enter to verify that the Azure CLI tool is installed. If it's installed, a help menu with `az` commands appears. If you get an error, make sure you followed the [steps for installing the Azure CLI in the quickstart](../quickstarts/get-started-code.md#install-the-azure-cli-and-login).
+1. Type `az` and then enter to verify that the Azure CLI tool is installed. If it's installed, a help menu with `az` commands appears. If you get an error, make sure you followed the [steps for installing the Azure CLI in the quickstart](../quickstarts/get-started-code.md#install-the-azure-cli-and-sign-in).
 1. Follow the steps to create an Azure AI Search service using the [`az search service create`](../../search/search-manage-azure-cli.md#create-or-delete-a-service) command.
 
 ---

articles/ai-studio/tutorials/copilot-sdk-build-rag.md

@@ -5,7 +5,7 @@ description: Evaluate and deploy a RAG-based copilot with the prompt flow SDK. T
 manager: scottpolly
 ms.service: azure-ai-studio
 ms.topic: tutorial
-ms.date: 7/18/2024
+ms.date: 8/6/2024
 ms.reviewer: lebaro
 ms.author: sgilley
 author: sdgilley
@@ -18,9 +18,6 @@ In this [Azure AI Studio](https://ai.azure.com) tutorial, you use the prompt flo
 
 This tutorial is part two of a two-part tutorial.
 
-> [!TIP]
-> This tutorial is based on code in the sample repo for a [copilot application that implements RAG](https://github.com/Azure-Samples/rag-data-openai-python-promptflow).
-
 In this part two, you learn how to:
 
 > [!div class="checklist"]
@@ -69,7 +66,7 @@ Now define an evaluation script that will:
 - Load the sample `.jsonl` dataset.
 - Generate a target function wrapper around our copilot logic.
 - Run the evaluation, which takes the target function, and merges the evaluation dataset with the responses from the copilot.
-- Generate a set of GPT-assisted metrics (Relevance, Groundedness, and Coherence) to evaluate the quality of the copilot responses.
+- Generate a set of GPT-assisted metrics (relevance, groundedness, and coherence) to evaluate the quality of the copilot responses.
 - Output the results locally, and logs the results to the cloud project.
 
 The script allows you to review the results locally, by outputting the results in the command line, and to a json file.
@@ -327,5 +324,5 @@ To avoid incurring unnecessary Azure costs, you should delete the resources you
 
 ## Related content
 
-> [!div class="nextstepaction"]
-> [Learn more about prompt flow](../how-to/prompt-flow.md)
+- [Learn more about prompt flow](../how-to/prompt-flow.md)
+- For a sample copilot application that implements RAG, see [Azure-Samples/rag-data-openai-python-promptflow](https://github.com/Azure-Samples/rag-data-openai-python-promptflow)

articles/ai-studio/tutorials/copilot-sdk-evaluate-deploy.md

@@ -37,7 +37,7 @@ The steps in this tutorial are:
 
 - An [Azure AI Search service connection](../how-to/connections-add.md#create-a-new-connection) to index the sample product and customer data. 
 
-- You need at least one file to upload that contains example data. To complete this tutorial, use the product information samples from the [Azure-Samples/aistudio-python-quickstart-sample repository on GitHub](https://github.com/Azure-Samples/aistudio-python-quickstart-sample/tree/main/data). Specifically, the [product_info_11.md](https://github.com/Azure-Samples/aistudio-python-quickstart-sample/blob/main/data/3-product-info/product_info_11.md) contains product information about the TrailWalker hiking shoes that's relevant for this tutorial example. You can download the file or copy its contents to a file named `product_info_11.md` on your local computer.
+- You need a local copy of product data. The [Azure-Samples/rag-data-openai-python-promptflow repository on GitHub](https://github.com/Azure-Samples/rag-data-openai-python-promptflow/) contains sample retail product information that's relevant for this tutorial scenario. Specifically, the `product_info_11.md` file contains product information about the TrailWalker hiking shoes that's relevant for this tutorial example. [Download the example Contoso Trek retail product data in a ZIP file](https://github.com/Azure-Samples/rag-data-openai-python-promptflow/raw/main/tutorial/data.zip) to your local machine.
 
 ## Add your data and try the chat model again