| # 🧪 VDoc-RAG Testing Guide |
|
|
| A step-by-step guide to test the VDoc-RAG document Q&A application. |
|
|
| --- |
|
|
| ## 📋 Table of Contents |
|
|
| 1. [Access the Application](#1-access-the-application) |
| 2. [Upload a Document](#2-upload-a-document) |
| 3. [Ask Questions](#3-ask-questions) |
| 4. [Review the Response](#4-review-the-response) |
| 5. [Provide Feedback](#5-provide-feedback) |
| 6. [Additional Features](#6-additional-features) |
| 7. [Troubleshooting](#7-troubleshooting) |
|
|
| --- |
|
|
| ## 1. Access the Application |
|
|
| ### Online (HuggingFace Spaces) |
| Open the live demo: **https://huggingface.co/spaces/adi9128/vdoc_rag** |
| |
| ### Local Development |
| ```bash |
| # Start the server |
| uvicorn app.main:app --host 127.0.0.1 --port 8000 |
| |
| # Open in browser |
| http://127.0.0.1:8000 |
| ``` |
| |
| --- |
| |
| ## 2. Upload a Document |
| |
| ### Step 2.1: Select a File |
| - Click the **"Choose File"** button |
| - Select a PDF file from your computer |
| - Supported formats: `.pdf`, `.png`, `.jpg`, `.jpeg` |
| |
| ### Step 2.2: Upload & Index |
| - Click **"Upload & Index"** button |
| - Wait for processing (usually 5-15 seconds) |
| - You'll see: `✅ Uploaded and indexed [filename] (X chunks)` |
| |
| ### Step 2.3: Confirmation |
| - A green box will appear: **"📎 Ready to query: [filename]"** |
| - The document is now indexed and ready for questions |
| |
| --- |
| |
| ## 3. Ask Questions |
| |
| ### Step 3.1: Enter Your Question |
| - Type your question in the text box |
| - Example questions: |
| - "What is the user's name?" |
| - "What skills are mentioned?" |
| - "Summarize this document" |
| - "What is the contact email?" |
| - "List the work experience" |
| |
| ### Step 3.2: Submit |
| - Click **"Ask Question"** button |
| - Wait for the AI to process (2-5 seconds) |
| |
| --- |
| |
| ## 4. Review the Response |
| |
| ### The Answer Section Shows: |
| |
| | Component | Description | |
| |-----------|-------------| |
| | **💡 Answer** | AI-generated response based on your document | |
| | **📚 Sources** | Which pages/sections were used | |
| | **🔍 Retrieved Chunks** | Raw text segments found in the document | |
| | **Confidence %** | How relevant each chunk is to your question | |
| |
| ### Example Response: |
| ``` |
| 💡 Answer: |
| The user's name is Aditya, as mentioned in the resume header. |
| |
| 📚 Sources: |
| - Page 1 → Name: Aditya, Email: aditya@example.com... |
| |
| 🔍 Retrieved Chunks: |
| [1] Name: Aditya | Confidence: 95.2% |
| [2] Contact: aditya@example.com | Confidence: 87.1% |
| ``` |
| |
| --- |
| |
| ## 5. Provide Feedback |
| |
| After receiving an answer, you can help improve the system: |
| |
| | Button | When to Use | |
| |--------|-------------| |
| | **✅ Correct** | The answer is accurate and helpful | |
| | **❌ Incorrect** | The answer is wrong or irrelevant | |
| |
| Your feedback helps improve future responses! |
| |
| --- |
| |
| ## 6. Additional Features |
| |
| ### Clear Cache |
| - Click **"🧹 Clear Cache"** to remove cached responses |
| - Use when you want fresh answers |
| |
| ### Clear Persistent Index |
| - Click **"🗑️ Clear Persistent Index"** to remove all indexed documents |
| - Use to start completely fresh |
| |
| ### Dashboards |
| |
| | Dashboard | URL | Purpose | |
| |-----------|-----|---------| |
| | Feedback | `/feedback_dashboard` | View feedback statistics | |
| | Benchmark | `/benchmark_dashboard` | Evaluate embedding models | |
| |
| --- |
| |
| ## 7. Troubleshooting |
| |
| ### "No document found. Please upload a document first." |
| - **Cause**: No document is currently indexed |
| - **Solution**: Upload a PDF file first |
| |
| ### "Internal Server Error" after uploading |
| - **Cause**: Server state issue |
| - **Solution**: Refresh the page and try uploading again |
| |
| ### Document shows from another user |
| - **Note**: This is a shared demo instance |
| - **Solution**: Upload your own document - it will replace the previous one |
| |
| ### Slow response times |
| - **Cause**: First load downloads ML models (~500MB) |
| - **Solution**: Wait for initial setup, subsequent queries are faster |
| |
| ### OCR not extracting text properly |
| - **Cause**: Low quality PDF or scanned image |
| - **Solution**: Use higher resolution PDFs or clear text documents |
| |
| --- |
| |
| ## 📝 Test Scenarios |
| |
| ### Scenario 1: Resume Testing |
| 1. Upload a resume PDF |
| 2. Ask: "What is the candidate's name?" |
| 3. Ask: "What are their skills?" |
| 4. Ask: "List their work experience" |
| |
| ### Scenario 2: Report Testing |
| 1. Upload a business report PDF |
| 2. Ask: "What is the main topic?" |
| 3. Ask: "Summarize the key findings" |
| 4. Ask: "What recommendations are made?" |
| |
| ### Scenario 3: Invoice Testing |
| 1. Upload an invoice PDF |
| 2. Ask: "What is the total amount?" |
| 3. Ask: "What items are listed?" |
| 4. Ask: "What is the due date?" |
| |
| --- |
| |
| ## ✅ Success Criteria |
| |
| The application is working correctly if: |
| - [x] Document uploads successfully with chunk count |
| - [x] Questions return relevant answers |
| - [x] Confidence scores are displayed |
| - [x] Source attribution shows page numbers |
| - [x] Feedback buttons work |
| - [x] New uploads replace old documents |
| |
| --- |
| |
| ## 🆘 Getting Help |
| |
| If you encounter issues: |
| 1. Check the browser console for errors (F12) |
| 2. Try refreshing the page |
| 3. Upload a different PDF to test |
| 4. Clear the index and try again |
| |
| --- |
| |
| **Made with ❤️ by Aditya** |
| |
