Updated for / MSIgnite Lab 401 (Azure-Samples#199)

* refactor 1 / organize into tabs * refactor / v2 docs * initial lab401-skillable-panel * fox / skillable instructions * fix / skillable instructions * forking sample to my profile * forking sample to my profile * refactor / nav sections * fix / workshop docs reorganized * update devcontainer.json * fix / AIServices
jmanywhere · Nov 6, 2024 · 1da6b6f · 1da6b6f
1 parent a6a742e
commit 1da6b6f
Show file tree

Hide file tree

Showing 67 changed files with 2,002 additions and 1,205 deletions.
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
@@ -13,7 +13,11 @@
         },
         "ghcr.io/devcontainers/features/git:1": {},
         "ghcr.io/azure/azure-dev/azd:latest": {},
-        "ghcr.io/devcontainers/features/docker-in-docker:2": {}
+        "ghcr.io/devcontainers/features/docker-in-docker:2": {},
+        "ghcr.io/devcontainers/features/github-cli:1": {},
+        "ghcr.io/devcontainers/features/node:1": {
+            "version": "22.8.0"
+        }
     },
     "customizations": {
         "vscode": {
@@ -26,5 +30,9 @@
                 "rogalmic.bash-debug"
             ]
         }
-    }
+    },
+    "postCreateCommand": "bash .devcontainer/setup.sh",
+    "forwardPorts": [
+        8000
+    ]
 }
