rag-backend-api / README.md
seraj-b2
runtime err fix
03c219f
|
Raw History Blame Contribute Delete
7.76 kB
---
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**:
```json
{
"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**:
```json
{
"status": "success",
"message": "Successfully indexed 1 documents into 1 chunks.",
"documents_processed": 1,
"chunks_created": 1
}
```
* **Response**:
```json
{
"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**:
```bash
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**:
```json
{
"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**:
```json
{
"query": "What is RAG?",
"top_k": 3
}
```
* **Response**:
```json
{
"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**:
```json
{
"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**:
```json
{
"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**:
```json
{
"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**:
```json
{
"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:
```bash
pip install -r requirements.txt
```
### 2. Run the Server
To run locally in development mode:
```bash
uvicorn main:app --reload --port 7860
```
Open [http://localhost:7860/docs](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](https://huggingface.co/new-space).
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:
```bash
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`.