Spaces:
Runtime error
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
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`. |