diff --git a/.devcontainer/setup.sh b/.devcontainer/setup.sh
@@ -0,0 +1,11 @@
+#!/bin/bash
+
+# Exit immediately if a command exits with a non-zero status
+set -e
+
+# Install NPM modules for Contoso Web UI
+echo "Installing NPM modules for Contoso Web UI"
+# pushd ./src/web
+# npm install
+# npx next telemetry disable
+# popd
diff --git a/...shop/docs/01-Tour-Guide-Setup/.env.sample → ...docs-orig/01-Tour-Guide-Setup/.env.sample b/...shop/docs/01-Tour-Guide-Setup/.env.sample → ...docs-orig/01-Tour-Guide-Setup/.env.sample
diff --git a/...shop/docs/01-Tour-Guide-Setup/01-setup.md → ...docs-orig/01-Tour-Guide-Setup/01-setup.md b/...shop/docs/01-Tour-Guide-Setup/01-setup.md → ...docs-orig/01-Tour-Guide-Setup/01-setup.md
diff --git a/...p/docs/01-Tour-Guide-Setup/02-validate.md → ...s-orig/01-Tour-Guide-Setup/02-validate.md b/...p/docs/01-Tour-Guide-Setup/02-validate.md → ...s-orig/01-Tour-Guide-Setup/02-validate.md
diff --git a/...shop/docs/02-Self-Guide-Setup/01-setup.md → ...docs-orig/02-Self-Guide-Setup/01-setup.md b/...shop/docs/02-Self-Guide-Setup/01-setup.md → ...docs-orig/02-Self-Guide-Setup/01-setup.md
diff --git a/.../docs/02-Self-Guide-Setup/02-provision.md → ...-orig/02-Self-Guide-Setup/02-provision.md b/.../docs/02-Self-Guide-Setup/02-provision.md → ...-orig/02-Self-Guide-Setup/02-provision.md
diff --git a/docs/workshop/docs-orig/img/Evaluation Runs.png b/docs/workshop/docs-orig/img/Evaluation Runs.png
diff --git a/docs/workshop/docs-orig/img/aca-architecture.png b/docs/workshop/docs-orig/img/aca-architecture.png
diff --git a/docs/workshop/docs-orig/img/branch.png b/docs/workshop/docs-orig/img/branch.png
diff --git a/docs/workshop/docs-orig/img/chat-ai.png b/docs/workshop/docs-orig/img/chat-ai.png
diff --git a/docs/workshop/docs-orig/img/chat-ui.png b/docs/workshop/docs-orig/img/chat-ui.png
diff --git a/docs/workshop/docs-orig/img/gen-ai-ops.png b/docs/workshop/docs-orig/img/gen-ai-ops.png
diff --git a/docs/workshop/docs-orig/img/logo.svg b/docs/workshop/docs-orig/img/logo.svg
diff --git a/docs/workshop/docs-orig/img/prompty-auth.png b/docs/workshop/docs-orig/img/prompty-auth.png
diff --git a/docs/workshop/docs-orig/img/prompty-logo.png b/docs/workshop/docs-orig/img/prompty-logo.png
diff --git a/docs/workshop/docs-orig/img/rag-design-pattern.png b/docs/workshop/docs-orig/img/rag-design-pattern.png
diff --git a/docs/workshop/docs-orig/img/tabular-eval.png b/docs/workshop/docs-orig/img/tabular-eval.png
diff --git a/docs/workshop/docs-orig/img/workshop-developer-flow.png b/docs/workshop/docs-orig/img/workshop-developer-flow.png
diff --git a/docs/workshop/docs-orig/img/wrk-port-popup.png b/docs/workshop/docs-orig/img/wrk-port-popup.png
diff --git a/docs/workshop/docs-orig/img/wrk-prompty-login.png b/docs/workshop/docs-orig/img/wrk-prompty-login.png
diff --git a/docs/workshop/docs-orig/img/wrk-prompty-menubar.png b/docs/workshop/docs-orig/img/wrk-prompty-menubar.png
diff --git a/docs/workshop/docs-orig/img/wrk-starred.png b/docs/workshop/docs-orig/img/wrk-starred.png
diff --git a/docs/workshop/docs-orig/img/wrk-venv.png b/docs/workshop/docs-orig/img/wrk-venv.png
diff --git a/docs/workshop/docs-orig/index.md b/docs/workshop/docs-orig/index.md
@@ -0,0 +1,79 @@
+# Build a Retail Copilot Code-First on Azure AI
+
+!!! example "Microsoft AI Tour Attendees:  <br/> To get started with this workshop, [make sure you have everything you need](00-Before-You-Begin/index.md) to start building."   
+
+This website contains the step-by-step instructions for a hands-on workshop that teaches you how to **build, evaluate, and deploy a retail copilot code-first on Azure AI**. 
+
+- Our solution use the [Retrieval Augmented Generation (RAG) pattern](https://learn.microsoft.com/azure/ai-studio/concepts/retrieval-augmented-generation) to ground chat AI responses in the retailer's product catalog and cusomer data.
+- Our implementation uses [Prompty](https://prompty.ai) for ideation, [Azure AI Studio](https://ai.azure.com) as the platform for code-first copilotdevelopment, and [Azure Container Apps](https://aka.ms/azcontainerapps) for hosting the deployed copilot.
+
+In this section, we introduce the application scenario (Contoso Chat), review the design pattern used (RAG) and understand how it maps to our application architecture (on Azure AI). We'll wrap the section by understanding the application lifecycle (GenAIOps) and the three stages for end-to-end development that we will follow in this workshop.
+
+---
+
+## 1. The App Scenario
+
+**Contoso Outdoors** is an enterprise retailer that sells a wide variety of hiking and camping equipment to outdoor adventurer through their website. Customers visiting the site often call the customer support line with requests for product information or recommendations, before making their purchases. The retailer decides to build and integrate an AI-based _customer support agent_ (retail copilot) to handle these queries right from their website, for efficiency.
+
+![Contoso Chat UI](./img/chat-ui.png)
+
+**Contoso Chat** is the chat AI implementation (_backend_) for the retail copilot experience. It has a hosted API (_endpoint_) that the chat UI (_frontend_) can interact with to process user requests. Customers can now ask questions in a conversational format, using natural language, and get valid responses grounded in product data and their own purchase history.
+
+![Contoso Chat AI](./img/chat-ai.png)
+
+## 2. The RAG Pattern
+
+Foundation large language models are trained on massive quantities of public data, giving them the ability to answer general questions effectively. However, our retail copilot needs responses grounded in _private data_ that exists in the retailer's data stores. _Retrieval Augmented Generation_ (RAG) is a design pattern that provides a popular solution to this challenge with this workflow:
+
+1. The user query arrives at our copilot implementation via the endpoint (API).
+1. The copilot sends the text query to a **retrieval** service which vectorizes it for efficiency.
+1. It uses this vector to query a search index for matching results (e.g., based on similarity)
+1. The retrieval service returns results to the copilot, potentially with semantic ranking applied.
+1. The copilot **augments** the user prompt with this knowledge, and invokes the chat model.
+1. The chat model now **generates** responses _grounded_ in the provided knowledge.
+
+![RAG](./img/rag-design-pattern.png)
+
+## 3. The App Architecture
+
+Implementing this design pattern requires these architectural components:
+
+ - an **information retrieval** service (data indexing, similarity search, semantic ranking)
+ - a **database** service for storing other data (customer orders)
+ - a **model deployments** capability (for chat, embeddings - and AI-assisted evaluation)
+ - a **copilot hosting** capability (for real-world access to deployed endpoint)
+
+The corresponding Azure AI application architecture for the Contoso Chat retail copilot is shown below. The copilot is deployed to Azure Container Apps, providing a hosted API endpoint for client integration. The copilot processes incoming requests with the help of:
+
+ - **Azure OpenAI Services**  - provides model deployments for chat and text embeddings
+ - **Azure CosmosDB**  - stores the customer order data (JSON) in a noSQL database
+ - **Azure AI Search**  - indexes the product catalog with search-retrieval capability. 
+
+![ACA Architecture](./img/aca-architecture.png)
+
+The copilot _orchestrates_ the steps of the RAG workflow using **Prompty** assets (configured with required Azure OpenAI models) executed in a Prompty runtime (Python). It supports multi-turn conversations and responsible AI practices to meet response quality and safety requirements.
+
+## 4. The App Lifecycle
+
+Building generative AI applications requires an iterative process of refinement from _prompt_ to _production_. The application  lifecycle (GenAIOps) is best illustrated by the three stages shown:
+
+1. **Ideation** - involves building the initial prototype, validating it manually with a test prompt.
+2. **Evaluation** - involves assessing it for quality and safety with large, diverse test datasets.
+3. **Operationalization** - involves deploying it for real-world usage & monitoring it for insights.
+
+![GenAIOps](./img/gen-ai-ops.png)
+
+In our workshop, you willl see the development workflow organized into sections that mimic this lifecycle - giving you a more intuitive sense for how you can iteratively go from promt to production, code-first, with Azure AI.
+
+## 5. Related Resources
+
+1. **Prompty** | [Documentation](https://prompty.ai) · [Specification](https://github.com/microsoft/prompty/blob/main/Prompty.yaml)  · [Tooling](https://marketplace.visualstudio.com/items?itemName=ms-toolsai.prompty) · [SDK](https://pypi.org/project/prompty/)
+1. **Azure AI Studio**  | [Documentation](https://learn.microsoft.com/en-us/azure/ai-studio/)  · [Architecture](https://learn.microsoft.com/azure/ai-studio/concepts/architecture) · [SDKs](https://learn.microsoft.com/azure/ai-studio/how-to/develop/sdk-overview) ·  [Evaluation](https://learn.microsoft.com/azure/ai-studio/how-to/evaluate-generative-ai-app)
+1. **Azure AI Search** | [Documentation](https://learn.microsoft.com/azure/search/)  · [Semantic Ranking](https://learn.microsoft.com/azure/search/semantic-search-overview) 
+1. **Azure Container Apps**  | [Azure Container Apps](https://learn.microsoft.com/azure/container-apps/)  · [Deploy from code](https://learn.microsoft.com/en-us/azure/container-apps/quickstart-repo-to-cloud?tabs=bash%2Ccsharp&pivots=with-dockerfile)
+1. **Responsible AI**  | [Overview](https://www.microsoft.com/ai/responsible-ai)  · [With AI Services](https://learn.microsoft.com/en-us/azure/ai-services/responsible-use-of-ai-overview?context=%2Fazure%2Fai-studio%2Fcontext%2Fcontext)  · [Azure AI Content Safety](https://learn.microsoft.com/en-us/azure/ai-services/content-safety/)
+
+
+---
+
+!!! example "To get started with this workshop, [make sure you have everything you need](00-Before-You-Begin/index.md) to start building."
diff --git a/docs/workshop/docs/00-Before-You-Begin/index.md b/docs/workshop/docs/00-Before-You-Begin/index.md
diff --git a/docs/workshop/docs/01-Introduction/01-App-Scenario.md b/docs/workshop/docs/01-Introduction/01-App-Scenario.md
@@ -0,0 +1,19 @@
+# 1. The App Scenario
+
+
+The workshop teaches you to **build, evaluate, and deploy a retail copilot** code-first on Azure AI. The application scenario involves an enterprise retailer **frontend** (Contoso Web app) integrated with a custom copilot **backend** (Contoso Chat app), to provide a chat-based customer support experience to users. *Click each tab below, to learn more!*
+
+---
+
+=== "Contoso Web (Chat UI)"
+
+    **Contoso Outdoors** is an enterprise retailer that sells a wide variety of hiking and camping equipment to outdoor adventurer through their website. Customers visiting the site often call the customer support line with requests for product information or recommendations, before making their purchases. The retailer decides to build and integrate an AI-based _customer support agent_ (retail copilot) to handle these queries right from their website, for efficiency.
+
+    ![Contoso Chat UI](./../img/chat-ui.png)
+
+=== "Contoso Chat (Chat AI)"
+
+    **Contoso Chat** is the chat AI implementation (_backend_) for the retail copilot experience. It has a hosted API (_endpoint_) that the chat UI (_frontend_) can interact with to process user requests. Customers can now ask questions in a conversational format, using natural language, and get valid responses grounded in product data and their own purchase history.
+
+    ![Contoso Chat AI](./../img/chat-ai.png)
+
diff --git a/docs/workshop/docs/01-Introduction/02-RAG-Pattern.md b/docs/workshop/docs/01-Introduction/02-RAG-Pattern.md
@@ -0,0 +1,43 @@
+# 2. The RAG Pattern
+
+The workshop teaches you to **build, evaluate, and deploy a retail copilot** code-first on Azure AI - using the _Retrieval Augmented Generation_ (RAG) design pattern to make sure that our copilot responses are grounded in the (private) data maintained by the enterprise, for this application.
+
+![RAG](./../img/rag-design-pattern.png)
+
+
+Let's learn how this design pattern works in the context of our Contoso Chat application. Click on the tabs in order, to understand the sequence of events shown in the figure above.
+
+---
+
+=== "1. Get Query"
+
+    !!! info "The user query arrives at our copilot implementation via the endpoint (API)"
+
+    Our deployed Contoso Chat application is exposed as a hosted API endpoint using Azure Container Apps. The inoming "user query" has 3 components: the user _question_ (text input), the user's _customer ID_ (text input), and an optional _chat history_ (object array).
+
+    The API server extracts these parameters from the incoming request, and invokes the Contoso Chat application - starting the workflow reflecting this RAG design pattern.
+
+=== "2. Vectorize Query" 
+
+    !!! info "The copilot sends the text query to a **retrieval** service after first vectorizing it."
+
+    The Contoso Chat application converts the text question into a vectorized query using a Large Language "Embedding" Model (e.g., Azure Open AI `text-embedding-ada-002`). This is then sent to the information retrieval service (e.g., Azure AI Search) in the next step.
+
+=== "3. **Retrieve** Matches"
+
+    !!! info "The retrieval service uses the vectorized query to return matching results based on similarity"
+
+    The information retrieval service maintains a search index for relevant information (here, for our product catalog). In this step, we use the vectorized query from the previous step to find and return _matching product results_ based on vector similarity. The information retrieval service can also use features like _semantic ranking_ to order the returned results.
+
+=== "4. **Augment** Query"
+
+    !!! info "The copilot **augments** the question with this knowledge for an enhanced _model prompt_."
+
+    The Contoso Chat application combines the user's original _question_ with returned "documents" from the information retrieval service, to create an enhanced _model prompt_. This is made easier using prompt template technologies (e.g., Prompty) with placeholders - for chat history, retrieved documents, and customer profile information - that are filled in at this step.
+
+
+=== "3. **Generate** Response"
+
+    !!! info "The chat model is invoked with this prompt, generating a grounded response as the returned result."
+
+    This enhanced prompt is now sent to the Large Language "chat" model (e.g., Azure OpenAI `gpt-35-turbo` or `gpt-4o`) which sees the enhanced prompt (retrieved documents, customer profile data, chat history) as _grounding_ context for generating the final response, improving the quality (e.g., relevance, groundedness) of results returned from Contoso Chat.