Skip to content

Commit ec95c2b

Browse files
Roopan-MicrosoftRoopan-Microsoft
authored
Update README.md
1 parent bb3b85b commit ec95c2b

File tree

1 file changed

+116
-90
lines changed

1 file changed

+116
-90
lines changed

‎README.md‎

Lines changed: 116 additions & 90 deletions
Original file line numberDiff line numberDiff line change
@@ -71,129 +71,154 @@ This guide provides step-by-step instructions for deploying your application usi
7171

7272
There are several ways to deploy the solution. You can deploy to run in Azure in one click, or manually, or you can deploy locally.
7373

74-
## Quick Deploy
74+
<h2><img src="./documentation/images/readme/oneClickDeploy.png" width="64">
75+
<br/>
76+
QUICK DEPLOY
77+
</h2>
78+
79+
### Prerequisites
80+
81+
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 and resources**. Follow the steps in [Azure Account Set Up](./docs/AzureAccountSetUp.md)
82+
83+
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:
84+
85+
- Azure OpenAI Service
86+
- Azure AI Search
87+
- [Azure Semantic Search](./docs/AzureSemanticSearchRegion.md)
88+
- Current Azure CLI installed
89+
- You can update to the latest version using ```az upgrade```
90+
- Azure account with appropriate permissions
91+
- Docker installed
92+
93+
### ⚠️ Important: Check Azure OpenAI Quota Availability
94+
95+
➡️ To ensure sufficient quota is available in your subscription, please follow **[Quota check instructions guide](./documentation/quota_check.md)** before you deploy the solution.
7596

