Skip to content

Commit ba811d6

Browse files
blessing-sanusiblessing-sanusi
authored
Update README.md
1 parent 4e81ea2 commit ba811d6

File tree

1 file changed

+223
-36
lines changed

1 file changed

+223
-36
lines changed

‎README.md‎

Lines changed: 223 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,15 @@ This solution accelerator is a powerful tool that helps you create your own AI a
1515

1616
It leverages Azure OpenAI Service and Azure AI Search, to identify relevant documents, summarize unstructured information, and generate document templates.
1717

18+
### Key features
19+
20+
![Key Features](/docs/images/keyfeatures.png)
21+
22+
Below is an image of the solution.
23+
24+
![Landing Page](/docs/images/landing_page.png)
25+
26+
1827
**Scenario**
1928

2029
This example focuses on a generic use case - chat with your own data, generate a document template using your own data, and exporting the document in a docx format.
@@ -24,38 +33,188 @@ The documents are intended for use as sample data only.
2433

2534
<br/>
2635

27-
**Key features**
2836

29-
![Key Features](/docs/images/keyfeatures.png)
37+
### Solution accelerator architecture
38+
![image](/docs/images/architecture.png)
3039

40+
<h2><img src="./docs/images/oneClickDeploy.png" width="64">
3141
<br/>
42+
QUICK DEPLOY
43+
</h2>
3244

