Documentation improvements: Remove duplicate READMEs, consistent titles (#2118)

pamelafox · web-flow · commit becd7f9889b4 · 2024-11-05T08:59:21.000-08:00
* Remove duplicate samples

* More consistent docs

* Add debugging tips

* Move formats again

* Fix typo with ACA

* Update docs/data_ingestion.md
diff --git a/README.md b/README.md
@@ -1,4 +1,25 @@
-# ChatGPT-like app with your data using Azure OpenAI and Azure AI Search (Python)
+<!--
+---
+name: RAG chat app with your data (Python)
+description: Chat with your domain data using Azure OpenAI and Azure AI Search.
+languages:
+- python
+- typescript
+- bicep
+- azdeveloper
+products:
+- azure-openai
+- azure-cognitive-search
+- azure-app-service
+- azure
+page_type: sample
+urlFragment: azure-search-openai-demo
+---
+-->
+
+# RAG chat app with Azure OpenAI and Azure AI Search (Python)
+
+This solution creates a ChatGPT-like frontend experience over your own documents using RAG (Retrieval Augmented Generation). It uses Azure OpenAI Service to access GPT models, and Azure AI Search for data indexing and retrieval.
 
 This solution's backend is written in Python. There are also [**JavaScript**](https://aka.ms/azai/js/code), [**.NET**](https://aka.ms/azai/net/code), and [**Java**](https://aka.ms/azai/java/code) samples based on this one. Learn more about [developing AI apps using Azure AI Services](https://aka.ms/azai).
 
diff --git a/docs/appservice.md b/docs/appservice.md
@@ -1,4 +1,4 @@
-# Debugging the app on App Service
+# RAG chat: Debugging the app on App Service
 
 When you run `azd up` or `azd deploy`, it deploys your application to App Service,
 and displays the deployed endpoint in the console.
diff --git a/docs/azd.md b/docs/azd.md
@@ -1,4 +1,4 @@
-# Deploying with the Azure Developer CLI
+# RAG chat: Deploying with the Azure Developer CLI
 
 This guide includes advanced topics that are not necessary for a basic deployment. If you are new to the project, please consult the main [README](../README.md#deploying) for steps on deploying the project.
 
diff --git a/docs/azure_app_service.md b/docs/azure_app_service.md
@@ -1,9 +1,9 @@
-# Deploying on Azure App Service
+# RAG chat: Deploying on Azure App Service
 
 Due to [a limitation](https://github.com/Azure/azure-dev/issues/2736) of the Azure Developer CLI (`azd`), there can be only one host option in the [azure.yaml](../azure.yaml) file.
 By default, `host: containerapp` is used and `host: appservice` is commented out.
 
-To deploy to Azure Container Apps, please follow the following steps:
+To deploy to Azure App Service, please follow the following steps:
 
 1. Comment out `host: containerapp` and uncomment `host: appservice` in the [azure.yaml](../azure.yaml) file.
 
diff --git a/docs/azure_container_apps.md b/docs/azure_container_apps.md
@@ -1,4 +1,4 @@
-# Deploying on Azure Container Apps
+# RAG chat: Deploying on Azure Container Apps
 
 Due to [a limitation](https://github.com/Azure/azure-dev/issues/2736) of the Azure Developer CLI (`azd`), there can be only one host option in the [azure.yaml](../azure.yaml) file.
 By default, `host: containerapp` is used and `host: appservice` is commented out.
diff --git a/docs/customization.md b/docs/customization.md
@@ -1,4 +1,4 @@
-# Customizing the Chat App
+# RAG chat: Customizing the chat app
 
 This guide provides more details for customizing the Chat App.
 
diff --git a/docs/data_ingestion.md b/docs/data_ingestion.md
@@ -1,21 +1,24 @@
-# Indexing documents for the Chat App
+# RAG chat: Data ingestion
 
-This guide provides more details for using the `prepdocs` script to index documents for the Chat App.
+The [azure-search-openai-demo](/) project can set up a full RAG chat app on Azure AI Search and OpenAI so that you can chat on custom data, like internal enterprise data or domain-specific knowledge sets. For full instructions on setting up the project, consult the [main README](/README.md), and then return here for detailed instructions on the data ingestion component.
+
+The chat app provides two ways to ingest data: manual indexing and integrated vectorization. This document explains the differences between the two approaches and provides an overview of the manual indexing process.
 
 - [Supported document formats](#supported-document-formats)
-- [Overview of the manual indexing process](#overview-of-the-manual-indexing-process)
+- [Manual indexing process](#manual-indexing-process)
   - [Chunking](#chunking)
   - [Categorizing data for enhanced search](#enhancing-search-functionality-with-data-categorization)
   - [Indexing additional documents](#indexing-additional-documents)
   - [Removing documents](#removing-documents)
-- [Overview of Integrated Vectorization](#overview-of-integrated-vectorization)
+- [Integrated Vectorization](#integrated-vectorization)
   - [Indexing of additional documents](#indexing-of-additional-documents)
   - [Removal of documents](#removal-of-documents)
   - [Scheduled indexing](#scheduled-indexing)
+- [Debugging tips](#debugging-tips)
 
 ## Supported document formats
 
-In order to ingest a document format, we need a tool that can turn it into text. By default, use Azure Document Intelligence (DI in the table below), but we also have local parsers for several formats. The local parsers are not as sophisticated as Azure Document Intelligence, but they can be used to decrease charges.
+In order to ingest a document format, we need a tool that can turn it into text. By default, the manual indexing uses Azure Document Intelligence (DI in the table below), but we also have local parsers for several formats. The local parsers are not as sophisticated as Azure Document Intelligence, but they can be used to decrease charges.
 
 | Format | Manual indexing                      | Integrated Vectorization |
 | ------ | ------------------------------------ | ------------------------ |
@@ -29,7 +32,7 @@ In order to ingest a document format, we need a tool that can turn it into text.
 
 The Blob indexer used by the Integrated Vectorization approach also supports a few [additional formats](https://learn.microsoft.com/azure/search/search-howto-indexing-azure-blob-storage#supported-document-formats).
 
-## Overview of the manual indexing process
+## Manual indexing process
 
 The [`prepdocs.py`](../app/backend/prepdocs.py) script is responsible for both uploading and indexing documents. The typical usage is to call it using `scripts/prepdocs.sh` (Mac/Linux) or `scripts/prepdocs.ps1` (Windows), as these scripts will set up a Python virtual environment and pass in the required parameters based on the current `azd` environment. You can pass additional arguments directly to the script, for example `scripts/prepdocs.ps1 --removeall`. Whenever `azd up` or `azd provision` is run, the script is called automatically.
 
@@ -42,12 +45,6 @@ The script uses the following steps to index documents:
 3. Split the PDFs into chunks of text.
 4. Upload the chunks to Azure AI Search. If using vectors (the default), also compute the embeddings and upload those alongside the text.
 
-### Enhancing search functionality with data categorization
-
-To enhance search functionality, categorize data during the ingestion process with the `--category` argument, for example `scripts/prepdocs.ps1 --category ExampleCategoryName`. This argument specifies the category to which the data belongs, enabling you to filter search results based on these categories.
-
-After running the script with the desired category, ensure these categories are added to the 'Include Category' dropdown list. This can be found in the developer settings of [`Chat.tsx`](../app/frontend/src/pages/chat/Chat.tsx) and [`Ask.tsx`](../app/frontend/src/pages/ask/Ask.tsx). The default option for this dropdown is "All". By including specific categories, you can refine your search results more effectively.
-
 ### Chunking
 
 We're often asked why we need to break up the PDFs into chunks when Azure AI Search supports searching large documents.
@@ -56,6 +53,12 @@ Chunking allows us to limit the amount of information we send to OpenAI due to t
 
 If needed, you can modify the chunking algorithm in `scripts/prepdocslib/textsplitter.py`.
 
+### Enhancing search functionality with data categorization
+
+To enhance search functionality, categorize data during the ingestion process with the `--category` argument, for example `scripts/prepdocs.ps1 --category ExampleCategoryName`. This argument specifies the category to which the data belongs, enabling you to filter search results based on these categories.
+
+After running the script with the desired category, ensure these categories are added to the 'Include Category' dropdown list. This can be found in the developer settings of [`Chat.tsx`](../app/frontend/src/pages/chat/Chat.tsx) and [`Ask.tsx`](../app/frontend/src/pages/ask/Ask.tsx). The default option for this dropdown is "All". By including specific categories, you can refine your search results more effectively.
+
 ### Indexing additional documents
 
 To upload more PDFs, put them in the data/ folder and run `./scripts/prepdocs.sh` or `./scripts/prepdocs.ps1`.
@@ -70,7 +73,7 @@ To remove all documents, use `scripts/prepdocs.sh --removeall` or `scripts/prepd
 
 You can also remove individual documents by using the `--remove` flag. Open either `scripts/prepdocs.sh` or `scripts/prepdocs.ps1` and replace `/data/*` with `/data/YOUR-DOCUMENT-FILENAME-GOES-HERE.pdf`. Then run `scripts/prepdocs.sh --remove` or `scripts/prepdocs.ps1 --remove`.
 
-## Overview of Integrated Vectorization
+## Integrated Vectorization
 
 Azure AI Search includes an [integrated vectorization feature](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), a cloud-based approach to data ingestion. Integrated vectorization takes care of document format cracking, data extraction, chunking, vectorization, and indexing, all with Azure technologies.
 
@@ -99,3 +102,30 @@ The Azure AI Search indexer will take care of removing those documents from the
 ### Scheduled indexing
 
 If you would like the indexer to run automatically, you can set it up to [run on a schedule](https://learn.microsoft.com/azure/search/search-howto-schedule-indexers).
+
+## Debugging tips
+
+If you are not sure if a file successfully uploaded, you can query the index from the Azure Portal or from the REST API. Open the index and paste the queries below into the search bar.
+
+To see all the filenames uploaded to the index:
+
+```json
+{
+  "search": "*",
+  "count": true,
+  "top": 1,
+  "facets": ["sourcefile"]
+}
+```
+
+To search for specific filenames:
+
+```json
+{
+  "search": "*",
+  "count": true,
+  "top": 1,
+  "filter": "sourcefile eq 'employee_handbook.pdf'",
+  "facets": ["sourcefile"]
+}
+```
diff --git a/docs/deploy_existing.md b/docs/deploy_existing.md
@@ -1,5 +1,5 @@
 
-# Deploying with existing Azure resources
+# RAG chat: Deploying with existing Azure resources
 
 If you already have existing Azure resources, or if you want to specify the exact name of new Azure Resource, you can do so 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).
diff --git a/docs/deploy_features.md b/docs/deploy_features.md
@@ -1,5 +1,5 @@
 
-# Enabling optional features
+# RAG chat: 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).
diff --git a/docs/deploy_lowcost.md b/docs/deploy_lowcost.md
@@ -1,4 +1,4 @@
-# Deploying with minimal costs
+# RAG chat: Deploying with minimal costs
 
 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.
 
diff --git a/docs/deploy_private.md b/docs/deploy_private.md
@@ -1,5 +1,25 @@
-
-# Deploying with private access
+<!--
+---
+name: RAG chat with private endpoints
+description: Configure access to a chat app so that it's only accessible from private endpoints.
+languages:
+- python
+- typescript
+- bicep
+- azdeveloper
+products:
+- azure-openai
+- azure-cognitive-search
+- azure-app-service
+- azure
+page_type: sample
+urlFragment: azure-search-openai-demo-private-access
+---
+-->
+
+# RAG chat: Deploying with private access
+
+The [azure-search-openai-demo](/) project can set up a full RAG chat app on Azure AI Search and OpenAI so that you can chat on custom data, like internal enterprise data or domain-specific knowledge sets. For full instructions on setting up the project, consult the [main README](/README.md), and then return here for detailed instructions on configuring private endpoints.
 
 ⚠️ This feature is not yet compatible with Azure Container Apps, so you will need to [deploy to Azure App Service](./azure_app_service.md) instead.
 
diff --git a/docs/gpt4v.md b/docs/gpt4v.md
@@ -1,4 +1,4 @@
-# Using GPT vision model with RAG approach
+# RAG chat: Using GPT vision model with RAG approach
 
 This repository now includes an example of integrating a GPT Vision model with Azure AI Search. This feature enables indexing and searching images and graphs, such as financial documents, in addition to text-based content, and then sending the retrieved content to the GPT model for response generation.
 
diff --git a/docs/localdev.md b/docs/localdev.md
@@ -1,4 +1,4 @@
-# Local development of Chat App
+# RAG chat: Local development of chat app
 
 You can only run locally **after** having successfully run the `azd up` command. If you haven't yet, follow the steps in [Azure deployment](../README.md#azure-deployment) above.
 
diff --git a/docs/login_and_acl.md b/docs/login_and_acl.md
@@ -1,4 +1,25 @@
-# Setting up optional login and document level access control
+<!--
+---
+name: RAG chat with document security
+description: This guide demonstrates how to add an optional login and document level access control system to a RAG chat app for your domain data. This system can be used to restrict access to indexed data to specific users.
+languages:
+- python
+- typescript
+- bicep
+- azdeveloper
+products:
+- azure-openai
+- azure-cognitive-search
+- azure-app-service
+- azure
+page_type: sample
+urlFragment: azure-search-openai-demo-document-security
+---
+-->
+
+# RAG chat: Setting up optional login and document level access control
+
+The [azure-search-openai-demo](/) project can set up a full RAG chat app on Azure AI Search and OpenAI so that you can chat on custom data, like internal enterprise data or domain-specific knowledge sets. For full instructions on setting up the project, consult the [main README](/README.md), and then return here for detailed instructions on configuring login and access control.
 
 ## Table of Contents
 
diff --git a/docs/other_samples.md b/docs/other_samples.md
@@ -1,4 +1,4 @@
-# Alternative RAG chat samples
+# RAG chat: Alternative RAG chat samples
 
 There are an increasingly large number of ways to build RAG chat apps.
 
diff --git a/docs/productionizing.md b/docs/productionizing.md
@@ -1,4 +1,4 @@
-# Productionizing the Chat App
+# RAG chat: Productionizing the app
 
 This sample is designed to be a starting point for your own production application,
 but you should do a thorough review of the security and performance before deploying
diff --git a/samples/chat/README.md b/samples/chat/README.md
diff --git a/samples/data-ingestion/README.md b/samples/data-ingestion/README.md
diff --git a/samples/document-security/README.md b/samples/document-security/README.md
diff --git a/samples/private-endpoint/README.md b/samples/private-endpoint/README.md

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Debugging the app on App Service`
	`1`	`+# RAG chat: Debugging the app on App Service`
`2`	`2`
`3`	`3`	When you run `azd up` or `azd deploy`, it deploys your application to App Service,
`4`	`4`	`and displays the deployed endpoint in the console.`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Deploying with the Azure Developer CLI`
	`1`	`+# RAG chat: Deploying with the Azure Developer CLI`
`2`	`2`
`3`	`3`	`This guide includes advanced topics that are not necessary for a basic deployment. If you are new to the project, please consult the main [README](../README.md#deploying) for steps on deploying the project.`
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Deploying on Azure Container Apps`
	`1`	`+# RAG chat: Deploying on Azure Container Apps`
`2`	`2`
`3`	`3`	Due to [a limitation](https://github.com/Azure/azure-dev/issues/2736) of the Azure Developer CLI (`azd`), there can be only one host option in the [azure.yaml](../azure.yaml) file.
`4`	`4`	By default, `host: containerapp` is used and `host: appservice` is commented out.
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Customizing the Chat App`
	`1`	`+# RAG chat: Customizing the chat app`
`2`	`2`
`3`	`3`	`This guide provides more details for customizing the Chat App.`
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Deploying with minimal costs`
	`1`	`+# RAG chat: Deploying with minimal costs`
`2`	`2`
`3`	`3`	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.
`4`	`4`