rag-backend-api / README.md
seraj-b2
runtime err fix
03c219f
|
Raw History Blame Contribute Delete
7.76 kB
metadata
title: rag-pipeline
sdk: docker
emoji: 🏃
colorFrom: purple
colorTo: indigo

RAG Backend Pipeline API

This repository contains a high-performance, lightweight Retrieval-Augmented Generation (RAG) backend service built using FastAPI, SentenceTransformers (all-MiniLM-L6-v2), and Qdrant Vector Database.

It is fully optimized to be deployed to Hugging Face Spaces via the Docker SDK. It is designed to work seamlessly with a separate frontend client (such as a ReactJS application) by implementing CORS.


Architecture Overview

  1. Document Ingestion: Accepts raw text documents, splits them into semantic chunks using langchain-text-splitters, computes vector embeddings locally using SentenceTransformers, and stores them in Qdrant.
  2. Context Retrieval: Accepts user queries, computes query embeddings, conducts a cosine-similarity search against Qdrant, and returns the top matching text chunks as a flat array of strings to be injected as LLM context.
  3. Storage Flexibility: Connects to Qdrant Cloud (for persistent production databases) and automatically falls back to an In-Memory Qdrant instance for rapid local testing without credentials.

API Endpoints Reference

1. Ingest Documents

  • Route: POST /documents
  • Content-Type: application/json
  • Description: Splits, embeds, and stores documents.
  • Request Body:
{
  "documents": [
    {
      "text": "Retrieval-Augmented Generation (RAG) is an AI framework for retrieving facts from an external knowledge base.",
      "metadata": {
        "source": "wikipedia",
        "topic": "RAG"
      }
    }
  ],
  "chunk_size": 500,
  "chunk_overlap": 50
}
  • Response:
{
  "status": "success",
  "message": "Successfully indexed 1 documents into 1 chunks.",
  "documents_processed": 1,
  "chunks_created": 1
}
  • Response:
{
  "status": "success",
  "message": "Successfully indexed 1 documents into 1 chunks.",
  "documents_processed": 1,
  "chunks_created": 1
}

1b. Upload Document File

  • Route: POST /documents/upload
  • Content-Type: multipart/form-data
  • Description: Accepts an uploaded file (.pdf or .txt), automatically extracts text, chunks, embeds, and stores it in Qdrant.
  • Form Fields:
    • file: The document file to upload (PDF or TXT).
    • chunk_size (Optional): Maximum character length of each chunk (Default: 500, Range: 50-5000).
    • chunk_overlap (Optional): Character overlap between adjacent chunks (Default: 50, Range: 0-1000).
    • metadata (Optional): A JSON-formatted string representing custom key-value metadata to attach to the ingested chunks (e.g. {"category": "physics"}).
  • Example curl command:
curl -X POST "http://localhost:7860/documents/upload" \
  -F "file=@/path/to/document.pdf" \
  -F "chunk_size=500" \
  -F "chunk_overlap=50" \
  -F "metadata={\"category\": \"research\", \"author\": \"John Doe\"}"
  • Response:
{
  "status": "success",
  "message": "Successfully indexed document 'document.pdf' into 4 chunks.",
  "documents_processed": 1,
  "chunks_created": 4
}

2. Retrieve Context

  • Route: POST /retrieve
  • Content-Type: application/json
  • Description: Performs a vector search and returns matching contexts.
  • Request Body:
{
  "query": "What is RAG?",
  "top_k": 3
}
  • Response:
{
  "query": "What is RAG?",
  "results": [
    {
      "text": "Retrieval-Augmented Generation (RAG) is an AI framework for retrieving facts from an external knowledge base.",
      "score": 0.892,
      "metadata": {
        "source": "wikipedia",
        "topic": "RAG",
        "doc_index": 0
      }
    }
  ],
  "context": [
    "Retrieval-Augmented Generation (RAG) is an AI framework for retrieving facts from an external knowledge base."
  ]
}

2b. Agentic Chat

  • Route: POST /agent/chat
  • Content-Type: application/json
  • Description: Runs a tool-calling reasoning loop using the Gemini API. If the agent needs details from the vector database to answer the user prompt, it dynamically calls the query_knowledge_base search tool.
  • Request Body:
{
  "prompt": "What is antigravity based on our database?",
  "chat_history": [
    {
      "role": "user",
      "content": "Hi there"
    },
    {
      "role": "model",
      "content": "Hello! How can I help you today?"
    }
  ]
}
  • Response:
{
  "answer": "Based on the database, antigravity is a concept of creating a place or object that is free from the force of gravity...",
  "tool_calls": [
    {
      "query": "antigravity",
      "top_k": 3,
      "results_count": 1,
      "results": [
        {
          "text": "Antigravity is a concept of creating a place or object that is free from the force of gravity...",
          "score": 0.892,
          "metadata": {
            "source": "physics_101",
            "category": "gravity"
          }
        }
      ]
    }
  ],
  "sources": [
    {
      "text": "Antigravity is a concept of creating a place or object that is free from the force of gravity...",
      "score": 0.892,
      "metadata": {
        "source": "physics_101",
        "category": "gravity"
      }
    }
  ]
}

3. Database Status

  • Route: GET /documents
  • Description: Gets collection metrics and database connection status.
  • Response:
{
  "connection_type": "Cloud",
  "collection_name": "rag_documents",
  "vector_size": 384,
  "vectors_count": 1,
  "status": "green"
}

4. Reset Vector Store

  • Route: DELETE /documents
  • Description: Clears all records from the vector store.
  • Response:
{
  "status": "success",
  "message": "Vector database has been reset successfully."
}

5. Health Check

  • Route: GET /health
  • Description: Returns overall API and vector store health status.

Local Setup & Development

1. Install Dependencies

Make sure you have Python 3.9+ installed. Run:

pip install -r requirements.txt

2. Run the Server

To run locally in development mode:

uvicorn main:app --reload --port 7860

Open http://localhost:7860/docs in your browser to test endpoints interactively using the Swagger UI.


Deployment to Hugging Face Spaces

This backend is ready to run as a Docker Space on Hugging Face.

Step 1: Create a Hugging Face Space

  1. Visit Hugging Face Spaces.
  2. Enter your Space name (e.g., rag-backend-api).
  3. Under SDK, select Docker.
  4. Choose the Blank template.
  5. Set Space visibility (Public or Private) and click Create Space.

Step 2: Configure Environment Variables / Secrets

Go to your Space's Settings tab, scroll to the Variables and Secrets section, and add your credentials as secrets:

  • GEMINI_API_KEY (Required for the Agentic RAG chat feature)
  • QDRANT_URL (e.g., https://xxxxxx-xxxx.eu-west3-1.gcp.qdrant.tech:443 or just https://xxxxxx-xxxx.eu-west3-1.gcp.qdrant.tech)
  • QDRANT_API_KEY (Your Qdrant API Key)
  • QDRANT_COLLECTION (Optional: The collection name to use, defaults to rag_documents)

Step 3: Push Your Code

Clone the HF Space repository and push this project's code:

git init
git remote add origin https://huggingface.co/spaces/<your-username>/<your-space-name>
git add .
git commit -m "Deploy RAG Backend API"
git push -u origin main

Hugging Face will automatically build the Docker image (pre-caching the model weights) and launch the FastAPI server on port 7860. The API docs will be available at https://<your-username>-<your-space-name>.hf.space/docs.