Skip to content

Commit 770a906

Browse files
gopal-raj-sureshgopal-raj-suresh
committed
Add RAGChatbot blueprint
1 parent 68b7ef4 commit 770a906

34 files changed

Lines changed: 3366 additions & 0 deletions

‎RAGChatbot/.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
**/.env
2+
**/test.txt

‎RAGChatbot/README.md‎

Lines changed: 227 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,227 @@
1+
## RAG Chatbot
2+
3+
A full-stack Retrieval-Augmented Generation (RAG) application that enables intelligent, document-based question answering.
4+
The system integrates a FastAPI backend powered by LangChain, FAISS, and AI models, alongside a modern React + Vite + Tailwind CSS frontend for an intuitive chat experience.
5+
6+
## Table of Contents
7+
8+
- [Project Overview](#project-overview)
9+
- [Features](#features)
10+
- [Architecture](#architecture)
11+
- [Prerequisites](#prerequisites)
12+
- [Quick Start Deployment](#quick-start-deployment)
13+
- [User Interface](#user-interface)
14+
- [Troubleshooting](#troubleshooting)
15+
16+
---
17+
18+
## Project Overview
19+
20+
The **RAG Chatbot** demonstrates how retrieval-augmented generation can be used to build intelligent, document-grounded conversational systems. It retrieves relevant information from a knowledge base, passes it to a large language model, and generates a concise and reliable answer to the user’s query. This project integrates seamlessly with cloud-hosted APIs or local model endpoints, offering flexibility for research, enterprise, or educational use.
21+
22+
---
23+
24+
## Features
25+
26+
**Backend**
27+
28+
- Clean PDF upload with validation
29+
- LangChain-powered document processing
30+
- FAISS-CPU vector store for efficient similarity search
31+
- Enterprise inference endpoints for embeddings and LLM
32+
- Keycloak authentication for secure API access
33+
- Comprehensive error handling and logging
34+
- File validation and size limits
35+
- CORS enabled for web integration
36+
- Health check endpoints
37+
- Modular architecture (routes + services)
38+
39+
**Frontend**
40+
41+
- PDF file upload with drag-and-drop support
42+
- Real-time chat interface
43+
- Modern, responsive design with Tailwind CSS
44+
- Built with Vite for fast development
45+
- Live status updates
46+
- Mobile-friendly
47+
48+
---
49+
50+
## Architecture
51+
52+
Below is the architecture as it consists of a server that waits for documents to embed and index into a vector database. Once documents have been uploaded, the server will wait for user queries which initiates a similarity search in the vector database before calling the LLM service to summarize the findings.
53+
54+
![Architecture Diagram](./images/RAG%20Model%20System%20Design.png)
55+
56+
**Service Components:**
57+
58+
1. **React Web UI (Port 3000)** - Provides intuitive chat interface with drag-and-drop PDF upload, real-time messaging, and document-grounded Q&A interaction
59+
60+
2. **FastAPI Backend (Port 5001)** - Handles document processing, FAISS vector storage, LangChain integration, and orchestrates retrieval-augmented generation for accurate responses
61+
62+
**Typical Flow:**
63+
64+
1. User uploads a document through the web UI.
65+
2. The backend processes the document by splitting it and transforming it into embeddings before storing it in the vector database.
66+
3. User sends a question through the web UI.
67+
4. The backend retrieves relevant content from stored documents.
68+
5. The model generates a response based on retrieved context.
69+
6. The answer is displayed to the user via the UI.
70+
71+
---
72+
73+
## Prerequisites
74+
75+
### System Requirements
76+
77+
Before you begin, ensure you have the following installed:
78+
79+
- **Docker and Docker Compose**
80+
- **Enterprise inference endpoint access** (Keycloak authentication)
81+
82+
### Verify Docker Installation
83+
84+
```bash
85+
# Check Docker version
86+
docker --version
87+
88+
# Check Docker Compose version
89+
docker compose version
90+
91+
# Verify Docker is running
92+
docker ps
93+
```
94+
95+
## Quick Start Deployment
96+
97+
### Clone the Repository
98+
99+
```bash
100+
git clone https://github.com/opea-project/GenAIExamples.git
101+
cd GenAIExamples/RAGChatbot
102+
```
103+
104+
### Set up the Environment
105+
106+
This application requires an `.env` file in the `api` directory for proper configuration. Create it with the commands below:
107+
108+
```bash
109+
# Create the .env file in the api directory
110+
mkdir -p api
111+
cat > api/.env << EOF
112+
# Backend API URL (accessible from frontend)
113+
VITE_API_URL=https://backend:5000
114+
115+
# Required - Enterprise/Keycloak Configuration
116+
BASE_URL=https://api.example.com
117+
KEYCLOAK_REALM=master
118+
KEYCLOAK_CLIENT_ID=api
119+
KEYCLOAK_CLIENT_SECRET=your_client_secret
120+
121+
# Required - Model Configuration
122+
EMBEDDING_MODEL_ENDPOINT=bge-base-en-v1.5
123+
INFERENCE_MODEL_ENDPOINT=Llama-3.1-8B-Instruct
124+
EMBEDDING_MODEL_NAME=bge-base-en-v1.5
125+
INFERENCE_MODEL_NAME=meta-llama/Llama-3.1-8B-Instruct
126+
EOF
127+
```
128+
129+
Or manually create `api/.env` with:
130+
131+
```bash
132+
# Backend API URL (accessible from frontend)
133+
VITE_API_URL=https://backend:5000
134+
135+
# Required - Enterprise/Keycloak Configuration
136+
BASE_URL=https://api.example.com
137+
KEYCLOAK_REALM=master
138+
KEYCLOAK_CLIENT_ID=api
139+
KEYCLOAK_CLIENT_SECRET=your_client_secret
140+
141+
# Required - Model Configuration
142+
EMBEDDING_MODEL_ENDPOINT=bge-base-en-v1.5
143+
INFERENCE_MODEL_ENDPOINT=Llama-3.1-8B-Instruct
144+
EMBEDDING_MODEL_NAME=bge-base-en-v1.5
145+
INFERENCE_MODEL_NAME=meta-llama/Llama-3.1-8B-Instruct
146+
```
147+
148+
**Note**: The docker-compose.yml file automatically loads environment variables from `./api/.env` for the backend service.
149+
150+
### Running the Application
151+
152+
Start both API and UI services together with Docker Compose:
153+
154+
```bash
155+
# From the rag-chatbot directory
156+
docker compose up --build
157+
158+
# Or run in detached mode (background)
159+
docker compose up -d --build
160+
```
161+
162+
The API will be available at: `http://localhost:5001`
163+
The UI will be available at: `http://localhost:3000`
164+
165+
**View logs**:
166+
167+
```bash
168+
# All services
169+
docker compose logs -f
170+
171+
# Backend only
172+
docker compose logs -f backend
173+
174+
# Frontend only
175+
docker compose logs -f frontend
176+
```
177+
178+
**Verify the services are running**:
179+
180+
```bash
181+
# Check API health
182+
curl http://localhost:5001/health
183+
184+
# Check if containers are running
185+
docker compose ps
186+
```
187+
188+
## User Interface
189+
190+
**Using the Application**
191+
192+
Make sure you are at the localhost:3000 url
193+
194+
You will be directed to the main page which has each feature
195+
196+
![User Interface](images/ui.png)
197+
198+
Upload a PDF:
199+
200+
- Drag and drop a PDF file, or
201+
- Click "Browse Files" to select a file
202+
- Wait for processing to complete
203+
204+
Start chatting:
205+
206+
- Type your question in the input field
207+
- Press Enter or click Send
208+
- Get AI-powered answers based on your document
209+
210+
**UI Configuration**
211+
212+
When running with Docker Compose, the UI automatically connects to the backend API. The frontend is available at `http://localhost:3000` and the API at `http://localhost:5001`.
213+
214+
For production deployments, you may want to configure a reverse proxy or update the API URL in the frontend configuration.
215+
216+
### Stopping the Application
217+
218+
219+
```bash
220+
docker compose down
221+
```
222+
223+
## Troubleshooting
224+
225+
For comprehensive troubleshooting guidance, common issues, and solutions, refer to:
226+
227+
[Troubleshooting Guide - TROUBLESHOOTING.md](./TROUBLESHOOTING.md)

‎RAGChatbot/TROUBLESHOOTING.md‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
# Troubleshooting Guide
2+
3+
This document contains all common issues encountered during development and their solutions.
4+
5+
## Table of Contents
6+
7+
- [API Common Issues](#api-common-issues)
8+
- [UI Common Issues](#ui-common-issues)
9+
10+
### API Common Issues
11+
12+
#### "OPENAI_API_KEY not found in environment variables"
13+
14+
**Solution**:
15+
16+
1. Create a `.env` file in the `api` directory
17+
2. Add your OpenAI API key: `OPENAI_API_KEY=your_key_here`
18+
3. Restart the server
19+
20+
#### "No documents uploaded"
21+
22+
**Solution**:
23+
24+
- Upload a PDF first using the `/upload-pdf` endpoint
25+
- Check server logs for any upload errors
26+
- Verify the PDF is not corrupted or empty
27+
28+
#### "Could not load vector store"
29+
30+
**Solution**:
31+
32+
- The vector store is created when you upload your first PDF
33+
- Check that the application has write permissions in the directory
34+
- Verify `dmv_index/` directory exists and is accessible
35+
36+
#### Import errors
37+
38+
**Solution**:
39+
40+
1. Ensure all dependencies are installed: `pip install -r requirements.txt`
41+
2. Verify you're using Python 3.10 or higher: `python --version`
42+
3. Activate your virtual environment if using one
43+
44+
#### Server won't start
45+
46+
**Solution**:
47+
48+
1. Check if port 5000 is already in use: `lsof -i :5000` (Unix) or `netstat -ano | findstr :5000` (Windows)
49+
2. Use a different port: `uvicorn server:app --port 5001`
50+
3. Check the logs for specific error messages
51+
52+
#### PDF upload fails
53+
54+
**Solution**:
55+
56+
1. Verify the file is a valid PDF
57+
2. Check file size (must be under 50MB by default)
58+
3. Ensure the PDF contains extractable text (not just images)
59+
4. Check server logs for detailed error messages
60+
61+
#### Query returns no answer
62+
63+
**Solution**:
64+
65+
1. Verify a document has been uploaded successfully
66+
2. Try rephrasing your question
67+
3. Check if the document contains relevant information
68+
4. Increase `TOP_K_DOCUMENTS` in `config.py` for broader search
69+
70+
## UI Common Issues
71+
72+
### API Connection Issues
73+
74+
**Problem**: "Failed to upload PDF" or "Failed to get response"
75+
76+
**Solution**:
77+
78+
1. Ensure the API server is running on `http://localhost:5000`
79+
2. Check browser console for detailed errors
80+
3. Verify CORS is enabled in the API
81+
82+
### Build Issues
83+
84+
**Problem**: Build fails with dependency errors
85+
86+
**Solution**:
87+
88+
```bash
89+
# Clear node_modules and reinstall
90+
rm -rf node_modules package-lock.json
91+
npm install
92+
```
93+
94+
### Styling Issues
95+
96+
**Problem**: Styles not applying
97+
98+
**Solution**:
99+
100+
```bash
101+
# Rebuild Tailwind CSS
102+
npm run dev
103+
```

‎RAGChatbot/api/Dockerfile‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
FROM python:3.9-slim
2+
3+
# Set the working directory in the container
4+
WORKDIR /app
5+
6+
COPY requirements.txt .
7+
8+
9+
# Install Python dependencies
10+
RUN pip install --no-cache-dir -r requirements.txt
11+
12+
# Copy the rest of the application files into the container
13+
COPY server.py .
14+
15+
# Expose the port the service runs on
16+
EXPOSE 5001
17+
18+
# Command to run the application
19+
CMD ["uvicorn", "server:app", "--host", "0.0.0.0", "--port", "5001", "--reload"]

0 commit comments

Comments
 (0)