AI Tour / docs fix v4 (#186)

* aitour-docs-fix-v4 / clear inputs on notebooks * docs ds-refresh * updated / evaluation docs * fixed / typos
Azure-Samples · Sep 27, 2024 · 26938fc · 26938fc
1 parent 6c54506
commit 26938fc
Show file tree

Hide file tree

Showing 15 changed files with 743 additions and 231 deletions.
diff --git a/data/customer_info/create-cosmos-db.ipynb b/data/customer_info/create-cosmos-db.ipynb
diff --git a/data/product_info/create-azure-search.ipynb b/data/product_info/create-azure-search.ipynb
@@ -15,20 +15,9 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 1,
+   "execution_count": null,
    "metadata": {},
-   "outputs": [
-    {
-     "data": {
-      "text/plain": [
-       "True"
-      ]
-     },
-     "execution_count": 1,
-     "metadata": {},
-     "output_type": "execute_result"
-    }
-   ],
+   "outputs": [],
    "source": [
     "import os\n",
     "import pandas as pd\n",
@@ -206,19 +195,9 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 5,
+   "execution_count": null,
    "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "deleting index contoso-products\n",
-      "creating index contoso-products\n",
-      "index contoso-products created\n"
-     ]
-    }
-   ],
+   "outputs": [],
    "source": [
     "contoso_search = os.environ[\"AZURE_SEARCH_ENDPOINT\"]\n",
     "index_name = \"contoso-products\"\n",
@@ -236,30 +215,9 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 6,
+   "execution_count": null,
    "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "indexing documents\n"
-     ]
-    },
-    {
-     "ename": "OpenAIError",
-     "evalue": "Missing credentials. Please pass one of `api_key`, `azure_ad_token`, `azure_ad_token_provider`, or the `AZURE_OPENAI_API_KEY` or `AZURE_OPENAI_AD_TOKEN` environment variables.",
-     "output_type": "error",
-     "traceback": [
-      "\u001b[1;31m---------------------------------------------------------------------------\u001b[0m",
-      "\u001b[1;31mOpenAIError\u001b[0m                               Traceback (most recent call last)",
-      "Cell \u001b[1;32mIn[6], line 2\u001b[0m\n\u001b[0;32m      1\u001b[0m \u001b[38;5;28mprint\u001b[39m(\u001b[38;5;124mf\u001b[39m\u001b[38;5;124m\"\u001b[39m\u001b[38;5;124mindexing documents\u001b[39m\u001b[38;5;124m\"\u001b[39m)\n\u001b[1;32m----> 2\u001b[0m docs \u001b[38;5;241m=\u001b[39m \u001b[43mgen_contoso_products\u001b[49m\u001b[43m(\u001b[49m\u001b[38;5;124;43m\"\u001b[39;49m\u001b[38;5;124;43mproducts.csv\u001b[39;49m\u001b[38;5;124;43m\"\u001b[39;49m\u001b[43m)\u001b[49m\n\u001b[0;32m      3\u001b[0m \u001b[38;5;66;03m# Upload our data to the index.\u001b[39;00m\n\u001b[0;32m      4\u001b[0m search_client \u001b[38;5;241m=\u001b[39m SearchClient(\n\u001b[0;32m      5\u001b[0m     endpoint\u001b[38;5;241m=\u001b[39mcontoso_search,\n\u001b[0;32m      6\u001b[0m     index_name\u001b[38;5;241m=\u001b[39mindex_name,\n\u001b[0;32m      7\u001b[0m     credential\u001b[38;5;241m=\u001b[39mDefaultAzureCredential(),\n\u001b[0;32m      8\u001b[0m )\n",
-      "Cell \u001b[1;32mIn[4], line 8\u001b[0m, in \u001b[0;36mgen_contoso_products\u001b[1;34m(path)\u001b[0m\n\u001b[0;32m      5\u001b[0m openai_deployment \u001b[38;5;241m=\u001b[39m \u001b[38;5;124m\"\u001b[39m\u001b[38;5;124mtext-embedding-ada-002\u001b[39m\u001b[38;5;124m\"\u001b[39m\n\u001b[0;32m      7\u001b[0m \u001b[38;5;66;03m# openai.Embedding.create() -> client.embeddings.create()\u001b[39;00m\n\u001b[1;32m----> 8\u001b[0m client \u001b[38;5;241m=\u001b[39m \u001b[43mAzureOpenAI\u001b[49m\u001b[43m(\u001b[49m\n\u001b[0;32m      9\u001b[0m \u001b[43m    \u001b[49m\u001b[43mapi_version\u001b[49m\u001b[38;5;241;43m=\u001b[39;49m\u001b[38;5;124;43m\"\u001b[39;49m\u001b[38;5;124;43m2023-07-01-preview\u001b[39;49m\u001b[38;5;124;43m\"\u001b[39;49m\u001b[43m,\u001b[49m\n\u001b[0;32m     10\u001b[0m \u001b[43m    \u001b[49m\u001b[43mazure_endpoint\u001b[49m\u001b[38;5;241;43m=\u001b[39;49m\u001b[43mopenai_service_endoint\u001b[49m\u001b[43m,\u001b[49m\n\u001b[0;32m     11\u001b[0m \u001b[43m    \u001b[49m\u001b[43mazure_deployment\u001b[49m\u001b[38;5;241;43m=\u001b[39;49m\u001b[43mopenai_deployment\u001b[49m\n\u001b[0;32m     12\u001b[0m \u001b[43m\u001b[49m\u001b[43m)\u001b[49m\n\u001b[0;32m     14\u001b[0m products \u001b[38;5;241m=\u001b[39m pd\u001b[38;5;241m.\u001b[39mread_csv(path)\n\u001b[0;32m     15\u001b[0m items \u001b[38;5;241m=\u001b[39m []\n",
-      "File \u001b[1;32me:\\github\\azure-samples\\contoso-chat-1\\.venv\\Lib\\site-packages\\openai\\lib\\azure.py:169\u001b[0m, in \u001b[0;36mAzureOpenAI.__init__\u001b[1;34m(self, api_version, azure_endpoint, azure_deployment, api_key, azure_ad_token, azure_ad_token_provider, organization, project, base_url, timeout, max_retries, default_headers, default_query, http_client, _strict_response_validation)\u001b[0m\n\u001b[0;32m    166\u001b[0m     azure_ad_token \u001b[38;5;241m=\u001b[39m os\u001b[38;5;241m.\u001b[39menviron\u001b[38;5;241m.\u001b[39mget(\u001b[38;5;124m\"\u001b[39m\u001b[38;5;124mAZURE_OPENAI_AD_TOKEN\u001b[39m\u001b[38;5;124m\"\u001b[39m)\n\u001b[0;32m    168\u001b[0m \u001b[38;5;28;01mif\u001b[39;00m api_key \u001b[38;5;129;01mis\u001b[39;00m \u001b[38;5;28;01mNone\u001b[39;00m \u001b[38;5;129;01mand\u001b[39;00m azure_ad_token \u001b[38;5;129;01mis\u001b[39;00m \u001b[38;5;28;01mNone\u001b[39;00m \u001b[38;5;129;01mand\u001b[39;00m azure_ad_token_provider \u001b[38;5;129;01mis\u001b[39;00m \u001b[38;5;28;01mNone\u001b[39;00m:\n\u001b[1;32m--> 169\u001b[0m     \u001b[38;5;28;01mraise\u001b[39;00m OpenAIError(\n\u001b[0;32m    170\u001b[0m         \u001b[38;5;124m\"\u001b[39m\u001b[38;5;124mMissing credentials. Please pass one of `api_key`, `azure_ad_token`, `azure_ad_token_provider`, or the `AZURE_OPENAI_API_KEY` or `AZURE_OPENAI_AD_TOKEN` environment variables.\u001b[39m\u001b[38;5;124m\"\u001b[39m\n\u001b[0;32m    171\u001b[0m     )\n\u001b[0;32m    173\u001b[0m \u001b[38;5;28;01mif\u001b[39;00m api_version \u001b[38;5;129;01mis\u001b[39;00m \u001b[38;5;28;01mNone\u001b[39;00m:\n\u001b[0;32m    174\u001b[0m     api_version \u001b[38;5;241m=\u001b[39m os\u001b[38;5;241m.\u001b[39menviron\u001b[38;5;241m.\u001b[39mget(\u001b[38;5;124m\"\u001b[39m\u001b[38;5;124mOPENAI_API_VERSION\u001b[39m\u001b[38;5;124m\"\u001b[39m)\n",
-      "\u001b[1;31mOpenAIError\u001b[0m: Missing credentials. Please pass one of `api_key`, `azure_ad_token`, `azure_ad_token_provider`, or the `AZURE_OPENAI_API_KEY` or `AZURE_OPENAI_AD_TOKEN` environment variables."
-     ]
-    }
-   ],
+   "outputs": [],
    "source": [
     "print(f\"indexing documents\")\n",
     "docs = gen_contoso_products(\"products.csv\")\n",

diff --git a/docs/workshop/docs/00-Before-You-Begin/index.md b/docs/workshop/docs/00-Before-You-Begin/index.md
@@ -1,5 +1,8 @@
 #  0️⃣ | Pre-Requisites
 
+!!! example "Microsoft AI Tour Attendees:  <br/> Are you currently in the instructor-led session on tour? [Get Started Here](./../01-Tour-Guide-Setup/01-setup.md) to save time."   
+
+
 !!! warning "To participate in this workshop you will need the following"
 
 1. **Your own laptop.**

diff --git a/docs/workshop/docs/01-Tour-Guide-Setup/01-setup.md b/docs/workshop/docs/01-Tour-Guide-Setup/01-setup.md
@@ -1,6 +1,8 @@
 # 1️⃣ | Getting Started: Instructor-Led Workshop
 
-Thie instructions are for participants of the instructor-led **"WRK550: Build a Retail Copilot Code-First on Azure AI"** workshop offered on the Microsoft AI Tour (2024-2025). 
+!!! example "Microsoft AI Tour Attendees:  <br/> Already launched the Skillable Lab and verified credentials? [Move Directly to Step 2](#2-set-up-your-dev-environment) to save time."   
+
+The instructions are for participants of the instructor-led **"WRK550: Build a Retail Copilot Code-First on Azure AI"** workshop offered on the Microsoft AI Tour (2024-2025). 
 
 If you're not at an AI Tour event right now, you can register for an upcoming event in a city near you.
 
@@ -40,7 +42,7 @@ The **WRK550 Lab** requires a Python development runtime (with package dependenc
 
 _In this section, we'll fork the sample repo to our personal profiles - then launch GitHub Codespaces to activate that environment with a Visual Studio Code editor, right in the browser_.
 
-### Step 1: Open GitHub in Tab 1️⃣
+### 2.1 Open GitHub in Tab 1️⃣
 
 The source code for the application used in this workshop is available on GitHub. Let's log into GitHub and copy a fork of the source code to your GitHub account.
 
@@ -66,7 +68,7 @@ The source code for the application used in this workshop is available on GitHub
 
 **✅ | CONGRATULATIONS!** - Your have a personal copy of the sample to explore!
 
-## Step 2: Launch Codespaces in Tab 2️⃣
+### 2.2: Launch Codespaces in Tab 2️⃣
 
 GitHub Codespaces will be our development environment for this workshop. Let's launch CodeSpaces now, starting from the fork of the `contoso-chat` repository you just created.
 
@@ -80,7 +82,7 @@ GitHub Codespaces will be our development environment for this workshop. Let's l
 
 1. This will launch a new browser tab (Tab 2️⃣). It will take a few minutes for the CodeSpace to be ready for use. In the meantime, continue with the next steps. 
 
-## Step 3: Open Azure Portal in Tab 3️⃣
+### 2.3: Open Azure Portal in Tab 3️⃣
 
 1. Open a new browser tab (Tab 3️⃣)
 1. Navigate to the [Azure Portal](https://portal.azure.com):
@@ -96,7 +98,7 @@ GitHub Codespaces will be our development environment for this workshop. Let's l
 
 **✅ | CONGRATULATIONS!** - Your Azure Infra is Provisioned!
 
-## Step 4: Open Azure AI Studio in Tab 4️⃣
+### 2.4 Open Azure AI Studio in Tab 4️⃣
 
 1. Open a new browser tab = Tab 4️⃣
 1. Navigate to the [Azure AI Studio](https://ai.azure.com?feature.customportal=false#home):
@@ -107,19 +109,21 @@ GitHub Codespaces will be our development environment for this workshop. Let's l
 1. **Click** `Sign in` -- you will auto-login with the Azure credentials used to sign into the portal.
 1. Under Management in the left pane, **click** `All hubs`. One hub resource will be listed.
 
+    !!! warning "The AI Studio UI is evolving. Instead of `All hubs` you may see an `All resources` item in the left pane instead, with 2 resources listed in the right - one of which should be a _hub_ resource."
+
     !!! info "An [AI Studio hub](https://learn.microsoft.com/azure/ai-studio/concepts/ai-resources) collects resources like generative AI endpoints that can be shared between projects."
 
 1. **Click** the listed hub resource name to display it. **Check:** 1 project is listed under `Projects`.
 
     !!! info "An [AI Studio project](https://learn.microsoft.com/azure/ai-studio/how-to/create-projects?tabs=ai-studio) is used to organize your work when building applications."
 
-1. Under "Shared Resources" in the left pane, **click** `Deployments`. **Check:** 4 models are listed under `aoai-connection` 
+1. Under "Shared Resources" in the left pane, **click** `Deployments`. The right pane should show two `*-connection` groups. **Check:** 4 models are listed under each connection. 
 
     !!! info "The Model Deployments section lists Generative AI models deployed to this Hub. For this application, we will use the chat completion models `gpt-4` and `gpt-35-turbo`, and the embedding model `text-embedding-ada-002`." 
 
 **✅ | CONGRATULATIONS!** - Your Azure AI Project is ready!
 
-## Step 5: View Container Apps Endpoint in Tab 5️⃣
+### 2.5: View Container Apps Endpoint in Tab 5️⃣
 
 [Azure Container Apps](https://learn.microsoft.com/azure/container-apps/overview) will host the endpoint used to serve the Contoso Chat application on the Contoso Outdoors website. We have deployed a container app, but have not yet pushed code to it. 
 
@@ -133,7 +137,7 @@ GitHub Codespaces will be our development environment for this workshop. Let's l
 
 **✅ | CONGRATULATIONS!** - Your ACA Endpoint is ready!
 
-## Step 6: Make sure CodeSpaces has completed launching
+## 3. Make sure CodeSpaces has completed launching
 
 1. Return to your GitHub Codespaces tab, Tab 2️⃣.
 

diff --git a/docs/workshop/docs/01-Tour-Guide-Setup/02-validate.md b/docs/workshop/docs/01-Tour-Guide-Setup/02-validate.md
@@ -40,7 +40,7 @@ prompty --version
 fastapi --version
 ```
 
-!!! tip "These tools have been installed into the GitHub CodeSpaces dev container for you. If you want to run this workshop in another environment like your dekstop PC, you will have to install them first."
+!!! tip "These tools have been installed into the GitHub CodeSpaces dev container for you. If you want to run this workshop in another environment like your desktop PC, you will have to install them first."
 
 ## 2. Authenticate with Azure
 
@@ -56,7 +56,7 @@ From the VS Code Online Terminal pane (in Tab 2️⃣):
 
 1. Copy the 8-character code shown to your clipboard, then control-click the link to visit [https://microsoft.com/devicelogin](https://microsoft.com/devicelogin) in a new browser tab.
 
-1. Select the account with Username and from Skillable Lab window. Click "Continue" at the `are you sure?` prompt, and then close the tab.
+1. Select the account with the Username shown in the Skillable Lab window. Click "Continue" at the `are you sure?` prompt, and then close the tab
 
 1. Back in the Terminal, press Enter to select the default presented subscription and tenant.
 

diff --git a/docs/workshop/docs/03-Workshop-Build/03-infra.md b/docs/workshop/docs/03-Workshop-Build/03-infra.md
@@ -2,11 +2,16 @@
 
 !!! success "Let's Review where we are right now"
 
+    ![Dev Workflow](./../img/workshop-developer-flow.png)
+
+    Looking at our end-to-end developer workflow, we completed the `PROVISION` and `SETUP` stages. Before we dive into the `IDEATE` stage, let's take a minute to validate that we are ready to begin development.
+
     1. We set up our development environment (GitHub Codespaces)
     1. We provisioned our infrastructure (Azure Resources)
     1. We connected our dev environment to our infra (Auth & Env Vars)
     1. We used SDK and CLI tools to push updates to infra (Data & App)
 
+---
 
 _In this section, we'll take a minute to understand what our Azure infrastructure looks like, and validate that the resources are deployed and initialized correctly. Here's a reminder of the Azure Application Architecure showing the key resources used. Let's dive in._
 
@@ -55,16 +60,38 @@ When iterating on a prototype application, we start with manual testing - using
     - enter `2` for **customer_id**
     - enter `[]` for **chat_history**
     - enter **Execute** to run the endpoint with the provided parameters.
+
+You will get a response body with `question`, `answer` and `context` components. 
 
-You will get a response body with `question`, `answer` and `context` components.
+- **Check** `question` -  is the customer's question the same as that typed in the chat window on the Contoso Outdoor website
+- **Check** `answer` -  is the chatbot's response to the customer's `question`, as generated by this RAG application
+- **Check** `context` - is the additional information provided to the Generative AI model being used by it used to ground its answer.
+    - In this app, that includes information about products relevant to the customer question.
+    - The products selected may depend on `customer_id` and the associated order history. 
+    - The web app provides `chat_history` from the chat window - which can serve as additional context that the model can use to ground the response.
+
+!!! note "Exercise → Repeat exercise above with a different customer ID number. How did the response change?"
 
-* `question` is the customer's question as typed in the chat window on the Contoso Outdoor website
-* `answer` is the chatbot's response to the customer's `question`, as generated by this RAG application
-* `context` is the additional information provided to the Generative AI model, which it used to ground its answer. In this app, that includes information about products relevant to the customer question. The products selected may depend on the `customer_id` and their associated order history. 
-* The web app provides the `chat_history` from the chat window, which provides additional context for the generative AI model to ground its response.
 
 ✅ | Your Contoso Chat AI is deployed - and works with valid inputs!
 
+## Let's Connect The Dots
+
+!!! info "Recall that the [Retrieval Augmented Generation](https://learn.microsoft.com/en-us/azure/ai-studio/concepts/retrieval-augmented-generation#how-does-rag-work) works by *retrieving* relevant knowledge from your data stores, and _augmenting_ the user query with it to create an enhanced prompt - which _generates_ the final response."
+
+To implement this RAG pattern, we need to execute three steps:
+
+1. **Setup data sources** and populate them with our data (product catalog, customer orders)
+1. **Create [indexes](https://learn.microsoft.com/azure/ai-studio/concepts/retrieval-augmented-generation#how-does-rag-work)** for efficient information retrieval by LLMs (e.g., find matching products)
+1. **Connect our Azure AI project** to access data/indexes code-first, for use in processing steps.
+
+In the previous section we setup the data sources (provisioning infra) and populated them with data (post-provisioning scripts) as follows:
+
+1. **Azure CosmosDB** - loaded **12 records** from `data/customer_info`, got _customers_ database.
+1. **Azure AI Search** - loaded **20 records** from `data/product_info`, got _contoso-products_ index.
+
+In this section, we verified these steps and checked off the first two items on our RAG checklist above. In the next section (Ideation with Prompty) we'll see how we achieve the third item with a code-first approach that makes use of the Azure AI Search, Azure CosmosDB and Azure OpenAI services through their Azure SDKs.
+
 ---
 
 _Now you understand the application architecture, and have a sense for the retail copilot API, it's time to dig into the codebase and understand the three stages of our GenAIOps workflow - ideation, evaluation, and operationalization_.