docs: update readme and docs

Author: manekinekko

.env.example

@@ -23,7 +23,7 @@ OPENAI_API_KEY=
 
 # Customize the deployment for the OpenAI text embedding model and chat model.
 AZURE_OPENAI_EMBEDDING_DEPLOYMENT=text-embedding-ada-002
-AZURE_OPENAI_CHAT_DEPLOYMENT=gpt-4
+AZURE_OPENAI_CHAT_DEPLOYMENT=gpt-4o-mini
 AZURE_API_VERSION=2024-10-01-preview
 AZURE_AI_SEARCH_INDEX_NAME=llamaindex-vector-search
 AZURE_AI_SEARCH_CHUNK_FIELD="chunk"

README.md

@@ -31,6 +31,10 @@ This template, the application code and configuration it contains, has been buil
 
 ## Table of Contents
 
+- [LlamaIndex RAG chat app with Azure OpenAI and Azure AI Search (JavaScript)](#llamaindex-rag-chat-app-with-azure-openai-and-azure-ai-search-javascript)
+- [Important Security Notice](#important-security-notice)
+- [Table of Contents](#table-of-contents)
+  - [Architecture Diagram](#architecture-diagram)
 - [Azure account requirements](#azure-account-requirements)
   - [Cost estimation](#cost-estimation)
 - [Getting Started](#getting-started)
@@ -40,6 +44,7 @@ This template, the application code and configuration it contains, has been buil
 - [Deploying](#deploying)
   - [Deploying again](#deploying-again)
 - [Running the development server](#running-the-development-server)
+  - [Using Docker (optional)](#using-docker-optional)
 - [Using the app](#using-the-app)
 - [Clean up](#clean-up)
 - [Guidance](#guidance)
@@ -58,7 +63,7 @@ The repo includes sample data so it's ready to try end to end. In this sample ap
 
 - **Azure account**. If you're new to Azure, [get an Azure account for free](https://azure.microsoft.com/free/cognitive-search/) and you'll get some free Azure credits to get started.
 - **Azure account permissions**:
-  - Your Azure account must have `Microsoft.Authorization/roleAssignments/write` permissions, such as [Role Based Access Control Administrator](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles#role-based-access-control-administrator-preview), [User Access Administrator](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles#user-access-administrator), or [Owner](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles#owner). If you don't have subscription-level permissions, you must be granted [RBAC](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles#role-based-access-control-administrator-preview) for an existing resource group and [deploy to that existing group](docs/deploy_existing.md#resource-group).
+  - Your Azure account must have `Microsoft.Authorization/roleAssignments/write` permissions, such as [Role Based Access Control Administrator](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles#role-based-access-control-administrator-preview), [User Access Administrator](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles#user-access-administrator), or [Owner](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles#owner). If you don't have subscription-level permissions, you must be granted [RBAC](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles#role-based-access-control-administrator-preview) for an existing resource group and deploy to that existing group.
   - Your Azure account also needs `Microsoft.Resources/deployments/write` permissions on the subscription level.
 
 ### Cost estimation
@@ -67,14 +72,14 @@ Pricing varies per region and usage, so it isn't possible to predict exact costs
 However, you can try the [Azure pricing calculator](https://azure.com/e/a87a169b256e43c089015fda8182ca87) for the resources below.
 
 * Azure Container Apps: Consumption plan with 1 CPU core, 2.0 GB RAM. Pricing with Pay-as-You-Go. [Pricing](https://azure.microsoft.com/pricing/details/container-apps/)
-* Azure OpenAI: Standard tier, gpt-4 and text-embedding-3-large models. Pricing per 1K tokens used. [Pricing](https://azure.microsoft.com/pricing/details/cognitive-services/openai-service/)
+* Azure OpenAI: Standard tier, gpt-4o-mini and text-embedding-3-large models. Pricing per 1K tokens used. [Pricing](https://azure.microsoft.com/pricing/details/cognitive-services/openai-service/)
 * Azure AI Search: Standard tier, 1 replica, free level of semantic search. Pricing per hour. [Pricing](https://azure.microsoft.com/pricing/details/search/)
 * Azure Blob Storage: Standard tier with ZRS (Zone-redundant storage). Pricing per storage and read operations. [Pricing](https://azure.microsoft.com/pricing/details/storage/blobs/)
 * Azure Monitor: Pay-as-you-go tier. Costs based on data ingested. [Pricing](https://azure.microsoft.com/pricing/details/monitor/)
 
 To reduce costs, you can switch to free SKUs for various services, but those SKUs have limitations.
 
- To avoid unnecessary costs, remember to take down your app if it's no longer in use,
+To avoid unnecessary costs, remember to take down your app if it's no longer in use,
 either by deleting the resource group in the Portal or running `azd down`.
 
 ## Getting Started
@@ -114,46 +119,61 @@ A related option is VS Code Dev Containers, which will open the project in your
 2. Create a new folder and switch to it in the terminal.
 3. Run this command to download the project code:
 
-    ```shell
-    azd init -t llamaindex-search-javascript
-    ```
+```shell
+azd init -t llamaindex-search-javascript
+```
 
-Note that this command will initialize a git repository, so you do not need to clone this repository.
+> [!NOTE] 
+> This command will initialize a git repository, so you do not need to clone this repository.
 
 ## Deploying
 
 The steps below will provision Azure resources and deploy the application code to Azure Container Apps.
 
-1. Login to your Azure account:
+Login to your Azure account:
 
-    ```shell
-    azd auth login
-    ```
+```shell
+azd auth login
+```
 
-    For GitHub Codespaces users, if the previous command fails, try:
+For GitHub Codespaces users, if the previous command fails, try:
 
-   ```shell
-    azd auth login --use-device-code
-    ```
+```shell
+azd auth login --use-device-code
+```
+
+Create a new azd environment:
 
-1. Create a new azd environment:
+```shell
+azd env new
+```
 
-    ```shell
-    azd env new
-    ```
+Enter a name that will be used for the resource group.
+This will create a new folder in the `.azure` folder, and set it as the active environment for any calls to `azd` going forward.
 
-    Enter a name that will be used for the resource group.
-    This will create a new folder in the `.azure` folder, and set it as the active environment for any calls to `azd` going forward.
-1. Run `azd up` - This will provision Azure resources and deploy this sample to those resources, including building the search index based on the files found in the `./data` folder.
-    - **Important**: Beware that the resources created by this command will incur immediate costs, primarily from the AI Search resource. These resources may accrue costs even if you interrupt the command before it is fully executed. You can run `azd down` or delete the resources manually to avoid unnecessary spending.
-    - You will be prompted to select two locations, one for the majority of resources and one for the OpenAI resource, which is currently a short list. That location list is based on the [OpenAI model availability table](https://learn.microsoft.com/azure/cognitive-services/openai/concepts/models#model-summary-table-and-region-availability) and may become outdated as availability changes.
-1. After the application has been successfully deployed you will see a URL printed to the console.  Click that URL to interact with the application in your browser.
+Package, provision and deploy this project to Azure:
+
+```shell
+azd up
+```
+
+> [!NOTE]
+> This will provision Azure resources and deploy this sample to those resources, including building the search index based on the files found in the ./data folder.
+
+After the application has been successfully deployed you will see a URL printed to the console.  Click that URL to interact with the application in your browser.
 
 It will look like the following:
 
 !['Output from running azd up'](docs/images/llamaindex-search-javascript-endpoint.png)
 
-> NOTE: It may take 5-10 minutes after you see 'SUCCESS' for the application to be fully deployed.
+> [!NOTE]
+> It may take 5-10 minutes after you see 'SUCCESS' for the application to be fully deployed.
+
+> [!IMPORTANT]
+> Beware that the resources created by this command will incur immediate costs, primarily from the AI Search resource. These resources may accrue costs even if you interrupt the command before it is fully executed. You can run `azd down` or delete the resources manually to avoid unnecessary spending.
+>
+> You will be prompted to select two locations, one for the majority of resources and one for the OpenAI resource, which is currently a short list. That location list is based on the [OpenAI model availability table](https://learn.microsoft.com/azure/cognitive-services/openai/concepts/models#model-summary-table-and-region-availability) and may become outdated as availability changes.
+
 
 ### Deploying again
 
@@ -248,7 +268,7 @@ NOTE: you can also run `azd down --purge --force`.
 
 The resource group and all the resources will be deleted.
 
-# Guidance
+## Guidance
 
 You can find extensive documentation in the [docs](docs/README.md) folder:
 

docs/azd.md

@@ -72,7 +72,7 @@ To troubleshoot any issues, see [troubleshooting](#troubleshooting).
 
 ### Configure environment variables for running services
 
-Configure environment variables for running services by updating `settings` in [main.parameters.json](./infra/main.parameters.json).
+Configure environment variables for running services by updating `settings` in [main.parameters.json](../infra/main.parameters.json).
 
 ### Configure CI/CD pipeline
 

docs/features.md

@@ -4,10 +4,11 @@
 This document covers optional features that can be enabled in the deployed Azure resources.
 You should typically enable these features before running `azd up`. Once you've set them, return to the [deployment steps](../README.md#deploying).
 
-* [Using GPT-4](#using-gpt-4)
-* [Using text-embedding-3 models](#using-text-embedding-3-models)
-* [Enabling authentication](#enabling-authentication)
-* [Adding an OpenAI load balancer](#adding-an-openai-load-balancer)
+- [Enabling optional features](#enabling-optional-features)
+  - [Using GPT-4](#using-gpt-4)
+  - [Using text-embedding-3 models](#using-text-embedding-3-models)
+  - [Enabling authentication](#enabling-authentication)
+  - [Adding an OpenAI load balancer](#adding-an-openai-load-balancer)
 
 ## Using GPT-4
 
@@ -19,73 +20,73 @@ Execute the following commands inside your terminal:
 
 1. To set the name of the deployment, run this command with a unique name in your Azure OpenAI account. You can use any deployment name, as long as it's unique in your Azure OpenAI account.
 
-    ```bash
-    azd env set AZURE_OPENAI_CHAT_DEPLOYMENT <your-deployment-name>
-    ```
+```bash
+azd env set AZURE_OPENAI_CHAT_DEPLOYMENT <your-deployment-name>
+```
 
-    For example:
+For example:
 
-    ```bash
-    azd env set AZURE_OPENAI_CHAT_DEPLOYMENT chat4
-    ```
+```bash
+azd env set AZURE_OPENAI_CHAT_DEPLOYMENT chat4
+```
 
 1. To set the GPT model name to a **gpt-4**, **gpt-4o**, or **gpt-4o mini** version from the [available models](https://learn.microsoft.com/azure/ai-services/openai/concepts/models), run this command with the appropriate GPT model name.
 
-    For GPT-4:
+For GPT-4:
 
-    ```bash
-    azd env set AZURE_OPENAI_CHATGPT_MODEL gpt-4
-    ```
+```bash
+azd env set AZURE_OPENAI_CHATGPT_MODEL gpt-4
+```
 
-    For GPT-4o:
+For GPT-4o:
 
-    ```bash
-    azd env set AZURE_OPENAI_CHATGPT_MODEL gpt-4o
-    ```
+```bash
+azd env set AZURE_OPENAI_CHATGPT_MODEL gpt-4o
+```
 
-    For GPT-4o mini:
+For GPT-4o mini:
 
-    ```bash
-    azd env set AZURE_OPENAI_CHATGPT_MODEL gpt-4o-mini
-    ```
+```bash
+azd env set AZURE_OPENAI_CHATGPT_MODEL gpt-4o-mini
+```
 
 1. To set the Azure OpenAI deployment SKU name, run this command with [the desired SKU name](https://learn.microsoft.com/azure/ai-services/openai/how-to/deployment-types#deployment-types).
 
-    ```bash
-    azd env set AZURE_OPENAI_CHAT_DEPLOYMENT_SKU GlobalStandard
-    ```
+```bash
+azd env set AZURE_OPENAI_CHAT_DEPLOYMENT_SKU GlobalStandard
+```
 
 1. To set the Azure OpenAI deployment capacity, run this command with the desired capacity.
 
-    ```bash
-    azd env set AZURE_OPENAI_CHAT_DEPLOYMENT_CAPACITY 10
-    ```
+```bash
+azd env set AZURE_OPENAI_CHAT_DEPLOYMENT_CAPACITY 10
+```
 
 1. To set the Azure OpenAI deployment version from the [available versions](https://learn.microsoft.com/azure/ai-services/openai/concepts/models), run this command with the appropriate version.
 
-    For GPT-4:
+For GPT-4:
 
-    ```bash
-    azd env set AZURE_OPENAI_CHAT_DEPLOYMENT_VERSION turbo-2024-04-09
-    ```
+```bash
+azd env set AZURE_OPENAI_CHAT_DEPLOYMENT_VERSION turbo-2024-04-09
+```
 
-    For GPT-4o:
+For GPT-4o:
 
-    ```bash
-    azd env set AZURE_OPENAI_CHAT_DEPLOYMENT_VERSION 2024-05-13
-    ```
+```bash
+azd env set AZURE_OPENAI_CHAT_DEPLOYMENT_VERSION 2024-05-13
+```
 
-    For GPT-4o mini:
+For GPT-4o mini:
 
-    ```bash
-    azd env set AZURE_OPENAI_CHAT_DEPLOYMENT_VERSION 2024-07-18
-    ```
+```bash
+azd env set AZURE_OPENAI_CHAT_DEPLOYMENT_VERSION 2024-07-18
+```
 
 1. To update the deployment with the new parameters, run this command.
 
-    ```bash
-    azd up
-    ```
+```bash
+azd up
+```
 
 > [!NOTE]
 > To revert back to GPT 3.5, run the following commands:
@@ -105,25 +106,25 @@ By default, the deployed Azure web app uses the `text-embedding-ada-002` embeddi
 
 1. Run one of the following commands to set the desired model:
 
-    ```shell
-    azd env set AZURE_OPENAI_EMB_MODEL_NAME text-embedding-3-small
-    ```
+```shell
+azd env set AZURE_OPENAI_EMB_MODEL_NAME text-embedding-3-small
+```
 
-    ```shell
-    azd env set AZURE_OPENAI_EMB_MODEL_NAME text-embedding-3-large
-    ```
+```shell
+azd env set AZURE_OPENAI_EMB_MODEL_NAME text-embedding-3-large
+```
 
 2. Specify the desired dimensions of the model: (from 256-3072, model dependent)
 
-    ```shell
-    azd env set AZURE_OPENAI_EMB_DIMENSIONS 256
-    ```
+```shell
+azd env set AZURE_OPENAI_EMB_DIMENSIONS 256
+```
 
 3. Set the model version to "1" (the only version as of March 2024):
 
-    ```shell
-    azd env set AZURE_OPENAI_EMB_DEPLOYMENT_VERSION 1
-    ```
+```shell
+azd env set AZURE_OPENAI_EMB_DEPLOYMENT_VERSION 1
+```
 
 4. When prompted during `azd up`, make sure to select a region for the OpenAI resource group location that supports the text-embedding-3 models. There are [limited regions available](https://learn.microsoft.com/azure/ai-services/openai/concepts/models#embeddings-models).
 
@@ -143,5 +144,5 @@ To then limit access to a specific set of users or groups, you can follow the st
 
 ## Adding an OpenAI load balancer
 
-As discussed in more details in our [productionizing guide](./productionizing.md), you may want to consider implementing a load balancer between OpenAI instances if you are consistently going over the TPM limit.
+As discussed in more details in our [productionizing guide](./prod.md), you may want to consider implementing a load balancer between OpenAI instances if you are consistently going over the TPM limit.
 Fortunately, this repository is designed for easy integration with other repositories that create load balancers for OpenAI instances.