|
1 | | -# Deployment Guide |
2 | | - |
3 | | -## **Pre-requisites** |
4 | | - |
5 | | -To deploy this solution accelerator, ensure you have access to an [Azure subscription](https://azure.microsoft.com/free/) with the necessary permissions to create **resource groups, resources, and assign roles at the 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/table) page and select a **region** where the following services are available: |
8 | | - |
9 | | -- [Azure OpenAI](https://learn.microsoft.com/en-us/azure/ai-services/openai/) |
10 | | -- [Azure AI Search](https://learn.microsoft.com/en-us/azure/search/) |
11 | | -- [Azure App Service](https://learn.microsoft.com/en-us/azure/app-service/) |
12 | | -- [Azure SQL Database](https://learn.microsoft.com/en-us/azure/azure-sql/) |
13 | | -- [Microsoft Fabric](https://learn.microsoft.com/en-us/fabric/) |
14 | | -- [Azure Semantic Search](AzureSemanticSearchRegion.md) |
15 | | - |
16 | | -Here are some example regions where the services are available: East US, East US2, Australia East, UK South, France Central. |
17 | | - |
18 | | - |
19 | | -### **Important: Check Azure OpenAI Quota Availability** |
20 | | - |
21 | | -⚠️ To ensure sufficient quota is available in your subscription, please follow [quota check instructions guide](./quota_check.md) before you deploy the solution. |
22 | | - |
23 | | - |
24 | | -### [Optional] Quota Recommendations |
25 | | -By default, the **Gpt-4o-mini model capacity** in deployment is set to **30k tokens**, so we recommend |
26 | | - |
27 | | -> **For Global Standard | GPT-4o-mini - the capacity to at least 100k tokens post-deployment for optimal performance.** |
28 | | -
|
29 | | -To adjust quota settings, follow these [steps](AzureGPTQuotaSettings.md) |
30 | | - |
31 | | - |
32 | | -## Deployment Options & Steps |
33 | | - |
34 | | -Pick from the options below to see step-by-step instructions for GitHub Codespaces, VS Code Dev Containers, and Local Environments. |
35 | | - |
36 | | -| [](https://github.com/codespaces/new?repo=microsoft/Build-your-own-copilot-Solution-Accelerator) | [](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/microsoft/Build-your-own-copilot-Solution-Accelerator) | |
37 | | -|---|---| |
38 | | - |
39 | | -<details> |
40 | | - <summary><b>Deploy in GitHub Codespaces</b></summary> |
41 | | - |
42 | | -### GitHub Codespaces |
43 | | - |
44 | | -You can run this solution using [GitHub Codespaces](https://docs.github.com/en/codespaces). The button will open a web-based VS Code instance in your browser: |
45 | | - |
46 | | -1. Open the solution accelerator (this may take several minutes): |
47 | | - |
48 | | - [](https://github.com/codespaces/new?repo=microsoft/Build-your-own-copilot-Solution-Accelerator) |
49 | | - |
50 | | -2. Accept the default values on the create Codespaces page. |
51 | | -3. Open a terminal window if it is not already open. |
52 | | -4. Continue with the [deploying steps](#deploying-with-azd). |
53 | | - |
54 | | -</details> |
55 | | - |
56 | | -<details> |
57 | | - <summary><b>Deploy in VS Code</b></summary> |
58 | | - |
59 | | -### VS Code Dev Containers |
60 | | - |
61 | | -You can run this solution in [VS Code Dev Containers](https://code.visualstudio.com/docs/devcontainers/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): |
62 | | - |
63 | | -1. Start Docker Desktop (install it if not already installed). |
64 | | -2. Open the project: |
65 | | - |
66 | | - [](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/microsoft/Build-your-own-copilot-Solution-Accelerator) |
67 | | - |
68 | | -3. In the VS Code window that opens, once the project files show up (this may take several minutes), open a terminal window. |
69 | | -4. Continue with the [deploying steps](#deploying-with-azd). |
70 | | - |
71 | | -</details> |
72 | | - |
73 | | -<details> |
74 | | - <summary><b>Deploy in your local Environment</b></summary> |
75 | | - |
76 | | -### Local Environment |
77 | | - |
78 | | -If you're not using one of the above options for opening the project, then you'll need to: |
79 | | - |
80 | | -1. Make sure the following tools are installed: |
81 | | - - [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. |
82 | | - - [Azure Developer CLI (azd)](https://aka.ms/install-azd) |
83 | | - - [Python 3.9+](https://www.python.org/downloads/) |
84 | | - - [Docker Desktop](https://www.docker.com/products/docker-desktop/) |
85 | | - - [Git](https://git-scm.com/downloads) |
86 | | - - [Microsoft ODBC Driver 18 for SQL Server](https://learn.microsoft.com/en-us/sql/connect/odbc/download-odbc-driver-for-sql-server?view=sql-server-ver16) |
87 | | - - [sqlcmd(ODBC-Windows)](https://learn.microsoft.com/en-us/sql/tools/sqlcmd/sqlcmd-utility?view=sql-server-ver16&tabs=odbc%2Cwindows%2Cwindows-support&pivots=cs1-bash#download-and-install-sqlcmd) / [sqlcmd(Linux/Mac)](https://learn.microsoft.com/en-us/sql/linux/sql-server-linux-setup-tools?view=sql-server-ver16&tabs=redhat-install) |
88 | | - |
89 | | -2. Clone the repository or download the project code via command-line: |
90 | | - |
91 | | - ```shell |
92 | | - azd init -t microsoft/build-your-own-copilot-solution-accelerator/ |
93 | | - ``` |
94 | | - |
95 | | -3. Open the project folder in your terminal or editor. |
96 | | -4. Continue with the [deploying steps](#deploying-with-azd). |
97 | | - |
98 | | -</details> |
99 | | - |
100 | | -<br/> |
101 | | - |
102 | | -Consider the following settings during your deployment to modify specific settings: |
103 | | - |
104 | | -<details> |
105 | | - <summary><b>Configurable Deployment Settings</b></summary> |
106 | | - |
107 | | -When you start the deployment, most parameters will have **default values**, but you can update the below settings by following the steps [here](CustomizingAzdParameters.md): |
108 | | - |
109 | | -| **Setting** | **Description** | **Default value** | |
110 | | -|------------|----------------| ------------| |
111 | | -| **Azure OpenAI Location** | The region where OpenAI deploys | eastus2 | |
112 | | -| **Environment Name** | A **3-20 character alphanumeric value** used to generate a unique ID to prefix the resources. | byocatemplate | |
113 | | -| **Cosmos Location** | A **less busy** region for **CosmosDB**, useful in case of availability constraints. | eastus2 | |
114 | | -| **Deployment Type** | Select from a drop-down list. | Global Standard | |
115 | | -| **GPT Model** | OpenAI GPT model | gpt-4o-mini | |
116 | | -| **GPT Model Deployment Capacity** | Configure capacity for **GPT models**. | 30k | |
117 | | -| **Embedding Model** | OpenAI embedding model | 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 model capacity** in deployment is set to **30k tokens**. |
126 | | -> **We recommend increasing the capacity to 100k tokens, if available, for optimal performance.** |
127 | | - |
128 | | -To adjust quota settings, follow these [steps](./AzureGPTQuotaSettings.md). |
129 | | - |
130 | | -**⚠️ Warning:** Insufficient quota can cause deployment errors. Please ensure you have the recommended capacity or request additional capacity before deploying this solution. |
131 | | - |
132 | | -</details> |
133 | | - |
134 | | -### Deploying with AZD |
135 | | - |
136 | | -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: |
137 | | -
|
138 | | -1. Login to Azure: |
139 | | -
|
140 | | - ```shell |
141 | | - azd auth login |
142 | | - ``` |
143 | | -
|
144 | | - #### To authenticate with Azure Developer CLI (`azd`), use the following command with your **Tenant ID**: |
145 | | -
|
146 | | - ```sh |
147 | | - azd auth login --tenant-id <tenant-id> |
148 | | - ``` |
149 | | -
|
150 | | - > **Note:** To retrieve the Tenant ID required for local deployment, you can go to **Tenant Properties** in [Azure Portal](https://portal.azure.com/) from the resource list. Alternatively, follow these steps: |
151 | | - > |
152 | | - > 1. Open the [Azure Portal](https://portal.azure.com/). |
153 | | - > 2. Navigate to **Azure Active Directory** from the left-hand menu. |
154 | | - > 3. Under the **Overview** section, locate the **Tenant ID** field. Copy the value displayed. |
155 | | -
|
156 | | -2. Provision and deploy all the resources: |
157 | | -
|
158 | | - ```shell |
159 | | - azd up |
160 | | - ``` |
161 | | -
|
162 | | -3. Provide an `azd` environment name (e.g., "byocaapp"). |
163 | | -4. Select a subscription from your Azure account and choose a location that has quota for all the resources. |
164 | | - - This deployment will take *7-10 minutes* to provision the resources in your account and set up the solution with sample data. |
165 | | - - If you encounter an error or timeout during deployment, changing the location may help, as there could be availability constraints for the resources. |
166 | | -
|
167 | | -5. Once the deployment is complete, please follow the [Import Sample Data](#post-deployment-steps) instructions under **Post Deployment Steps** to load the sample data correctly. |
168 | | -6. 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`. |
169 | | -7. Test the app locally with the sample question with any selected client: _Show latest asset value by asset type?_. For more sample questions you can test in the application, see [Sample Questions](SampleQuestions.md). |
170 | | -8. You can now delete the resources by running `azd down`, if you are done trying out the application. |
171 | | -
|
172 | | -### Publishing Local Build Container to Azure Container Registry |
173 | | -
|
174 | | -If you need to rebuild the source code and push the updated container to the deployed Azure Container Registry, follow these steps: |
175 | | -
|
176 | | -1. Set the environment variable `USE_LOCAL_BUILD` to `True`: |
177 | | -
|
178 | | - - **Linux/macOS**: |
179 | | - ```bash |
180 | | - export USE_LOCAL_BUILD=True |
181 | | - ``` |
182 | | -
|
183 | | - - **Windows (PowerShell)**: |
184 | | - ```powershell |
185 | | - $env:USE_LOCAL_BUILD = $true |
186 | | - ``` |
187 | | -2. Run the `az login` command |
188 | | - ```bash |
189 | | - az login |
190 | | - ``` |
191 | | -
|
192 | | -3. Run the `azd up` command again to rebuild and push the updated container: |
193 | | - ```bash |
194 | | - azd up |
195 | | - ``` |
196 | | -
|
197 | | -This will rebuild the source code, package it into a container, and push it to the Azure Container Registry associated with your deployment. |
198 | | -
|
199 | | -## Post Deployment Steps |
200 | | -
|
201 | | -1. **Import Sample Data** |
202 | | - -Run bash command printed in the terminal. The bash command will look like the following: |
203 | | - ```shell |
204 | | - bash ./infra/scripts/process_sample_data.sh |
205 | | - ``` |
206 | | - if you don't have azd env then you need to pass parameters along with the command. Then the command will look like the following: |
207 | | - ```shell |
208 | | - bash ./infra/scripts/process_sample_data.sh <resourceGroupName> <cosmosDbAccountName> <storageAccount> <storageContainerName> <keyvaultName> <sqlServerName> <sqlDatabaseName> <webAppUserManagedIdentityClientId> <webAppUserManagedIdentityDisplayName> |
209 | | - ``` |
210 | | - |
211 | | -2. **Add Authentication Provider** |
212 | | - - Follow steps in [App Authentication](./AppAuthentication.md) to configure authenitcation in app service. Note that Authentication changes can take up to 10 minutes. |
213 | | - |
214 | | -3. **Fabric Configuration**, |
215 | | - - Follow steps in [Fabric Deployment guide](FabricDeployment.md) to set up the data processing pipelines and Power BI report in Fabric. |
216 | | -4. **Teams App Configuration** |
217 | | - - *(Optional)* Follow steps in [Teams Tab App guide](TeamsAppDeployment.md) to add the Client Advisor app to Microsoft Teams. |
218 | | -5. **Deleting Resources After a Failed Deployment** |
219 | | - |
220 | | - - Follow steps in [Delete Resource Group](DeleteResourceGroup.md) if your deployment fails and/or you need to clean up the resources. |
0 commit comments