Azure-Samples/azure-search-openai-demo: a RAG chat app you deploy with azd

The gap this sample fills for Azure RAG builders

Retrieval-augmented generation is easy to describe and tedious to assemble. You need a document pipeline, an index with a schema that supports filtering and citations, a retrieval step, a prompt that keeps the model grounded, and a frontend that shows where each sentence came from. The README frames the project as a demonstration of "a few approaches for creating ChatGPT-like experiences over your own data using the Retrieval-Augmented Generation pattern," with Azure OpenAI for generation and Azure AI Search for indexing and retrieval. The audience is developers who already work in Azure and want a concrete reference rather than a library. It is not a framework you import. It is an application you deploy, then read. The repository ships sample data about a fictitious company called Zava, covering benefits, internal policies, job descriptions and roles, so the retrieval path has something to retrieve on the first run.

How retrieval, citations and the thought process are wired

The architecture diagram in docs/images shows the split: a frontend, a backend that calls Azure AI Search, and Azure OpenAI behind it. Documents are ingested into an Azure AI Search index, and the README points to docs/data_ingestion.md for supported document formats and for cloud data ingestion. At query time the backend retrieves matching content and passes it to a GPT model, which is gpt-5.4-mini in the description given in the README. Two features shape the developer experience more than the retrieval itself. First, the UI renders citations and the thought process for each answer, which turns an opaque completion into something you can audit against the source document. Second, the settings panel lives in the UI, so you can change behavior and experiment with options without editing code or redeploying. Optional layers sit on top of that core: multimodal models for image-heavy documents, speech input and output, and Microsoft Entra login with data access control. Each is documented separately and off by default. Application Insights handles tracing and monitoring.

Installing azure-search-openai-demo with azd

The README lists three entry paths: GitHub Codespaces, VS Code Dev Containers, and a local environment. The fastest is Codespaces, which provisions the standard Linux machine and opens the devcontainer configuration from the repository. For a local run you need the Azure Developer CLI, since azure.yaml is the deployment descriptor at the repository root. After authenticating, provisioning and deployment happen in one command:

azd auth login
azd up

The README states that your Azure account must hold Microsoft.Authorization/roleAssignments/write, such as Owner, User Access Administrator, or Role Based Access Control Administrator, plus Microsoft.Resources/deployments/write at the subscription level. If azd up fails partway, that is the first thing to check, not the application code. If you lack subscription-level rights, docs/deploy_existing.md describes deploying into an existing resource group where you have been granted RBAC. To run the app against the deployed resources, start the development server as the README instructs:

cd app
./start.sh

Once it is up, open the local URL and ask a question about the Zava benefits documents. You should see an answer with citations and the thought process behind it, which is the behavior the README advertises for the chat interface. Costs are not fixed: the README says pricing varies per region and usage and that it is not possible to predict exact costs, then lists the resources involved, including Azure Container Apps as the default host since 10/28/2024, Azure Container Registry on the Basic tier, and Azure OpenAI billed per 1K tokens with at least 1K tokens used per question. Azure App Service is provisioned only if you follow the App Service deployment guide.

The production warning you should read before the features list

The most important paragraph in the README is the security notice, and it is placed above everything else. It states that the template, the application code and the configuration it contains were built to demonstrate Microsoft Azure specific services and tools, and it strongly advises customers not to make this code part of their production environments without implementing or enabling additional security features. It then points to docs/productionizing.md and to the Azure OpenAI Landing Zone reference architecture. Treat that as the project's own scope statement. The default topology is not hardened, the sample data is fictional, and the repository is a demonstration of approaches rather than a supported product. The second constraint is permissions. Deployment requires role assignment and deployment write rights that many developers do not have on a shared subscription, and the README treats that as a hard prerequisite rather than a note. The third is cost visibility: because pricing varies by region and usage, the README declines to estimate totals and instead links the Azure pricing calculator. If you need a fixed monthly figure before you start, this sample will not give you one.

Other language samples and how they differ from this one

The README states plainly that the backend of this repository is written in Python and that JavaScript, .NET and Java samples based on this one exist, linking to them under the Azure AI Services documentation path. The practical difference is the language of the backend you will read and modify, not the architecture. Each variant follows the same shape: Azure AI Search for indexing and retrieval, Azure OpenAI for generation, and a frontend that renders citations. If your team writes C#, starting from the .NET sample means the retrieval and prompt code you adapt is already in a language your reviewers can maintain. Choosing this Python repository and porting it is more work than starting from the matching sample, unless you specifically want the Python ingestion and evaluation tooling, which is where the scripts, evals and prepdocslib directories in the repository layout live. That tooling is the real reason to pick this variant over its siblings.

Maintenance, releases and what upgrading actually involves

The repository is not archived and the last push was on 2026-09-02, so it is being updated. Recent releases show the kind of churn to expect: 2026-0717 upgraded the agentic knowledge base to GPT-5.4 and defaulted to a minimal retrieval effort, 2026-07-10 migrated to a Foundry project and moved the evaluation judge to gpt-5.4, and 2026-07-09b upgraded the msal JS packages to 5.x. Those are model and platform migrations, not bug fixes. Upgrading means re-running azd up against your subscription and re-checking your index, prompt settings and evaluation results, because a model change alters answer quality in ways a version number will not tell you. The evals directory and the separate evals-test workflow in the type-checking configuration suggest the project maintains its own comparison tooling, which is a useful starting point for measuring that drift. Budget for periodic redeploys rather than a one-time install. The project is licensed MIT, which permits commercial use and modification, but the licence covers the sample code only. The Azure services it provisions are billed separately under their own terms, and the productionizing guidance is documentation, not a warranty. Nothing here is legal advice; read the licence file and the service terms yourself.

Editorial conclusion

Adopt it if you need a working reference for retrieval-augmented chat on Azure and you are comfortable reading Bicep and Python to see how the pieces fit. Do not adopt it as a production service: the README states the template and its configuration were built to demonstrate Azure services and advises against making the code part of a production environment without additional security features. Before committing, verify that your account holds Microsoft.Authorization/roleAssignments/write and Microsoft.Resources/deployments/write, and read docs/productionizing.md, because those two permissions decide whether azd up can finish at all.

Frequently asked questions

Official sources

1. Azure-Samples/azure-search-openai-demo on GitHub
2. License: MIT
3. Project website
4. README
5. Releases