Spaces:
Runtime error
Download README.md from its-seraj/rag-backend-api: direct link, hf CLI and curl.
- Browser
- Download file 7.76 kB
-
https://huggingface.co/spaces/its-seraj/rag-backend-api/resolve/main/README.md
- Command line
-
hf download hf://spaces/its-seraj/rag-backend-api/README.md
-
curl -L -o README.md https://huggingface.co/spaces/its-seraj/rag-backend-api/resolve/main/README.md
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
- 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. - 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.
- 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 (
.pdfor.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_basesearch 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
- Visit Hugging Face Spaces.
- Enter your Space name (e.g.,
rag-backend-api). - Under SDK, select Docker.
- Choose the Blank template.
- 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:443or justhttps://xxxxxx-xxxx.eu-west3-1.gcp.qdrant.tech)QDRANT_API_KEY(Your Qdrant API Key)QDRANT_COLLECTION(Optional: The collection name to use, defaults torag_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.