Skip to content

Commit

Permalink
Refactor the README to move advanced sections into docs (#2165)
Browse files Browse the repository at this point in the history 
* Refactor the docs

* Update docs readme

* Colon

* Update start commands
  • Loading branch information
@pamelafox
pamelafox authored Nov 21, 2024
1 parent 202e726 commit 57e6bba
Show file tree
Hide file tree
Showing 7 changed files with 143 additions and 138 deletions.
74 changes: 24 additions & 50 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,59 +12,15 @@ This project has adopted the [Microsoft Open Source Code of Conduct](https://ope
For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
contact [[email protected]](mailto:[email protected]) with any additional questions or comments.

- [Code of Conduct](#code-of-conduct)
- [Found an Issue?](#found-an-issue)
- [Want a Feature?](#want-a-feature)
- [Submission Guidelines](#submission-guidelines)
- [Submitting an Issue](#submitting-an-issue)
- [Submitting a Pull Request (PR)](#submitting-a-pull-request-pr)
- [Submitting a Pull Request (PR)](#submitting-a-pull-request-pr)
- [Setting up the development environment](#setting-up-the-development-environment)
- [Running unit tests](#running-unit-tests)
- [Running E2E tests](#running-e2e-tests)
- [Code Style](#code-style)
- [Adding new azd environment variables](#add-new-azd-environment-variables)
- [Code style](#code-style)
- [Adding new azd environment variables](#adding-new-azd-environment-variables)
- [Adding new UI strings](#adding-new-ui-strings)

## Code of Conduct

Help us keep this project open and inclusive. Please read and follow our [Code of Conduct](https://opensource.microsoft.com/codeofconduct/).

## Found an Issue?

If you find a bug in the source code or a mistake in the documentation, you can help us by
[submitting an issue](#submitting-an-issue) to the GitHub Repository. Even better, you can
[submit a Pull Request](#submitting-a-pull-request-pr) with a fix.

## Want a Feature?

You can *request* a new feature by [submitting an issue](#submitting-an-issue) to the GitHub
Repository. If you would like to *implement* a new feature, please submit an issue with
a proposal for your work first, to be sure that we can use it.

- **Small Features** can be crafted and directly [submitted as a Pull Request](#submitting-a-pull-request-pr).

## Submission Guidelines

### Submitting an Issue

Before you submit an issue, search the archive, maybe your question was already answered.

If your issue appears to be a bug, and hasn't been reported, open a new issue.
Help us to maximize the effort we can spend fixing issues and adding new
features, by not reporting duplicate issues. Providing the following information will increase the
chances of your issue being dealt with quickly:

- **Overview of the Issue** - if an error is being thrown a non-minified stack trace helps
- **Version** - what version is affected (e.g. 0.1.2)
- **Motivation for or Use Case** - explain what are you trying to do and why the current behavior is a bug for you
- **Browsers and Operating System** - is this a problem with all browsers?
- **Reproduce the Error** - provide a live example or a unambiguous set of steps
- **Related Issues** - has a similar issue been reported before?
- **Suggest a Fix** - if you can't fix the bug yourself, perhaps you can point to what might be
causing the problem (line of code or commit)

You can file new issues by providing the above information at the corresponding repository's issues link: <https://github.com/[organization-name>]/[repository-name]/issues/new].

### Submitting a Pull Request (PR)
## Submitting a Pull Request (PR)

Before you submit your Pull Request (PR) consider the following guidelines:

Expand Down Expand Up @@ -135,7 +91,7 @@ playwright show-trace test-results/<trace-zip>

You can also use the online trace viewer at <https://trace.playwright.dev/>

## Code Style
## Code style

This codebase includes several languages: TypeScript, Python, Bicep, Powershell, and Bash.
Code should follow the standard conventions of each language.
Expand Down Expand Up @@ -169,3 +125,21 @@ When adding new azd environment variables, please remember to update:
1. App Service's [azure.yaml](./azure.yaml)
1. [ADO pipeline](.azdo/pipelines/azure-dev.yml).
1. [Github workflows](.github/workflows/azure-dev.yml)

## Adding new UI strings

When adding new UI strings, please remember to update all translations.
For any translations that you generate with an AI tool,
please indicate in the PR description which language's strings were AI-generated.

Here are community contributors that can review translations:

| Language | Contributor |
|----------|---------------------|
| Danish | @EMjetrot |
| French | @manekinekko |
| Japanese | @bnodir |
| Norwegian| @@jeannotdamoiseaux |
| Portugese| @glaucia86 |
| Spanish | @miguelmsft |
| Turkish | @mertcakdogan |
119 changes: 47 additions & 72 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,10 @@ This solution's backend is written in Python. There are also [**JavaScript**](ht
[![Open in GitHub Codespaces](https://img.shields.io/static/v1?style=for-the-badge&label=GitHub+Codespaces&message=Open&color=brightgreen&logo=github)](https://github.com/codespaces/new?hide_repo_select=true&ref=main&repo=599293758&machine=standardLinux32gb&devcontainer_path=.devcontainer%2Fdevcontainer.json&location=WestUs2)
[![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/azure-samples/azure-search-openai-demo)

## Important Security Notice

This template, the application code and configuration it contains, has been built to showcase Microsoft Azure specific services and tools. We strongly advise our customers not to make this code part of their production environments without implementing or enabling additional security features. See our [productionizing guide](docs/productionizing.md) for tips, and consult the [Azure OpenAI Landing Zone reference architecture](https://techcommunity.microsoft.com/blog/azurearchitectureblog/azure-openai-landing-zone-reference-architecture/3882102) for more best practices.

## Table of Contents

- [Features](#features)
Expand All @@ -37,15 +41,10 @@ This solution's backend is written in Python. There are also [**JavaScript**](ht
- [Local environment](#local-environment)
- [Deploying](#deploying)
- [Deploying again](#deploying-again)
- [Sharing environments](#sharing-environments)
- [Running locally](#running-locally)
- [Running the development server](#running-the-development-server)
- [Using the app](#using-the-app)
- [Clean up](#clean-up)
- [Guidance](#guidance)
- [Customizing the UI and data](#customizing-the-ui-and-data)
- [Monitoring with Application Insights](#monitoring-with-application-insights)
- [Productionizing](#productionizing)
- [Troubleshooting](#troubleshooting)
- [Resources](#resources)

![Chat screen](docs/images/chatscreen.png)
Expand Down Expand Up @@ -196,26 +195,28 @@ If you've changed the infrastructure files (`infra` folder or `azure.yaml`), the
azd up
```

#### Sharing environments
## Running the development server

You can only run a development server locally **after** having successfully run the `azd up` command. If you haven't yet, follow the [deploying](#deploying) steps above.
1. Run `azd auth login` if you have not logged in recently.
2. Start the server:
To give someone else access to a completely deployed and existing environment,
either you or they can follow these steps:
Windows:
1. Install the [Azure CLI](https://learn.microsoft.com/cli/azure/install-azure-cli)
1. Run `azd init -t azure-search-openai-demo` or clone this repository.
1. Run `azd env refresh -e {environment name}`
They will need the azd environment name, subscription ID, and location to run this command. You can find those values in your `.azure/{env name}/.env` file. This will populate their azd environment's `.env` file with all the settings needed to run the app locally.
1. Set the environment variable `AZURE_PRINCIPAL_ID` either in that `.env` file or in the active shell to their Azure ID, which they can get with `az ad signed-in-user show`.
1. Run `./scripts/roles.ps1` or `.scripts/roles.sh` to assign all of the necessary roles to the user. If they do not have the necessary permission to create roles in the subscription, then you may need to run this script for them. Once the script runs, they should be able to run the app locally.
```shell
./app/start.ps1
```
## Running locally
Linux/Mac:
You can only run locally **after** having successfully run the `azd up` command. If you haven't yet, follow the [deploying](#deploying) steps above.
```shell
./app/start.sh
```
1. Run `azd auth login`
2. Change dir to `app`
3. Run `./start.ps1` or `./start.sh` or run the "VS Code Task: Start App" to start the project locally.
VS Code: Run the "VS Code Task: Start App" task.
It's also possible to enable hotloading or the VS Code debugger.
See more tips in [the local development guide](docs/localdev.md).

## Using the app
Expand All @@ -241,61 +242,35 @@ The resource group and all the resources will be deleted.

## Guidance

Besides the tips below, you can find extensive documentation in the [docs](docs/README.md) folder.

### Customizing the UI and data

Once you successfully deploy the app, you can start customizing it for your needs: changing the text, tweaking the prompts, and replacing the data. Consult the [app customization guide](docs/customization.md) as well as the [data ingestion guide](docs/data_ingestion.md) for more details.

### Monitoring with Application Insights

By default, deployed apps use Application Insights for the tracing of each request, along with the logging of errors.

To see the performance data, go to the Application Insights resource in your resource group, click on the "Investigate -> Performance" blade and navigate to any HTTP request to see the timing data.
To inspect the performance of chat requests, use the "Drill into Samples" button to see end-to-end traces of all the API calls made for any chat request:

![Tracing screenshot](docs/images/transaction-tracing.png)

To see any exceptions and server errors, navigate to the "Investigate -> Failures" blade and use the filtering tools to locate a specific exception. You can see Python stack traces on the right-hand side.

You can also see chart summaries on a dashboard by running the following command:

```shell
azd monitor
```

### Productionizing

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
to production. Read through our [productionizing guide](docs/productionizing.md) for more details.

### Troubleshooting

Here are the most common failure scenarios and solutions:

1. The subscription (`AZURE_SUBSCRIPTION_ID`) doesn't have access to the Azure OpenAI service. Please ensure `AZURE_SUBSCRIPTION_ID` matches the ID specified in the [OpenAI access request process](https://aka.ms/oai/access).
1. You're attempting to create resources in regions not enabled for Azure OpenAI (e.g. East US 2 instead of East US), or where the model you're trying to use isn't enabled. See [this matrix of model availability](https://aka.ms/oai/models).

1. You've exceeded a quota, most often number of resources per region. See [this article on quotas and limits](https://aka.ms/oai/quotas).
1. You're getting "same resource name not allowed" conflicts. That's likely because you've run the sample multiple times and deleted the resources you've been creating each time, but are forgetting to purge them. Azure keeps resources for 48 hours unless you purge from soft delete. See [this article on purging resources](https://learn.microsoft.com/azure/cognitive-services/manage-resources?tabs=azure-portal#purge-a-deleted-resource).
1. You see `CERTIFICATE_VERIFY_FAILED` when the `prepdocs.py` script runs. That's typically due to incorrect SSL certificates setup on your machine. Try the suggestions in this [StackOverflow answer](https://stackoverflow.com/questions/35569042/ssl-certificate-verify-failed-with-python3/43855394#43855394).

1. After running `azd up` and visiting the website, you see a '404 Not Found' in the browser. Wait 10 minutes and try again, as it might be still starting up. Then try running `azd deploy` and wait again. If you still encounter errors with the deployed app and are deploying to App Service, consult the [guide on debugging App Service deployments](docs/appservice.md). Please file an issue if the logs don't help you resolve the error.
You can find extensive documentation in the [docs](docs/README.md) folder:

- Deploying:
- [Troubleshooting deployment](docs/deploy_troubleshooting.md)
- [Debugging the app on App Service](docs/appservice.md)
- [Deploying with azd: deep dive and CI/CD](docs/azd.md)
- [Deploying with existing Azure resources](docs/deploy_existing.md)
- [Deploying from a free account](docs/deploy_lowcost.md)
- [Enabling optional features](docs/deploy_features.md)
- [Login and access control](docs/login_and_acl.md)
- [GPT-4 Turbo with Vision](docs/gpt4v.md)
- [Private endpoints](docs/deploy_private.md)
- [Sharing deployment environments](docs/sharing_environments.md)
- [Local development](docs/localdev.md)
- [Customizing the app](docs/customization.md)
- [Data ingestion](docs/data_ingestion.md)
- [Monitoring with Application Insights](docs/monitoring.md)
- [Productionizing](docs/productionizing.md)
- [Alternative RAG chat samples](docs/other_samples.md)

### Resources

- [Additional documentation for this app](docs/README.md)
- [📖 Revolutionize your Enterprise Data with ChatGPT: Next-gen Apps w/ Azure OpenAI and AI Search](https://techcommunity.microsoft.com/blog/azure-ai-services-blog/revolutionize-your-enterprise-data-with-chatgpt-next-gen-apps-w-azure-openai-and/3762087)
- [📖 Azure AI Search](https://learn.microsoft.com/azure/search/search-what-is-azure-search)
- [📖 Azure OpenAI Service](https://learn.microsoft.com/azure/cognitive-services/openai/overview)
- [📖 Comparing Azure OpenAI and OpenAI](https://learn.microsoft.com/azure/cognitive-services/openai/overview#comparing-azure-openai-and-openai/)
- [📖 Access Control in Generative AI applications with Azure AI Search](https://techcommunity.microsoft.com/blog/azure-ai-services-blog/access-control-in-generative-ai-applications-with-azure-ai-search/3956408)
- [📺 Quickly build and deploy OpenAI apps on Azure, infused with your own data](https://www.youtube.com/watch?v=j8i-OM5kwiY)
- [📺 AI Chat App Hack series](https://www.youtube.com/playlist?list=PL5lwDBUC0ag6_dGZst5m3G72ewfwXLcXV)
- [📖 Blog: Revolutionize your Enterprise Data with ChatGPT: Next-gen Apps w/ Azure OpenAI and AI Search](https://techcommunity.microsoft.com/blog/azure-ai-services-blog/revolutionize-your-enterprise-data-with-chatgpt-next-gen-apps-w-azure-openai-and/3762087)
- [📖 Docs: Azure AI Search](https://learn.microsoft.com/azure/search/search-what-is-azure-search)
- [📖 Docs: Azure OpenAI Service](https://learn.microsoft.com/azure/cognitive-services/openai/overview)
- [📖 Docs: Comparing Azure OpenAI and OpenAI](https://learn.microsoft.com/azure/cognitive-services/openai/overview#comparing-azure-openai-and-openai/)
- [📖 Blog: Access Control in Generative AI applications with Azure AI Search](https://techcommunity.microsoft.com/blog/azure-ai-services-blog/access-control-in-generative-ai-applications-with-azure-ai-search/3956408)
- [📺 Talk: Quickly build and deploy OpenAI apps on Azure, infused with your own data](https://www.youtube.com/watch?v=j8i-OM5kwiY)
- [📺 Talks: AI Chat App Hack series](https://www.youtube.com/playlist?list=PL5lwDBUC0ag6_dGZst5m3G72ewfwXLcXV)

### Getting help

Expand Down
31 changes: 17 additions & 14 deletions docs/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,17 +3,20 @@
Consult the main [README](../README.md) for general information about the project.
These are advanced topics that are not necessary for a basic deployment.

* [Deploying with the Azure Developer CLI](azd.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)
* [Private endpoints](deploy_private.md)
* [Debugging the app on App Service](appservice.md)
* [Local development](localdev.md)
* [App customization](customization.md)
* [Private access](deploy_private.md)
* [Data ingestion](data_ingestion.md)
* [Productionizing](productionizing.md)
* [Alternative RAG chat samples](other_samples.md)
- Deploying:
- [Troubleshooting deployment](docs/deploy_troubleshooting.md)
- [Debugging the app on App Service](appservice.md)
- [Deploying with azd: deep dive and CI/CD](azd.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)
- [Private endpoints](deploy_private.md)
- [Sharing deployment environments](sharing_environments.md)
- [Local development](localdev.md)
- [Customizing the app](customization.md)
- [Data ingestion](data_ingestion.md)
- [Monitoring with Application Insights](monitoring.md)
- [Productionizing](productionizing.md)
- [Alternative RAG chat samples](other_samples.md)
13 changes: 13 additions & 0 deletions docs/deploy_troubleshooting.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
# RAG chat: Troubleshooting deployment

If you are experiencing an error when deploying the RAG chat solution using the [deployment steps](../README.md#deploying), this guide will help you troubleshoot common issues.

1. You're attempting to create resources in regions not enabled for Azure OpenAI (e.g. East US 2 instead of East US), or where the model you're trying to use isn't enabled. See [this matrix of model availability](https://aka.ms/oai/models).

1. You've exceeded a quota, most often number of resources per region. See [this article on quotas and limits](https://aka.ms/oai/quotas).

1. You're getting "same resource name not allowed" conflicts. That's likely because you've run the sample multiple times and deleted the resources you've been creating each time, but are forgetting to purge them. Azure keeps resources for 48 hours unless you purge from soft delete. See [this article on purging resources](https://learn.microsoft.com/azure/cognitive-services/manage-resources?tabs=azure-portal#purge-a-deleted-resource).

1. You see `CERTIFICATE_VERIFY_FAILED` when the `prepdocs.py` script runs. That's typically due to incorrect SSL certificates setup on your machine. Try the suggestions in this [StackOverflow answer](https://stackoverflow.com/questions/35569042/ssl-certificate-verify-failed-with-python3/43855394#43855394).

1. After running `azd up` and visiting the website, you see a '404 Not Found' in the browser. Wait 10 minutes and try again, as it might be still starting up. Then try running `azd deploy` and wait again. If you still encounter errors with the deployed app and are deploying to App Service, consult the [guide on debugging App Service deployments](/docs/appservice.md). Please file an issue if the logs don't help you resolve the error.
17 changes: 15 additions & 2 deletions docs/localdev.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,8 +14,21 @@ After deploying the app to Azure, you may want to continue development locally.
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.

1. Run `azd auth login`
2. Change dir to `app`
3. Run `./start.ps1` or `./start.sh` or run the "VS Code Task: Start App" to start the project locally.
2. Start the server:

Windows:

```shell
./app/start.ps1
```

Linux/Mac:

```shell
./app/start.sh
```

VS Code: Run the "VS Code Task: Start App" task.

## Hot reloading frontend and backend files

Expand Down
Loading

0 comments on commit 57e6bba

Please sign in to comment.