Readme refactor (#1346)

* readme refactor

* wording tweaks

Author: pamelafox

README.md

@@ -4,12 +4,14 @@ Consult the main [README](../README.md) for general information about the projec
 These are advanced topics that are not necessary for a basic deployment.
 
 * [Deploying with the Azure Developer CLI](azd.md)
-* [Deploying from a free account](deploy_lowcost.md)
+    * [Deploying with existing Azure resources](deploy_existing.md)
+    * [Deploying from a free account](deploy_lowcost.md)
+    * [Enabling optional features](deploy_features.md)
+        * [Login and access control](login_and_acl.md)
+        * [GPT-4 Turbo with Vision](gpt4v.md)
 * [Debugging the app on App Service](appservice.md)
 * [Local development](localdev.md)
 * [App customization](customization.md)
 * [Data ingestion](data_ingestion.md)
 * [Productionizing](productionizing.md)
-* [Login and access control](login_and_acl.md)
-* [Using GPT-4 Turbo with Vision](gpt4v.md)
 * [Alternative RAG chat samples](other_samples.md)

docs/README.md

@@ -0,0 +1,70 @@
+
+# Deploying with existing Azure resources
+
+If you already have existing Azure resources, you can re-use those by setting `azd` environment values.
+You should set these values before running `azd up`. Once you've set them, return to the [deployment steps](../README.md#deploying).
+
+* [Existing resource group](#existing-resource-group)
+* [Existing OpenAI resource](#existing-openai-resource)
+* [Existing Azure AI Search resource](#existing-azure-ai-search-resource)
+* [Existing Azure Document Intelligence resource](#existing-azure-document-intelligence-resource)
+* [Other existing Azure resources](#other-existing-azure-resources)
+
+## Existing resource group
+
+1. Run `azd env set AZURE_RESOURCE_GROUP {Name of existing resource group}`
+1. Run `azd env set AZURE_LOCATION {Location of existing resource group}`
+
+## Existing OpenAI resource
+
+### Azure OpenAI:
+
+1. Run `azd env set AZURE_OPENAI_SERVICE {Name of existing OpenAI service}`
+1. Run `azd env set AZURE_OPENAI_RESOURCE_GROUP {Name of existing resource group that OpenAI service is provisioned to}`
+1. Run `azd env set AZURE_OPENAI_CHATGPT_DEPLOYMENT {Name of existing ChatGPT deployment}`. Only needed if your ChatGPT deployment is not the default 'chat'.
+1. Run `azd env set AZURE_OPENAI_EMB_DEPLOYMENT {Name of existing GPT embedding deployment}`. Only needed if your embeddings deployment is not the default 'embedding'.
+
+When you run `azd up` after and are prompted to select a value for `openAiResourceGroupLocation`, make sure to select the same location as the existing OpenAI resource group.
+
+### Openai.com OpenAI:
+
+1. Run `azd env set OPENAI_HOST openai`
+2. Run `azd env set OPENAI_ORGANIZATION {Your OpenAI organization}`
+3. Run `azd env set OPENAI_API_KEY {Your OpenAI API key}`
+4. Run `azd up`
+
+You can retrieve your OpenAI key by checking [your user page](https://platform.openai.com/account/api-keys) and your organization by navigating to [your organization page](https://platform.openai.com/account/org-settings).
+Learn more about creating an OpenAI free trial at [this link](https://openai.com/pricing).
+Do *not* check your key into source control.
+
+When you run `azd up` after and are prompted to select a value for `openAiResourceGroupLocation`, you can select any location as it will not be used.
+
+
+## Existing Azure AI Search resource
+
+1. Run `azd env set AZURE_SEARCH_SERVICE {Name of existing Azure AI Search service}`
+1. Run `azd env set AZURE_SEARCH_SERVICE_RESOURCE_GROUP {Name of existing resource group with ACS service}`
+1. If that resource group is in a different location than the one you'll pick for the `azd up` step,
+  then run `azd env set AZURE_SEARCH_SERVICE_LOCATION {Location of existing service}`
+1. If the search service's SKU is not standard, then run `azd env set AZURE_SEARCH_SERVICE_SKU {Name of SKU}`. If you specify the free tier, then your app will no longer be able to use semantic ranker, and it will use keys instead of managed identity for accessing the search service. Be advised that [search SKUs cannot be changed](https://learn.microsoft.com/azure/search/search-sku-tier#tier-upgrade-or-downgrade). ([See other possible SKU values](https://learn.microsoft.com/azure/templates/microsoft.search/searchservices?pivots=deployment-language-bicep#sku))
+1. If you have an existing index that is set up with all the expected fields, then run `azd env set AZURE_SEARCH_INDEX {Name of existing index}`. Otherwise, the `azd up` command will create a new index.
+
+You can also customize the search service (new or existing) for non-English searches:
+
+1. To configure the language of the search query to a value other than "en-US", run `azd env set AZURE_SEARCH_QUERY_LANGUAGE {Name of query language}`. ([See other possible values](https://learn.microsoft.com/rest/api/searchservice/preview-api/search-documents#queryLanguage))
+1. To turn off the spell checker, run `azd env set AZURE_SEARCH_QUERY_SPELLER none`. Consult [this table](https://learn.microsoft.com/rest/api/searchservice/preview-api/search-documents#queryLanguage) to determine if spell checker is supported for your query language.
+1. To configure the name of the analyzer to use for a searchable text field to a value other than "en.microsoft", run `azd env set AZURE_SEARCH_ANALYZER_NAME {Name of analyzer name}`. ([See other possible values](https://learn.microsoft.com/dotnet/api/microsoft.azure.search.models.field.analyzer?view=azure-dotnet-legacy&viewFallbackFrom=azure-dotnet))
+
+## Existing Azure Document Intelligence resource
+
+In order to support analysis of many document formats, this repository uses a preview version of Azure Document Intelligence (formerly Form Recognizer) that is only available in [limited regions](https://learn.microsoft.com/azure/ai-services/document-intelligence/concept-layout).
+If your existing resource is in one of those regions, then you can re-use it by setting the following environment variables:
+
+1. Run `azd env set AZURE_DOCUMENTINTELLIGENCE_SERVICE {Name of existing Azure AI Document Intelligence service}`
+1. Run `azd env set AZURE_DOCUMENTINTELLIGENCE_LOCATION {Location of existing service}`
+1. Run `azd env set AZURE_DOCUMENTINTELLIGENCE_RESOURCE_GROUP {Name of resource group with existing service, defaults to main resource group}`
+1. Run `azd env set AZURE_DOCUMENTINTELLIGENCE_SKU {SKU of existing service, defaults to S0}`
+
+## Other existing Azure resources
+
+You can also use existing Azure AI Document Intelligence and Storage Accounts. See `./infra/main.parameters.json` for list of environment variables to pass to `azd env set` to configure those existing resources.

docs/deploy_existing.md

@@ -0,0 +1,58 @@
+
+# Enabling optional features
+
+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)
+* [Enabling GPT-4 Turbo with Vision](#enabling-gpt-4-turbo-with-vision)
+* [Enabling Integrated Vectorization](#enabling-integrated-vectorization)
+* [Enabling authentication](#enabling-authentication)
+* [Enabling login and document level access control](#enabling-login-and-document-level-access-control)
+* [Enabling CORS for an alternate frontend](#enabling-cors-for-an-alternate-frontend)
+
+## Using GPT-4
+
+We generally find that most developers are able to get high quality answers using GPT 3.5. However, if you want to try GPT-4, you can do so by following these steps:
+
+* In `infra/main.bicep`, change `chatGptModelName` to 'gpt-4' instead of 'gpt-35-turbo'.
+* You may also need to adjust the capacity above that line depending on how much TPM your account is allowed.
+
+## Enabling GPT-4 Turbo with Vision
+
+This section covers the integration of GPT-4 Vision with Azure AI Search. Learn how to enhance your search capabilities with the power of image and text indexing, enabling advanced search functionalities over diverse document types. For a detailed guide on setup and usage, visit our [Enabling GPT-4 Turbo with Vision](docs/gpt4v.md) page.
+
+## Enabling Integrated Vectorization
+
+Azure AI search recently introduced an [integrated vectorization feature in preview mode](https://techcommunity.microsoft.com/t5/ai-azure-ai-services-blog/announcing-the-public-preview-of-integrated-vectorization-in/ba-p/3960809#:~:text=Integrated%20vectorization%20is%20a%20new%20feature%20of%20Azure,pull-indexers%2C%20and%20vectorization%20of%20text%20queries%20through%20vectorizers). This feature is a cloud-based approach to data ingestion, which takes care of document format cracking, data extraction, chunking, vectorization, and indexing, all with Azure technologies.
+
+To enable integrated vectorization with this sample:
+
+1. If you've previously deployed, delete the existing search index.
+2. Run `azd env set USE_FEATURE_INT_VECTORIZATION true`
+3. Run `azd up` to update system and user roles
+4. You can view the resources such as the indexer and skillset in Azure Portal and monitor the status of the vectorization process.
+
+## Enabling authentication
+
+By default, the deployed Azure web app will have no authentication or access restrictions enabled, meaning anyone with routable network access to the web app can chat with your indexed data.  You can require authentication to your Azure Active Directory by following the [Add app authentication](https://learn.microsoft.com/azure/app-service/scenario-secure-app-authentication-app-service) tutorial and set it up against the deployed web app.
+
+To then limit access to a specific set of users or groups, you can follow the steps from [Restrict your Azure AD app to a set of users](https://learn.microsoft.com/azure/active-directory/develop/howto-restrict-your-app-to-a-set-of-users) by changing "Assignment Required?" option under the Enterprise Application, and then assigning users/groups access.  Users not granted explicit access will receive the error message -AADSTS50105: Your administrator has configured the application <app_name> to block users unless they are specifically granted ('assigned') access to the application.-
+
+## Enabling login and document level access control
+
+By default, the deployed Azure web app allows users to chat with all your indexed data. You can enable an optional login system using Azure Active Directory to restrict access to indexed data based on the logged in user. Enable the optional login and document level access control system by following [this guide](./docs/login_and_acl.md).
+
+## Enabling CORS for an alternate frontend
+
+By default, the deployed Azure web app will only allow requests from the same origin.  To enable CORS for a frontend hosted on a different origin, run:
+
+1. Run `azd env set ALLOWED_ORIGIN https://<your-domain.com>`
+2. Run `azd up`
+
+For the frontend code, change `BACKEND_URI` in `api.ts` to point at the deployed backend URL, so that all fetch requests will be sent to the deployed backend.
+
+For an alternate frontend that's written in Web Components and deployed to Static Web Apps, check out
+[azure-search-openai-javascript](https://github.com/Azure-Samples/azure-search-openai-javascript) and its guide
+on [using a different backend](https://github.com/Azure-Samples/azure-search-openai-javascript#using-a-different-backend).
+Both these repositories adhere to the same [HTTP protocol for RAG chat apps](https://github.com/Azure-Samples/ai-chat-app-protocol).

docs/deploy_features.md

@@ -2,19 +2,10 @@
 
 This AI RAG chat application is designed to be easily deployed using the Azure Developer CLI, which provisions the infrastructure according to the Bicep files in the `infra` folder. Those files describe each of the Azure resources needed, and configures their SKU (pricing tier) and other parameters. Many Azure services offer a free tier, but the infrastructure files in this project do *not* default to the free tier as there are often limitations in that tier.
 
-However, if your goal is to minimize costs while prototyping your application, follow these steps below _before_ deploying the application.
+However, if your goal is to minimize costs while prototyping your application, follow the steps below _before_ running `azd up`. Once you've gone through these steps, return to the [deployment steps](../README.md#deploying).
 
 [📺 Live stream: Deploying from a free account](https://www.youtube.com/watch?v=nlIyos0RXHw)
 
-1. Create a new azd environment for the free resource group:
-
-    ```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.
-
 2. Use the free tier of App Service:
 
     ```shell