Usage

This guide will help you get started with Easy RAG and show you how to use its features.

Quick Start

Start the services:
```
docker compose up -d
```

Upload a document:

curl -X POST "http://localhost:8000/api/v1/upload" \
     -H "accept: application/json" \
     -H "Content-Type: multipart/form-data" \
     -F "file=@your-document.pdf"

Query the documents:

curl -X POST "http://localhost:8000/api/v1/ask" \
     -H "accept: application/json" \
     -H "Content-Type: application/json" \
     -d '{"query": "What is an Amazon EC2 instance?"}'

Uploading Documents

Supported Formats

PDF files (recommended: uses PyMuPDF for better structure preservation)
Text files (.txt)

Large Document Support

Easy RAG can handle large documents efficiently:

Batch Processing: Documents are processed in batches to avoid memory issues
3500+ Pages: Successfully tested with PDFs containing 3500+ pages
Automatic Chunking: Documents are automatically split into optimal chunks
Progress Logging: Monitor processing progress through logs

Example: Upload a PDF

Using curl:

curl -X POST "http://localhost:8000/api/v1/upload" \
     -F "file=@aws-ec2-guide.pdf"

Response:

{
  "status": "ok",
  "chunks_indexed": 1250
}

Using Python:

import requests

url = "http://localhost:8000/api/v1/upload"
files = {"file": open("aws-ec2-guide.pdf", "rb")}
response = requests.post(url, files=files)
print(response.json())

Using JavaScript/Node.js:

const FormData = require('form-data');
const fs = require('fs');
const axios = require('axios');

const form = new FormData();
form.append('file', fs.createReadStream('aws-ec2-guide.pdf'));

axios.post('http://localhost:8000/api/v1/upload', form, {
  headers: form.getHeaders()
})
.then(response => console.log(response.data))
.catch(error => console.error(error));

Querying Documents

Basic Query

Query your documents using natural language:

curl -X POST "http://localhost:8000/api/v1/ask" \
     -H "Content-Type: application/json" \
     -d '{"query": "What is an Amazon EC2 instance?"}'

Response:

{
  "query": "What is an Amazon EC2 instance?",
  "results": [
    {
      "source": "aws-ec2-guide.pdf",
      "text": "An Amazon EC2 instance is a virtual server...",
      "score": 0.8358426094055176,
      "page": 320
    },
    ...
  ]
}

Understanding Results

Each result includes:

source: Original filename of the document
text: The relevant text chunk
score: Relevance score (higher = more relevant, typically 0.7-0.9 for good matches)
page: Page number in the source document (if available)

Results are sorted by relevance score (highest first).

Python Example

import requests

url = "http://localhost:8000/api/v1/ask"
payload = {"query": "What are the different EC2 instance types?"}
response = requests.post(url, json=payload)

results = response.json()["results"]
for result in results:
    print(f"Score: {result['score']:.3f}")
    print(f"Page: {result.get('page', 'N/A')}")
    print(f"Text: {result['text'][:200]}...")
    print("-" * 50)

JavaScript Example

const axios = require('axios');

axios.post('http://localhost:8000/api/v1/ask', {
  query: 'What are the different EC2 instance types?'
})
.then(response => {
  response.data.results.forEach(result => {
    console.log(`Score: ${result.score.toFixed(3)}`);
    console.log(`Page: ${result.page || 'N/A'}`);
    console.log(`Text: ${result.text.substring(0, 200)}...`);
    console.log('-'.repeat(50));
  });
});

Best Practices

Query Optimization

Be specific: More specific queries yield better results
Use keywords: Include relevant technical terms
Ask complete questions: Full questions work better than single words

Document Preparation

Use structured PDFs: Well-formatted PDFs produce better results
Avoid scanned PDFs: Text-based PDFs work better than scanned images
Multiple documents: Upload multiple related documents for comprehensive search

Performance Tips

Batch size: Adjust BATCH_SIZE for your system’s memory
Chunk size: Larger chunks (800-1000) preserve more context
Result limit: Use appropriate default_k based on your needs

API Documentation

Interactive API documentation is available at:

Swagger UI: http://localhost:8000/docs
ReDoc: http://localhost:8000/redoc

Health Check

Check if the API is running:

curl http://localhost:8000/health

Response:

{
  "status": "healthy",
  "qdrant_connected": true,
  "documents_count": 1250
}