How azure-samples/azure-ai-vercel-rag-starter works
Project Type and Purpose
• This is a full-stack Next.js application using the Vercel AI SDK to implement Retrieval-Augmented Generation (RAG).
• The frontend is a React/Next.js UI (with Tailwind CSS and Framer Motion) that streams AI chat responses.
• The backend is a set of Next.js route handlers (API routes) that orchestrate calls to Azure Cognitive Search and Azure OpenAI for vector retrieval and generative chat.
File Structure Analysis
• Top-level: configuration files (Dockerfile, Next.js configs, CI/CD workflows).
• /app/(preview)/api/chat/route.ts: serverless API route for chat requests.
• /app/(preview): Next.js 13 app directory with layout, global CSS, and page components.
• /components: React UI components (chat-input, interface, message container, project overview).
• /components/ui: shared UI primitives (button, drawer, input, label, resizable, switch).
• /lib/ai/search.ts: helper to query Azure Cognitive Search.
• /lib/env.mjs & /lib/utils.ts: environment variable loader and utilities.
Key Architecture Details from README
• Retrieval: uses lib/ai/search.ts to fetch top-k embeddings from Azure Cognitive Search.
• Chat generation: uses the Vercel AI SDK’s streamText and useChat to pipe data between backend and frontend.
• Real-time streaming: backend streams partial tokens back to the client for a typing effect.
Components
a. Main Components
• Client Browser (React/Next.js app)
• Next.js Frontend Layer (app directory, UI components)
• Next.js API Layer (/api/chat/route.ts)
• Azure Cognitive Search Service
• Azure OpenAI Service
• Environment & Config (Vercel AI SDK, .env variables)
b. Relationships and Data Flow
1. User in Browser types a message → triggers useChat hook.
2. Frontend calls the API route /api/chat.
3. API route:
– Loads embeddings and search parameters from environment.
– Calls Azure Cognitive Search to retrieve relevant documents/vectors.
– Constructs RAG prompt and calls Azure OpenAI to generate chat.
– Streams the AI response back to the frontend via Vercel streamText.
4. Frontend receives streaming tokens and updates the chat UI.
c. Architectural Patterns
• Serverless Functions: API route as ephemeral serverless endpoint.
• RAG Pattern: combine vector search results with LLM prompt.
• Streaming Data Flow: chunked responses for real-time UI updates.
d. Technologies & Frameworks
• Next.js 13 (App Router)
• Vercel AI SDK (useChat, streamText)
• Azure Cognitive Search (vector search, semantic config)
• Azure OpenAI (chat and embedding models)
• React, Tailwind CSS, Framer Motion