diff --git a/README.md b/README.md index 08cc88fd77..cce8567c00 100644 --- a/README.md +++ b/README.md @@ -70,6 +70,8 @@ The repo includes sample data so it's ready to try end to end. In this sample ap ![RAG Architecture](docs/images/appcomponents.png) +For a detailed interactive architecture diagram with full component descriptions, see the [Architecture Overview](docs/architecture.md). + ## Azure account requirements **IMPORTANT:** In order to deploy and run this example, you'll need: @@ -246,6 +248,7 @@ The resource group and all the resources will be deleted. You can find extensive documentation in the [docs](docs/README.md) folder: +- [Architecture Overview](docs/architecture.md) - Deploying: - [Troubleshooting deployment](docs/deploy_troubleshooting.md) - [Debugging the app on App Service](docs/appservice.md) diff --git a/docs/README.md b/docs/README.md index 67cf6d96b1..d1d6c9bd30 100644 --- a/docs/README.md +++ b/docs/README.md @@ -3,6 +3,8 @@ Consult the main [README](../README.md) for general information about the project. These are advanced topics that are not necessary for a basic deployment. +- [Architecture Overview](architecture.md) - Detailed system architecture diagram and component descriptions + - Deploying: - [Troubleshooting deployment](docs/deploy_troubleshooting.md) - [Debugging the app on App Service](appservice.md) diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000000..48cd611c05 --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,151 @@ +# Architecture Overview + +This document provides a detailed architecture diagram of the Azure Search OpenAI demo application, showing the complete RAG (Retrieval Augmented Generation) flow and all components. + +## System Architecture + +```mermaid +graph TB + %% User Interface Layer + User[👤 User] --> WebApp[🌐 React Frontend
TypeScript/Vite] + + %% Application Layer + WebApp --> Backend[🐍 Python Backend
Quart API] + + %% Authentication (Optional) + Backend --> Auth{🔐 Authentication
Enabled?} + Auth -->|Yes| EntraID[🏢 Microsoft Entra ID
Azure AD] + Auth -->|No| ProcessRequest[Process Request] + EntraID --> ProcessRequest + + %% Core RAG Flow + ProcessRequest --> RAGFlow{📋 Request Type} + RAGFlow -->|Chat| ChatApproach[💬 Chat Approach
chatreadretrieveread.py] + RAGFlow -->|Ask| AskApproach[❓ Ask Approach
retrievethenread.py] + RAGFlow -->|Vision| VisionApproach[👁️ Vision Approach
GPT-4V enabled] + + %% Search and Retrieval + ChatApproach --> QueryRewrite[🔄 Query Rewriting
OpenAI API] + QueryRewrite --> SearchIndex[🔍 Azure AI Search
Vector + Keyword Search] + AskApproach --> SearchIndex + VisionApproach --> SearchIndex + VisionApproach --> VisionAPI[👁️ Azure AI Vision
Image Analysis] + + %% Document Storage and Processing + SearchIndex --> BlobStorage[💾 Azure Blob Storage
Document Storage] + DocProcessor[📄 Document Processor
prepdocs.py] --> BlobStorage + DocProcessor --> SearchIndex + DocProcessor --> FormRecognizer[📋 Azure AI Document Intelligence
Text Extraction] + DocProcessor --> OpenAIEmbedding[🧮 Azure OpenAI
Embedding Generation] + + %% AI Processing + ChatApproach --> OpenAI[🤖 Azure OpenAI Service
GPT Models] + AskApproach --> OpenAI + VisionApproach --> OpenAI + OpenAIEmbedding --> SearchIndex + + %% Response Generation + OpenAI --> ResponseProcessor[📝 Response Processing
Citations & Sources] + ResponseProcessor --> WebApp + + %% Optional Features + Backend --> ChatHistory{💭 Chat History
Enabled?} + ChatHistory -->|Cosmos DB| CosmosDB[🌌 Azure Cosmos DB
Persistent Storage] + ChatHistory -->|Browser| BrowserStorage[🖥️ Browser Storage
Local Storage] + ChatHistory -->|Disabled| NoHistory[No Storage] + + Backend --> Speech{🎤 Speech
Enabled?} + Speech -->|Yes| SpeechService[🗣️ Azure Speech Service
STT/TTS] + Speech -->|No| NoSpeech[No Speech] + + %% Monitoring and Observability + Backend --> AppInsights[📊 Azure Application Insights
Monitoring & Telemetry] + OpenAI --> AppInsights + SearchIndex --> AppInsights + + %% Deployment Infrastructure + WebApp --> ContainerApps[📦 Azure Container Apps
Default Hosting] + Backend --> ContainerApps + ContainerApps --> ContainerRegistry[📋 Azure Container Registry
Container Images] + + %% Alternative Deployment + WebApp -.-> AppService[🌐 Azure App Service
Alternative Hosting] + Backend -.-> AppService + + %% Security and Access Control + Backend --> AccessControl{🛡️ Access Control
Enabled?} + AccessControl -->|Yes| SecurityFilter[🔒 Security Filters
OID/Groups based] + AccessControl -->|No| PublicAccess[Public Access] + SecurityFilter --> SearchIndex + + %% Styling + classDef userInterface fill:#e1f5fe + classDef application fill:#f3e5f5 + classDef azureService fill:#fff3e0 + classDef storage fill:#e8f5e8 + classDef optional fill:#fce4ec + classDef security fill:#ffebee + + class User,WebApp userInterface + class Backend,ProcessRequest,RAGFlow,ChatApproach,AskApproach,VisionApproach,ResponseProcessor application + class OpenAI,SearchIndex,FormRecognizer,OpenAIEmbedding,VisionAPI,AppInsights,ContainerApps,ContainerRegistry,AppService,SpeechService azureService + class BlobStorage,CosmosDB,BrowserStorage storage + class ChatHistory,Speech,NoHistory,NoSpeech,VisionApproach optional + class Auth,EntraID,AccessControl,SecurityFilter,PublicAccess security +``` + +## Key Components + +### Frontend Layer + +- **React Frontend**: Modern web application built with TypeScript and Vite +- **User Interface**: Provides Chat and Ask interfaces for different interaction modes + +### Backend Layer + +- **Python API**: Quart-based asynchronous web framework +- **RAG Approaches**: Different strategies for retrieval and generation + - Chat: Multi-turn conversations with context + - Ask: Single-turn Q&A + - Vision: Image-aware processing with GPT-4V + +### Azure Services + +- **Azure OpenAI Service**: Core AI model hosting (GPT-4, GPT-3.5, Ada embeddings) +- **Azure AI Search**: Vector and keyword search with semantic ranking +- **Azure Blob Storage**: Document storage and content management +- **Azure AI Document Intelligence**: Text extraction from various document formats +- **Azure Container Apps**: Primary hosting platform (scalable, serverless) +- **Azure Application Insights**: Monitoring, logging, and telemetry + +### Optional Components + +- **Microsoft Entra ID**: Authentication and authorization +- **Azure Cosmos DB**: Persistent chat history storage +- **Azure AI Vision**: Image analysis for vision-enabled scenarios +- **Azure Speech Service**: Speech-to-text and text-to-speech capabilities + +### Data Flow + +1. **Document Ingestion**: Documents are processed by `prepdocs.py`, which extracts text using Azure AI Document Intelligence and generates embeddings using Azure OpenAI +2. **User Query**: User submits a question through the React frontend +3. **Authentication** (Optional): User identity is verified against Microsoft Entra ID +4. **Query Processing**: Backend determines the appropriate RAG approach based on request type +5. **Search & Retrieval**: Query is executed against Azure AI Search to find relevant documents +6. **AI Generation**: Retrieved content is combined with the user query and sent to Azure OpenAI for response generation +7. **Response**: AI-generated response with citations is returned to the user + +### Security Features + +- **Access Control**: Optional row-level security based on user identity +- **Security Filters**: OID and group-based filtering of search results +- **Private Endpoints**: Network isolation capabilities for enhanced security + +## Deployment Options + +The application supports two primary deployment modes: + +- **Azure Container Apps** (Default): Serverless container hosting with automatic scaling +- **Azure App Service**: Traditional PaaS hosting option + +Both options use Azure Container Registry for container image management and Azure Application Insights for monitoring.