Repository files navigation

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 alsoJavaScript,.NET, andJava samples based on this one. Learn more aboutdeveloping AI apps using Azure AI Services.

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 ourproductionizing guide for tips, and consult theAzure OpenAI Landing Zone reference architecture for more best practices.

• Features
• Azure account requirements
  • Cost estimation
• Getting Started
  • GitHub Codespaces
  • VS Code Dev Containers
  • Local environment
• Deploying
  • Deploying again
• Running the development server
• Using the app
• Clean up
• Guidance
  • Resources

📺 Watch a video overview of the app.

This sample demonstrates a few approaches for creating ChatGPT-like experiences over your own data using the Retrieval Augmented Generation pattern. It uses Azure OpenAI Service to access a GPT model (gpt-4.1-mini), and Azure AI Search for data indexing and retrieval.

The repo includes sample data so it's ready to try end to end. In this sample application we use a fictitious company called Contoso Electronics, and the experience allows its employees to ask questions about the benefits, internal policies, as well as job descriptions and roles.

• Chat (multi-turn) and Q&A (single turn) interfaces
• Renders citations and thought process for each answer
• Includes settings directly in the UI to tweak the behavior and experiment with options
• Integrates Azure AI Search for indexing and retrieval of documents, with support formany document formats as well asintegrated vectorization
• Optional usage ofmultimodal models to reason over image-heavy documents
• Optional addition ofspeech input/output for accessibility
• Optional automation ofuser login and data access via Microsoft Entra
• Performance tracing and monitoring with Application Insights

IMPORTANT: In order to deploy and run this example, you'll need:

• Azure account. If you're new to Azure,get an Azure account for free and you'll get some free Azure credits to get started. Seeguide to deploying with the free trial.
• Azure account permissions:
  • Your Azure account must haveMicrosoft.Authorization/roleAssignments/write permissions, such asRole Based Access Control Administrator,User Access Administrator, orOwner. If you don't have subscription-level permissions, you must be grantedRBAC for an existing resource group anddeploy to that existing group.
  • Your Azure account also needsMicrosoft.Resources/deployments/write permissions on the subscription level.

Pricing varies per region and usage, so it isn't possible to predict exact costs for your usage.However, you can try theAzure pricing calculator for the resources below.

• Azure Container Apps: Default host for app deployment as of 10/28/2024. See more details inthe ACA deployment guide. Consumption plan with 1 CPU core, 2 GB RAM, minimum of 0 replicas. Pricing with Pay-as-You-Go.Pricing
• Azure Container Registry: Basic tier.Pricing
• Azure App Service: Only provisioned if you deploy to Azure App Service followingthe App Service deployment guide. Basic Tier with 1 CPU core, 1.75 GB RAM. Pricing per hour.Pricing
• Azure OpenAI: Standard tier, GPT and Ada models. Pricing per 1K tokens used, and at least 1K tokens are used per question.Pricing
• Azure AI Document Intelligence: SO (Standard) tier using pre-built layout. Pricing per document page, sample documents have 261 pages total.Pricing
• Azure AI Search: Basic tier, 1 replica, free level of semantic search. Pricing per hour.Pricing
• Azure Blob Storage: Standard tier with ZRS (Zone-redundant storage). Pricing per storage and read operations.Pricing
• Azure Cosmos DB: Only provisioned if you enabledchat history with Cosmos DB. Serverless tier. Pricing per request unit and storage.Pricing
• Azure AI Vision: Only provisioned if you enabledmultimodal approach. Pricing per 1K transactions.Pricing
• Azure AI Content Understanding: Only provisioned if you enabledmedia description. Pricing per 1K images.Pricing
• Azure Monitor: Pay-as-you-go tier. Costs based on data ingested.Pricing

To reduce costs, you can switch to free SKUs for various services, but those SKUs have limitations.See this guide ondeploying with minimal costs for more details.

⚠️ 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 runningazd down.

You have a few options for setting up this project.The easiest way to get started is GitHub Codespaces, since it will setup all the tools for you,but you can alsoset it up locally if desired.

You can run this repo virtually by using GitHub Codespaces, which will open a web-based VS Code in your browser:

Once the codespace opens (this may take several minutes), open a terminal window.

A related option is VS Code Dev Containers, which will open the project in your local VS Code using theDev Containers extension:

1. Start Docker Desktop (install it if not already installed)

2. Open the project:

3. In the VS Code window that opens, once the project files show up (this may take several minutes), open a terminal window.