76-
<h2><img src="./documentation/images/readme/oneClickDeploy.png" width="64"></h2>
97+
| [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/microsoft/Multi-Agent-Custom-Automation-Engine-Solution-Accelerator) | [![Open in Dev Containers](https://img.shields.io/static/v1?style=for-the-badge&label=Dev%20Containers&message=Open&color=blue&logo=visualstudiocode)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/microsoft/Multi-Agent-Custom-Automation-Engine-Solution-Accelerator) |
98+
|---|---|
7799

78-
[![Deploy to Azure](https://aka.ms/deploytoazurebutton)](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2Fmicrosoft%2FMulti-Agent-Custom-Automation-Engine-Solution-Accelerator%2Frefs%2Fheads%2Fmain%2Fdeploy%2Fmacae-continer-oc.json)
100+
101+
<!-- [![Deploy to Azure](https://aka.ms/deploytoazurebutton)](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2Fmicrosoft%2FMulti-Agent-Custom-Automation-Engine-Solution-Accelerator%2Frefs%2Fheads%2Fmain%2Fdeploy%2Fmacae-continer-oc.json) -->
79102

80103
When Deployment is complete, follow steps in [Set Up Authentication in Azure App Service](./documentation/azure_app_service_auth_setup.md) to add app authentication to your web app running on Azure App Service
81104

82-
## Local Deployment
83-
To run the solution site and API backend only locally for development and debugging purposes, See the [local deployment guide](./documentation/LocalDeployment.md).
105+
### Configurable Deployment Settings
84106

85-
## Manual Azure Deployment
86-
Manual Deployment differs from the ‘Quick Deploy’ option in that it will install an Azure Container Registry (ACR) service, and relies on the installer to build and push the necessary containers to this ACR. This allows you to build and push your own code changes and provides a sample solution you can customize based on your requirements.
107+
When you start the deployment, most parameters will have **default values**, but you can update the below settings by following the steps [here](./docs/CustomizingAzdParameters.md):
87108

88-
### Prerequisites
109+
| **Setting** | **Description** | **Default value** |
110+
|------------|----------------| ------------|
111+
| **Environment Name** | A **3-20 character alphanumeric value** used to generate a unique ID to prefix the resources. | byctemplate |
112+
| **Secondary Location** | A **less busy** region for **CosmosDB**, useful in case of availability constraints. | eastus2 |
113+
| **Deployment Type** | Select from a drop-down list. | Global Standard |
114+
| **GPT Model** | Choose from **gpt-4, gpt-4o** | gpt-4o |
115+
| **GPT Model Deployment Capacity** | Configure capacity for **GPT models**. | 30k |
89116

90-
- Current Azure CLI installed
91-
You can update to the latest version using ```az upgrade```
92-
- Azure account with appropriate permissions
93-
- Docker installed
94117

95-
### Deploy the Azure Services
96-
All of the necessary Azure services can be deployed using the /deploy/macae.bicep script. This script will require the following parameters:
118+
### [Optional] Quota Recommendations
119+
By default, the **Gpt-4o model capacity** in deployment is set to **30k tokens**, so we recommend
120+
> **For Global Standard | GPT-4o - the capacity to at least 150k tokens post-deployment for optimal performance.**
97121
98-
```
99-
az login
100-
az account set --subscription <SUBSCRIPTION_ID>
101-
az group create --name <RG_NAME> --location <RG_LOCATION>
102-
```
103-
To deploy the script you can use the Azure CLI.
104-
```
105-
az deployment group create \
106-
--resource-group <RG_NAME> \
107-
--template-file <BICEP_FILE> \
108-
--name <DEPLOYMENT_NAME>
109-
```
122+
> **For Standard | GPT-4 - ensure a minimum of 30k–40k tokens for best results.**
110123
111-
Note: if you are using windows with PowerShell, the continuation character (currently ‘\’) should change to the tick mark (‘`’).
124+
To adjust quota settings, follow these [steps](./documentation/AzureGPTQuotaSettings.md)
112125

113-
The template will require you fill in locations for Cosmos and OpenAI services. This is to avoid the possibility of regional quota errors for either of these resources.
126+
### Deployment Options
127+
Pick from the options below to see step-by-step instructions for: GitHub Codespaces, VS Code Dev Containers, Local Environments, and Bicep deployments.
114128

115-
### Create the Containers
116-
#### Get admin credentials from ACR
129+
<details>
130+
<summary><b>Deploy in GitHub Codespaces</b></summary>
117131

118-
Retrieve the admin credentials for your Azure Container Registry (ACR):
132+
### GitHub Codespaces
119133

120-
```sh
121-
az acr credential show \
122-
--name <e.g. macaeacr2t62qyozi76bs> \
123-
--resource-group <rg-name>
124-
```
134+
You can run this solution using GitHub Codespaces. The button will open a web-based VS Code instance in your browser:
125135

126-
#### Login to ACR
136+
1. Open the solution accelerator (this may take several minutes):
127137

128-
Login to your Azure Container Registry:
138+
[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/microsoft/Multi-Agent-Custom-Automation-Engine-Solution-Accelerator)
139+
2. Accept the default values on the create Codespaces page
140+
3. Open a terminal window if it is not already open
141+
4. Continue with the [deploying steps](#deploying)
129142

130-
```sh
131-
az acr login --name <e.g. macaeacr2t62qyozi76bs>
132-
```
143+
</details>
133144

134-
#### Build and push the image
145+
<details>
146+
<summary><b>Deploy in VS Code</b></summary>
135147

136-
Build the frontend and backend Docker images and push them to your Azure Container Registry. Run the following from the src/backend and the src/frontend directory contexts:
148+
### VS Code Dev Containers
137149

138-
```sh
139-
az acr build \
140-
--registry <e.g. macaeacr2t62qyozi76bs> \
141-
--resource-group <rg-name> \
142-
--image <e.g. backendmacae:latest> .
143-
```
150+
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):
144151

145-
### Add images to the Container APP and Web App services
152+
1. Start Docker Desktop (install it if not already installed)
153+
2. Open the project:
146154

147-
To add your newly created backend image:
148-
- Navigate to the Container App Service in the Azure portal
149-
- Click on Application/Containers in the left pane
150-
- Click on the "Edit and deploy" button in the upper left of the containers pane
151-
- In the "Create and deploy new revision" page, click on your container image 'backend'. This will give you the option of reconfiguring the container image, and also has an Environment variables tab
152-
- Change the properties page to
153-
- point to your Azure Container registry with a private image type and your image name (e.g. backendmacae:latest)
154-
- under "Authentication type" select "Managed Identity" and choose the 'mace-containerapp-pull'... identity setup in the bicep template
155-
- In the environment variables section add the following (each with a 'Manual entry' source):
155+
[![Open in Dev Containers](https://img.shields.io/static/v1?style=for-the-badge&label=Dev%20Containers&message=Open&color=blue&logo=visualstudiocode)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/microsoft/Multi-Agent-Custom-Automation-Engine-Solution-Accelerator)
156156

157-
name: 'COSMOSDB_ENDPOINT'
158-
value: \<Cosmos endpoint>
157+
3. In the VS Code window that opens, once the project files show up (this may take several minutes), open a terminal window.
158+
4. Continue with the [deploying steps](#deploying)
159159

160-
name: 'COSMOSDB_DATABASE'
161-
value: 'autogen'
162-
Note: To change the default, you will need to create the database in Cosmos
163-
164-
name: 'COSMOSDB_CONTAINER'
165-
value: 'memory'
160+
</details>
166161

167-
name: 'AZURE_OPENAI_ENDPOINT'
168-
value: <Azure OpenAI endpoint>
162+
<details>
163+
<summary><b>Deploy in your local environment</b></summary>
169164

170-
name: 'AZURE_OPENAI_DEPLOYMENT_NAME'
171-
value: 'gpt-4o'
165+
### Local environment
172166

173-
name: 'AZURE_OPENAI_API_VERSION'
174-
value: '2024-08-01-preview'
175-
Note: Version should be updated based on latest available
167+
To run the solution site and API backend only locally for development and debugging purposes, See the [local deployment guide](./documentation/LocalDeployment.md).
168+
169+
</details>
170+
171+
### Manual Azure Deployment
172+
Manual Deployment differs from the ‘Quick Deploy’ option in that it will install an Azure Container Registry (ACR) service, and relies on the installer to build and push the necessary containers to this ACR. This allows you to build and push your own code changes and provides a sample solution you can customize based on your requirements. See the [local deployment guide](./documentation/ManualAzureDeployment.md).
173+
174+
175+
### Deploying
176+
177+
Once you've opened the project in [Codespaces](#github-codespaces) or in [Dev Containers](#vs-code-dev-containers) or [locally](#local-environment), you can deploy it to Azure following the following steps.
178+
179+
To change the azd parameters from the default values, follow the steps [here](./documentation/CustomizingAzdParameters.md).
180+
181+
182+
1. Login to Azure:
176183

177-
name: 'FRONTEND_SITE_NAME'
178-
value: 'https://<website Name>.azurewebsites.net'
184+
```shell
185+
azd auth login
186+
```
179187

180-
name: 'APPLICATIONINSIGHTS_CONNECTION_STRING'
181-
value: <Application Insights Connection String>
188+
#### To authenticate with Azure Developer CLI (`azd`), use the following command with your **Tenant ID**:
182189

183-
- Click 'Save' and deploy your new revision
190+
```sh
191+
azd auth login --tenant-id <tenant-id>
192+
```
184193

185-
To add the new container to your website run the following:
194+
2. Provision and deploy all the resources:
186195

187-
```
188-
az webapp config container set --resource-group <resource_group_name> \
189-
--name <container_name> \
190-
--container-image-name <e.g. macaeacr2t62qyozi76bs.azurecr.io/frontendmacae:latest> \
191-
--container-registry-url <e.g. https://macaeacr2t62qyozi76bs.azurecr.io>
192-
```
196+
```shell
197+
azd up
198+
```
193199

200+
3. Provide an `azd` environment name (like "macaeapp")
201+
4. Select a subscription from your Azure account, and select a location which has quota for all the resources.
202+
* This deployment will take *7-10 minutes* to provision the resources in your account and set up the solution with sample data.
203+
* If you get an error or timeout with deployment, changing the location can help, as there may be availability constraints for the resources.
204+
5. 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`.
194205

195-
### Add the Entra identity provider to the Azure Web App
196-
To add the identity provider, please follow the steps outlined in [Set Up Authentication in Azure App Service](./documentation/azure_app_service_auth_setup.md)
206+
6. You can now delete the resources by running `azd down`, if you are done trying out the application.
207+
<!-- 6. You can now proceed to run the [development server](#development-server) to test the app locally, or if you are done trying out the app, you can delete the resources by running `azd down`. -->
208+
209+
<h2>
210+
Additional Steps
211+
</h2>
212+
213+
1. **Add App Authentication**
214+
215+
Follow steps in [App Authentication](./documentation/azure_app_service_auth_setup.md) to configure authenitcation in app service.
216+
217+
Note: Authentication changes can take up to 10 minutes
218+
219+
2. **Deleting Resources After a Failed Deployment**
220+
221+
Follow steps in [Delete Resource Group](./documentation/DeleteResourceGroup.md) If your deployment fails and you need to clean up the resources.
197222

198223
### Run locally and debug
199224

@@ -209,10 +234,11 @@ Note that you can configure the name of the Cosmos database in the configuration
209234

210235
If you are using VSCode, you can use the debug configuration shown in the [local deployment guide](./documentation/LocalDeployment.md).
211236

212-
## Supporting documentation
237+
## Sample Questions
213238

239+
To help you get started, here are some [Sample Questions](./documentation/SampleQuestions.md) you can follow once your application is up and running.
214240

215-
###
241+
## Supporting documentation
216242

217243
### How to customize
218244

0 commit comments

Comments
 (0)