|
| 1 | +# Deployment Guide |
| 2 | + |
| 3 | +## **Pre-requisites** |
| 4 | + |
| 5 | +To deploy this solution, ensure you have access to an [Azure subscription](https://azure.microsoft.com/free/) with the necessary permissions to create **resource groups, resources, app registrations, and assign roles at the resource group level**. This should include Contributor role at the subscription level and Role Based Access Control (RBAC) permissions at the subscription and/or resource group level. Follow the steps in [Azure Account Set Up](./AzureAccountSetUp.md). |
| 6 | + |
| 7 | +Check the [Azure Products by Region](https://azure.microsoft.com/en-us/explore/global-infrastructure/products-by-region/?products=all®ions=all) page and select a **region** where the following services are available: |
| 8 | + |
| 9 | +- [Azure AI Foundry](https://learn.microsoft.com/en-us/azure/ai-foundry) |
| 10 | +- [Azure AI Content Understanding Service](https://learn.microsoft.com/en-us/azure/ai-services/content-understanding/) |
| 11 | +- [Azure OpenAI Service](https://learn.microsoft.com/en-us/azure/ai-services/openai/) |
| 12 | +- [GPT Model Capacity](https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/models) |
| 13 | +- [Azure AI Search](https://learn.microsoft.com/en-us/azure/search/search-what-is-azure-search) |
| 14 | +- [Azure SQL Database](https://learn.microsoft.com/en-us/azure/azure-sql/database/sql-database-paas-overview) |
| 15 | +- [Azure Cosmos DB](https://learn.microsoft.com/en-us/azure/cosmos-db/introduction) |
| 16 | +- [Azure Container Apps](https://learn.microsoft.com/en-us/azure/container-apps/) |
| 17 | +- [Azure Container Registry](https://learn.microsoft.com/en-us/azure/container-registry/) |
| 18 | +- [Embedding Deployment Capacity](https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/models#embedding-models) |
| 19 | +- [Azure Semantic Search](./docs/AzureSemanticSearchRegion.md) |
| 20 | + |
| 21 | +Here are some example regions where the services are available: East US, East US2, Australia East, UK South, France Central. |
| 22 | + |
| 23 | +### **Important Note for PowerShell Users** |
| 24 | + |
| 25 | +If you encounter issues running PowerShell scripts due to the policy of not being digitally signed, you can temporarily adjust the `ExecutionPolicy` by running the following command in an elevated PowerShell session: |
| 26 | + |
| 27 | +```powershell |
| 28 | +Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass |
| 29 | +``` |
| 30 | + |
| 31 | +This will allow the scripts to run for the current session without permanently changing your system's policy. |
| 32 | + |
| 33 | +## Deployment Options & Steps |
| 34 | + |
| 35 | +Pick from the options below to see step-by-step instructions for GitHub Codespaces, VS Code Dev Containers, Local Environments, and Bicep deployments. |
| 36 | + |
| 37 | +| [](https://codespaces.new/microsoft/Conversation-Knowledge-Mining-Solution-Accelerator) | [](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/microsoft/Conversation-Knowledge-Mining-Solution-Accelerator) | |
| 38 | +|---|---| |
| 39 | + |
| 40 | +<details> |
| 41 | + <summary><b>Deploy in GitHub Codespaces</b></summary> |
| 42 | + |
| 43 | +### GitHub Codespaces |
| 44 | + |
| 45 | +You can run this solution using GitHub Codespaces. The button will open a web-based VS Code instance in your browser: |
| 46 | + |
| 47 | +1. Open the solution accelerator (this may take several minutes): |
| 48 | + |
| 49 | + [](https://codespaces.new/microsoft/Conversation-Knowledge-Mining-Solution-Accelerator) |
| 50 | + |
| 51 | +2. Accept the default values on the create Codespaces page. |
| 52 | +3. Open a terminal window if it is not already open. |
| 53 | +4. Continue with the [deploying steps](#deploying-with-azd). |
| 54 | + |
| 55 | +</details> |
| 56 | + |
| 57 | +<details> |
| 58 | + <summary><b>Deploy in VS Code</b></summary> |
| 59 | + |
| 60 | +### VS Code Dev Containers |
| 61 | + |
| 62 | +You can run this solution in VS Code Dev Containers, which will open the project in your local VS Code using the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers): |
| 63 | + |
| 64 | +1. Start Docker Desktop (install it if not already installed). |
| 65 | +2. Open the project: |
| 66 | + |
| 67 | + [](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/microsoft/Conversation-Knowledge-Mining-Solution-Accelerator) |
| 68 | + |
| 69 | +3. In the VS Code window that opens, once the project files show up (this may take several minutes), open a terminal window. |
| 70 | +4. Continue with the [deploying steps](#deploying-with-azd). |
| 71 | + |
| 72 | +</details> |
| 73 | + |
| 74 | +<details> |
| 75 | + <summary><b>Deploy in your local Environment</b></summary> |
| 76 | + |
| 77 | +### Local Environment |
| 78 | + |
| 79 | +If you're not using one of the above options for opening the project, then you'll need to: |
| 80 | + |
| 81 | +1. Make sure the following tools are installed: |
| 82 | + - [PowerShell](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell?view=powershell-7.5) <small>(v7.0+)</small> - available for Windows, macOS, and Linux. |
| 83 | + - [Azure Developer CLI (azd)](https://aka.ms/install-azd) |
| 84 | + - [Python 3.9+](https://www.python.org/downloads/) |
| 85 | + - [Docker Desktop](https://www.docker.com/products/docker-desktop/) |
| 86 | + - [Git](https://git-scm.com/downloads) |
| 87 | + |
| 88 | +2. Clone the repository or download the project code via command-line: |
| 89 | + |
| 90 | + ```shell |
| 91 | + azd init -t microsoft/Conversation-Knowledge-Mining-Solution-Accelerator/ |
| 92 | + ``` |
| 93 | + |
| 94 | +3. Open the project folder in your terminal or editor. |
| 95 | +4. Continue with the [deploying steps](#deploying-with-azd). |
| 96 | + |
| 97 | +</details> |
| 98 | + |
| 99 | +<br/> |
| 100 | + |
| 101 | +Consider the following settings during your deployment to modify specific settings: |
| 102 | + |
| 103 | +<details> |
| 104 | + <summary><b>Configurable Deployment Settings</b></summary> |
| 105 | + |
| 106 | +When you start the deployment, most parameters will have **default values**, but you can update the following settings: |
| 107 | + |
| 108 | +| **Setting** | **Description** | **Default value** | |
| 109 | +|------------|----------------|------------| |
| 110 | +| **Azure Region** | The region where resources will be created. | eastus | |
| 111 | +| **Environment Name** | A **3-20 character alphanumeric value** used to generate a unique ID to prefix the resources. | kmtemplate | |
| 112 | +| **Azure AI Content Understanding Location** | Select from a drop-down list of values. | swedencentral | |
| 113 | +| **Secondary Location** | A **less busy** region for **Azure SQL and Azure Cosmos DB**, useful in case of availability constraints. | eastus2 | |
| 114 | +| **Deployment Type** | Select from a drop-down list. | GlobalStandard | |
| 115 | +| **GPT Model** | Choose from **gpt-4, gpt-4o, gpt-4o-mini** | gpt-4o-mini | |
| 116 | +| **GPT Model Deployment Capacity** | Configure capacity for **GPT models**. | 30k | |
| 117 | +| **Embedding Model** | Default: **text-embedding-ada-002**. | text-embedding-ada-002 | |
| 118 | +| **Embedding Model Capacity** | Set the capacity for **embedding models**. | 80k | |
| 119 | + |
| 120 | +</details> |
| 121 | + |
| 122 | +<details> |
| 123 | + <summary><b>[Optional] Quota Recommendations</b></summary> |
| 124 | + |
| 125 | +By default, the **Gpt-4o-mini model capacity** in deployment is set to **30k tokens**, so we recommend updating the following: |
| 126 | + |
| 127 | +> **For Global Standard | GPT-4o-mini - increase the capacity to at least 150k tokens post-deployment for optimal performance.** |
| 128 | + |
| 129 | +Depending on your subscription quota and capacity, you can [adjust quota settings](AzureGPTQuotaSettings.md) to better meet your specific needs. You can also [adjust the deployment parameters](CustomizingAzdParameters.md) for additional optimization. |
| 130 | + |
| 131 | +**⚠️ Warning:** Insufficient quota can cause deployment errors. Please ensure you have the recommended capacity or request additional capacity before deploying this solution. |
| 132 | + |
| 133 | +</details> |
| 134 | + |
| 135 | +### Deploying with AZD |
| 136 | + |
| 137 | +Once you've opened the project in [Codespaces](#github-codespaces), [Dev Containers](#vs-code-dev-containers), or [locally](#local-environment), you can deploy it to Azure by following these steps: |
| 138 | +
|
| 139 | +1. Login to Azure: |
| 140 | +
|
| 141 | + ```shell |
| 142 | + azd auth login |
| 143 | + ``` |
| 144 | +
|
| 145 | + #### To authenticate with Azure Developer CLI (`azd`), use the following command with your **Tenant ID**: |
| 146 | +
|
| 147 | + ```sh |
| 148 | + azd auth login --tenant-id <tenant-id> |
| 149 | + ``` |
| 150 | +
|
| 151 | +2. Provision and deploy all the resources: |
| 152 | +
|
| 153 | + ```shell |
| 154 | + azd up |
| 155 | + ``` |
| 156 | +
|
| 157 | +3. Provide an `azd` environment name (e.g., "ckmapp"). |
| 158 | +4. Select a subscription from your Azure account and choose a location that has quota for all the resources. |
| 159 | + -- This deployment will take *7-10 minutes* to provision the resources in your account and set up the solution with sample data. |
| 160 | + - If you encounter an error or timeout during deployment, changing the location may help, as there could be availability constraints for the resources. |
| 161 | +
|
| 162 | +5. Once the deployment has completed successfully, open the [Azure Portal](https://portal.azure.com/), go to the deployed resource group, find the App Service, and get the app URL from `Default domain`. |
| 163 | +
|
| 164 | +6. If you are done trying out the application, you can delete the resources by running `azd down`. |
| 165 | +
|
| 166 | +### Publishing Local Build Container to Azure Container Registry |
| 167 | +
|
| 168 | +If you need to rebuild the source code and push the updated container to the deployed Azure Container Registry, follow these steps: |
| 169 | +
|
| 170 | +1. Set the environment variable `USE_LOCAL_BUILD` to `True`: |
| 171 | +
|
| 172 | + - **Linux/macOS**: |
| 173 | + ```bash |
| 174 | + export USE_LOCAL_BUILD=True |
| 175 | + ``` |
| 176 | +
|
| 177 | + - **Windows (PowerShell)**: |
| 178 | + ```powershell |
| 179 | + $env:USE_LOCAL_BUILD = $true |
| 180 | + ``` |
| 181 | +2. Run the `az login` command |
| 182 | + ```bash |
| 183 | + az login |
| 184 | + ``` |
| 185 | +
|
| 186 | +3. Run the `azd up` command again to rebuild and push the updated container: |
| 187 | + ```bash |
| 188 | + azd up |
| 189 | + ``` |
| 190 | +
|
| 191 | +This will rebuild the source code, package it into a container, and push it to the Azure Container Registry associated with your deployment. |
| 192 | +
|
| 193 | +## Post Deployment Steps |
| 194 | +
|
| 195 | +1. **Add App Authentication** |
| 196 | + |
| 197 | + Follow steps in [App Authentication](./AppAuthentication.md) to configure authentication in app service. Note: Authentication changes can take up to 10 minutes |
| 198 | +
|
| 199 | +2. **Deleting Resources After a Failed Deployment** |
| 200 | +
|
| 201 | + - Follow steps in [Delete Resource Group](./DeleteResourceGroup.md) if your deployment fails and/or you need to clean up the resources. |
| 202 | +
|
| 203 | +## Sample Questions |
| 204 | +
|
| 205 | +To help you get started, here are some **Sample Questions** you can ask in the app: |
| 206 | +
|
| 207 | +- Total number of calls by date for the last 7 days |
| 208 | +- Show average handling time by topics in minutes |
| 209 | +- What are the top 7 challenges users reported? |
| 210 | +- Give a summary of billing issues |
| 211 | +- When customers call in about unexpected charges, what types of charges are they seeing? |
| 212 | +
|
| 213 | +These questions serve as a great starting point to explore insights from the data. |
0 commit comments