33-
**Below is an image of the solution accelerator.**
45+
| [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/microsoft/Generic-Build-your-own-copilot-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/Generic-Build-your-own-copilot-Solution-Accelerator) | [![Deploy to Azure](https://aka.ms/deploytoazurebutton)](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2Fmicrosoft%2FGeneric-Build-your-own-copilot-Solution-Accelerator%2Fmain%2Finfra%2Fmain.json) |
46+
|---|---|---|
3447

35-
![Landing Page](/docs/images/landing_page.png)
3648

49+
### Prerequisites
50+
51+
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)
3752

38-
<h2><img src="/docs/images//oneClickDeploy.png" width="64">
39-
<br/>
40-
One-click deploy
41-
</h2>
53+
Check the [Azure Products by Region](https://azure.microsoft.com/en-us/explore/global-infrastructure/products-by-region/?products=all&regions=all) page and select a **region** where the following services are available:
4254

43-
### Prerequisites
55+
- Azure AI Foundry
56+
- Azure OpenAI Service
57+
- Azure AI Search
58+
- Embedding Model Capacity
59+
- GPT Model Capacity
60+
- [Azure Semantic Search](./docs/AzureSemanticSearchRegion.md)
4461

45-
To use this solution accelerator, you will need access to an [Azure subscription](https://azure.microsoft.com/free/) with permission to create resource groups and resources. While not required, a prior understanding of Azure OpenAI and Azure AI Search will be helpful.
4662

47-
For additional training and support, please see:
63+
<!-- Here are some example regions where the services are available: East US, East US2, Australia East, UK South, France Central. -->
4864

49-
1. [Azure OpenAI](https://learn.microsoft.com/en-us/azure/ai-services/openai/)
50-
2. [Azure AI Search](https://learn.microsoft.com/en-us/azure/search/)
51-
3. [Azure AI Foundry](https://learn.microsoft.com/en-us/azure/ai-studio/)
5265

53-
### Solution accelerator architecture
54-
![image](/docs/images/architecture.png)
66+
### Configurable Deployment Settings
67+
68+
When you start the deployment, most parameters will have **default values**, but you can update the following settings:
69+
70+
| **Setting** | **Description** | **Default value** |
71+
|------------|----------------| ------------|
72+
| **Azure Region** | The region where resources will be created. | East US|
73+
| **Environment Name** | A **3-20 character alphanumeric value** used to generate a unique ID to prefix the resources. | byctemplate |
74+
| **Secondary Location** | A **less busy** region for **Azure SQL and CosmosDB**, useful in case of availability constraints. | eastus2 |
75+
| **Deployment Type** | Select from a drop-down list. | Standard |
76+
| **GPT Model** | Choose from **gpt-4, gpt-4o** | gpt-4 |
77+
| **GPT Model Deployment Capacity** | Configure capacity for **GPT models**. | 30k |
78+
| **Embedding Model** | Default: **text-embedding-ada-002**. | text-embedding-ada-002 |
79+
| **Embedding Model Capacity** | Set the capacity for **embedding models**. | 80k |
80+
81+
82+
### [Optional] Quota Recommendations
83+
By default, the **GPT model capacity** in deployment is set to **30k tokens**.
84+
> **We recommend increasing the capacity to 100k tokens for optimal performance.**
85+
86+
To adjust quota settings, follow these [steps](./docs/AzureGPTQuotaSettings.md)
87+
88+
89+
**⚠️ Warning:** **Insufficient quota can cause deployment errors.** Please ensure you have the recommended capacity or request for additional capacity before deploying this solution.
90+
91+
### Deployment Options
92+
Pick from the options below to see step-by-step instructions for: GitHub Codespaces, VS Code Dev Containers, Local Environments, and Bicep deployments.
93+
94+
<details>
95+
<summary><b>Deploy in GitHub Codespaces</b></summary>
96+
97+
### GitHub Codespaces
98+
99+
You can run this solution using GitHub Codespaces. The button will open a web-based VS Code instance in your browser:
100+
101+
1. Open the solution accelerator (this may take several minutes):
102+
103+
[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/microsoft/Generic-Build-your-own-copilot-Solution-Accelerator)
104+
2. Accept the default values on the create Codespaces page
105+
3. Open a terminal window if it is not already open
106+
4. Continue with the [deploying steps](#deploying)
107+
108+
</details>
109+
110+
<details>
111+
<summary><b>Deploy in VS Code</b></summary>
112+
113+
### VS Code Dev Containers
114+
115+
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):
116+
117+
1. Start Docker Desktop (install it if not already installed)
118+
2. Open the project:
119+
120+
[![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/Generic-Build-your-own-copilot-Solution-Accelerator)
121+
122+
123+
3. In the VS Code window that opens, once the project files show up (this may take several minutes), open a terminal window.
124+
4. Continue with the [deploying steps](#deploying)
125+
126+
</details>
127+
128+
<details>
129+
<summary><b>Deploy in your local environment</b></summary>
130+
131+
### Local environment
132+
133+
If you're not using one of the above options for opening the project, then you'll need to:
134+
135+
1. Make sure the following tools are installed:
136+
137+
* [Azure Developer CLI (azd)](https://aka.ms/install-azd)
138+
* [Python 3.9+](https://www.python.org/downloads/)
139+
* [Docker Desktop](https://www.docker.com/products/docker-desktop/)
140+
* [Git](https://git-scm.com/downloads)
141+
142+
2. Download the project code:
143+
144+
```shell
145+
azd init -t microsoft/Generic-Build-your-own-copilot-Solution-Accelerator/
146+
```
147+
148+
3. Open the project folder in your terminal or editor.
149+
150+
4. Continue with the [deploying steps](#deploying).
151+
152+
</details>
55153

154+
<details>
155+
<summary><b>Deploy with Bicep/ARM template</b></summary>
56156

57-
> Note: Some features contained in this repository are in private preview. Certain features might not be supported or might have constrained capabilities. For more information, see [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/en-us/support/legal/preview-supplemental-terms).
157+
### Bicep
158+
159+
Click the following deployment button to create the required resources for this solution directly in your Azure Subscription.
58160

161+
[![Deploy to Azure](https://aka.ms/deploytoazurebutton)](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2Fmicrosoft%2FGeneric-Build-your-own-copilot-Solution-Accelerator%2Fmain%2Finfra%2Fmain.json)
162+
163+
</details>
164+
165+
166+
### Deploying
167+
168+
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.
169+
170+
To change the azd parameters from the default values, follow the steps [here](./docs/CustomizingAzdParameters.md).
171+
172+
173+
1. Login to Azure:
174+
175+
```shell
176+
azd auth login
177+
```
178+
179+
#### To authenticate with Azure Developer CLI (`azd`), use the following command with your **Tenant ID**:
180+
181+
```sh
182+
azd auth login --tenant-id <tenant-id>
183+
```
184+
185+
2. Provision and deploy all the resources:
186+
187+
```shell
188+
azd up
189+
```
190+
191+
3. Provide an `azd` environment name (like "bycapp")
192+
4. Select a subscription from your Azure account, and select a location which has quota for all the resources.
193+
* This deployment will take *7-10 minutes* to provision the resources in your account and set up the solution with sample data.
194+
* If you get an error or timeout with deployment, changing the location can help, as there may be availability constraints for the resources.
195+
196+
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`.
197+
198+
6. You can now delete the resources by running `azd down`, if you are done trying out the application.
199+
<!-- 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`. -->
200+
201+
<h2>
202+
Additional Steps
203+
</h2>
204+
205+
1. **Add App Authentication**
206+
207+
Follow steps in [App Authentication](./docs/AppAuthentication.md) to configure authenitcation in app service.
208+
209+
Note: Authentication changes can take up to 10 minutes
210+
211+
2. **Deleting Resources After a Failed Deployment**
212+
213+
Follow steps in [Delete Resource Group](./docs/DeleteResourceGroup.md) If your deployment fails and you need to clean up the resources.
214+
215+
216+
217+
<!--
59218
60219
### **How to install/deploy**
61220
@@ -64,7 +223,7 @@ https://azure.microsoft.com/en-us/explore/global-infrastructure/products-by-regi
64223
65224
2. Click the following deployment button to create the required resources for this accelerator in your Azure Subscription.
66225
67-
[![Deploy to Azure](https://aka.ms/deploytoazurebutton)](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2Fmicrosoft%2Fdocument-generation-solution-accelerator%2Fmain%2Finfrastructure%2Fdeployment.json)
226+
[![Deploy to Azure](https://aka.ms/deploytoazurebutton)](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2Fmicrosoft%2FGeneric-Build-your-own-copilot-Solution-Accelerator%2Fmain%2Finfrastructure%2Fdeployment.json)
68227
69228
3. You will need to select an Azure Subscription, create/select a Resource group, and Region. If your intention is to deploy this solution accelerator and the corresponding sample data set, the default settings will suffice.
70229
@@ -86,22 +245,8 @@ To add further access controls, update the logic in `getUserInfoList` in `fronte
86245
2. **Importance of prompt engineering**. Prompt engineering is a critical aspect of working with AI models, especially when leveraging advanced capabilities such as those provided by Azure AI services. Proper prompt engineering ensures that the AI models generate accurate, relevant, and contextually appropriate responses. It involves carefully crafting and refining prompts to guide the model's behavior and output effectively. Neglecting prompt engineering can result in suboptimal performance, irrelevant outputs, and increased frustration for users. Therefore, it is essential to invest time and effort in prompt engineering to fully harness the potential of AI models
87246
88247
### Local deployment
89-
Review the local deployment [README](./docs/README_LOCAL.md).
90-
<br>
91-
<h2><img src="./docs/images/supportingDocuments.png" width="64">
92-
<br/>
93-
Supporting documents
94-
</h2>
248+
Review the local deployment [README](./docs/README_LOCAL.md). -->
95249
96-
Supporting documents coming soon.
97-
<br>
98-
<h2><img src="./docs/images/customerTruth.png" width="64">
99-
</br>
100-
Customer truth
101-
</h2>
102-
Customer stories coming soon.
103-
104-
<br/>
105250
106251
107252
<h2>
@@ -111,9 +256,51 @@ Responsible AI Transparency FAQ
111256
112257
Please refer to [Transparency FAQ](./docs/TRANSPARENCY_FAQ.md) for responsible AI transparency details of this solution accelerator.
113258
114-
<br/>
115-
<br/>
116-
---
259+
<h2>
260+
Supporting documentation
261+
</h2>
262+
263+
### Costs
264+
265+
Pricing varies per region and usage, so it isn't possible to predict exact costs for your usage.
266+
The majority of the Azure resources used in this infrastructure are on usage-based pricing tiers.
267+
However, Azure Container Registry has a fixed cost per registry per day.
268+
269+
You can try the [Azure pricing calculator](https://azure.microsoft.com/en-us/pricing/calculator) for the resources:
270+
271+
* Azure AI Foundry: Free tier. [Pricing](https://azure.microsoft.com/pricing/details/ai-studio/)
272+
* Azure AI Search: Standard tier, S1. Pricing is based on the number of documents and operations. [Pricing](https://azure.microsoft.com/pricing/details/search/)
273+
* Azure Storage Account: Standard tier, LRS. Pricing is based on storage and operations. [Pricing](https://azure.microsoft.com/pricing/details/storage/blobs/)
274+
* Azure Key Vault: Standard tier. Pricing is based on the number of operations. [Pricing](https://azure.microsoft.com/pricing/details/key-vault/)
275+
* Azure AI Services: S0 tier, defaults to gpt-4o and text-embedding-ada-002 models. Pricing is based on token count. [Pricing](https://azure.microsoft.com/pricing/details/cognitive-services/)
276+
* Azure Container App: Consumption tier with 0.5 CPU, 1GiB memory/storage. Pricing is based on resource allocation, and each month allows for a certain amount of free usage. [Pricing](https://azure.microsoft.com/pricing/details/container-apps/)
277+
* Azure Container Registry: Basic tier. [Pricing](https://azure.microsoft.com/pricing/details/container-registry/)
278+
* Log analytics: Pay-as-you-go tier. Costs based on data ingested. [Pricing](https://azure.microsoft.com/pricing/details/monitor/)
279+
* Azure Cosmos DB: [Pricing](https://azure.microsoft.com/en-us/pricing/details/cosmos-db/autoscale-provisioned/)
280+
281+
282+
⚠️ To avoid unnecessary costs, remember to take down your app if it's no longer in use,
283+
either by deleting the resource group in the Portal or running `azd down`.
284+
285+
### Security guidelines
286+
287+
This template uses Azure Key Vault to store all connections to communicate between resources.
288+
289+
This template also uses [Managed Identity](https://learn.microsoft.com/entra/identity/managed-identities-azure-resources/overview) for local development and deployment.
290+
291+
To ensure continued best practices in your own repository, we recommend that anyone creating solutions based on our templates ensure that the [Github secret scanning](https://docs.github.com/code-security/secret-scanning/about-secret-scanning) setting is enabled.
292+
293+
You may want to consider additional security measures, such as:
294+
295+
* Enabling Microsoft Defender for Cloud to [secure your Azure resources](https://learn.microsoft.com/azure/security-center/defender-for-cloud).
296+
* Protecting the Azure Container Apps instance with a [firewall](https://learn.microsoft.com/azure/container-apps/waf-app-gateway) and/or [Virtual Network](https://learn.microsoft.com/azure/container-apps/networking?tabs=workload-profiles-env%2Cazure-cli).
297+
298+
299+
300+
### Additional Resources
301+
1. [Azure OpenAI Service](https://learn.microsoft.com/en-us/azure/ai-services/openai/)
302+
2. [Azure AI Search](https://learn.microsoft.com/en-us/azure/search/)
303+
3. [Azure AI Foundry](https://learn.microsoft.com/en-us/azure/ai-studio/)
117304
118305
## Disclaimers
119306

0 commit comments

Comments
 (0)