1. Install the required tools:

   • Azure Developer CLI
   • Python 3.10, 3.11, 3.12, 3.13, or 3.14
     • Important: Python and the pip package manager must be in the path in Windows for the setup scripts to work.
     • Important: Ensure you can runpython --version from console. On Ubuntu, you might need to runsudo apt install python-is-python3 to linkpython topython3.
   • Node.js 20+
   • Git
   • Powershell 7+ (pwsh) - For Windows users only.
     • Important: Ensure you can runpwsh.exe from a PowerShell terminal. If this fails, you likely need to upgrade PowerShell.

2. Create a new folder and switch to it in the terminal.

3. Run this command to download the project code:

   azd init -t azure-search-openai-demo

   Note that this command will initialize a git repository, so you do not need to clone this repository.

The steps below will provision Azure resources and deploy the application code to Azure Container Apps. To deploy to Azure App Service instead, followthe app service deployment guide.

1. Login to your Azure account:

   azd auth login

   For GitHub Codespaces users, if the previous command fails, try:

    azd auth login --use-device-code

2. Create a new azd environment:

   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 toazd going forward.

3. (Optional) This is the point where you can customize the deployment by setting environment variables, in order touse existing resources,enable optional features (such as auth or vision), ordeploy low-cost options, ordeploy with the Azure free trial.

4. Runazd 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 runazd 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 theOpenAI model availability table and may become outdated as availability changes.

5. 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:

NOTE: It may take 5-10 minutes after you see 'SUCCESS' for the application to be fully deployed. If you see a "Python Developer" welcome screen or an error page, then wait a bit and refresh the page.

If you've only changed the backend/frontend code in theapp folder, then you don't need to re-provision the Azure resources. You can just run:

azd deploy

If you've changed the infrastructure files (infra folder orazure.yaml), then you'll need to re-provision the Azure resources. You can do that by running:

azd up

You can only run a development server locallyafter having successfully run theazd up command. If you haven't yet, follow thedeploying steps above.

1. Runazd auth login if you have not logged in recently.
2. Start the server:

Windows:

./app/start.ps1

Linux/Mac:

./app/start.sh

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 inthe local development guide.

• In Azure: navigate to the Azure WebApp deployed by azd. The URL is printed out when azd completes (as "Endpoint"), or you can find it in the Azure portal.
• Running locally: navigate to 127.0.0.1:50505

Once in the web app:

• Try different topics in chat or Q&A context. For chat, try follow up questions, clarifications, ask to simplify or elaborate on answer, etc.
• Explore citations and sources
• Click on "settings" to try different options, tweak prompts, etc.

To clean up all the resources created by this sample:

1. Runazd down
2. When asked if you are sure you want to continue, entery
3. When asked if you want to permanently delete the resources, entery

The resource group and all the resources will be deleted.

You can find extensive documentation in thedocs folder:

• Deploying:
  • Troubleshooting deployment
    • Debugging the app on App Service
  • Deploying with azd: deep dive and CI/CD
  • Deploying with existing Azure resources
  • Deploying from a free account
  • Enabling optional features
    • All features
    • Login and access control
    • Multimodal
    • Reasoning
    • Private endpoints
    • Agentic retrieval
  • Sharing deployment environments
• Local development
• Customizing the app
• App architecture
• HTTP Protocol
• Data ingestion
• Evaluation
• Safety evaluation
• Monitoring with Application Insights
• Productionizing
• Alternative RAG chat samples

• 📖 Docs: Get started using the chat with your data sample
• 📖 Blog: Revolutionize your Enterprise Data with ChatGPT: Next-gen Apps w/ Azure OpenAI and AI Search
• 📖 Docs: Azure AI Search
• 📖 Docs: Azure OpenAI Service
• 📖 Docs: Comparing Azure OpenAI and OpenAI
• 📖 Blog: Access Control in Generative AI applications with Azure AI Search
• 📺 Talk: Quickly build and deploy OpenAI apps on Azure, infused with your own data
• 📺 Video: RAG Deep Dive Series

This is a sample built to demonstrate the capabilities of modern Generative AI apps and how they can be built in Azure.For help with deploying this sample, please post inGitHub Issues. If you're a Microsoft employee, you can also post inour Teams channel.

This repository is supported by the maintainers,not by Microsoft Support,so please use the support mechanisms described above, and we will do our best to help you out.

For general questions about developing AI solutions on Azure,join the Azure AI Foundry Developer Community:

Note: The PDF documents used in this demo contain information generated using a language model (Azure OpenAI Service). The information contained in these documents is only for demonstration purposes and does not reflect the opinions or beliefs of Microsoft. Microsoft makes no representations or warranties of any kind, express or implied, about the completeness, accuracy, reliability, suitability or availability with respect to the information contained in this document. All rights reserved to Microsoft.