Spaces:
Runtime error
Runtime error
seraj-b2 commited on
Commit ·
73ddeba
0
Parent(s):
init
Browse files- Dockerfile +37 -0
- README.md +154 -0
- __pycache__/main.cpython-314.pyc +0 -0
- __pycache__/test_api.cpython-314-pytest-9.0.3.pyc +0 -0
- __pycache__/vector_store.cpython-314.pyc +0 -0
- main.py +222 -0
- requirements.txt +11 -0
- test_api.py +108 -0
- vector_store.py +142 -0
Dockerfile
ADDED
|
@@ -0,0 +1,37 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# Use an official lightweight Python base image
|
| 2 |
+
FROM python:3.9-slim
|
| 3 |
+
|
| 4 |
+
# Set system environment variables
|
| 5 |
+
ENV PYTHONUNBUFFERED=1 \
|
| 6 |
+
PYTHONDONTWRITEBYTECODE=1 \
|
| 7 |
+
HF_HOME=/code/model_cache \
|
| 8 |
+
PORT=7860
|
| 9 |
+
|
| 10 |
+
# Set working directory
|
| 11 |
+
WORKDIR /code
|
| 12 |
+
|
| 13 |
+
# Copy dependencies first to leverage Docker layer caching
|
| 14 |
+
COPY ./requirements.txt /code/requirements.txt
|
| 15 |
+
|
| 16 |
+
# Install python dependencies
|
| 17 |
+
RUN pip install --no-cache-dir --upgrade -r /code/requirements.txt
|
| 18 |
+
|
| 19 |
+
# Create cache folder and make it accessible
|
| 20 |
+
RUN mkdir -p /code/model_cache && chmod -R 777 /code/model_cache
|
| 21 |
+
|
| 22 |
+
# Pre-download the embedding model at build time to prevent cold-start latency
|
| 23 |
+
RUN python -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('all-MiniLM-L6-v2')"
|
| 24 |
+
|
| 25 |
+
# Set up a non-root user (Hugging Face Spaces requirement)
|
| 26 |
+
RUN useradd -m -u 1000 user
|
| 27 |
+
USER user
|
| 28 |
+
|
| 29 |
+
# Set home directory for user
|
| 30 |
+
ENV HOME=/home/user \
|
| 31 |
+
PATH=/home/user/.local/bin:$PATH
|
| 32 |
+
|
| 33 |
+
# Copy application files, changing ownership to the non-root user
|
| 34 |
+
COPY --chown=user:user . /code
|
| 35 |
+
|
| 36 |
+
# Run the FastAPI server on port 7860 (Hugging Face Spaces default port)
|
| 37 |
+
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "7860"]
|
README.md
ADDED
|
@@ -0,0 +1,154 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# RAG Backend Pipeline API
|
| 2 |
+
|
| 3 |
+
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**.
|
| 4 |
+
|
| 5 |
+
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.
|
| 6 |
+
|
| 7 |
+
---
|
| 8 |
+
|
| 9 |
+
## Architecture Overview
|
| 10 |
+
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.
|
| 11 |
+
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.
|
| 12 |
+
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.
|
| 13 |
+
|
| 14 |
+
---
|
| 15 |
+
|
| 16 |
+
## API Endpoints Reference
|
| 17 |
+
|
| 18 |
+
### 1. Ingest Documents
|
| 19 |
+
* **Route**: `POST /documents`
|
| 20 |
+
* **Content-Type**: `application/json`
|
| 21 |
+
* **Description**: Splits, embeds, and stores documents.
|
| 22 |
+
* **Request Body**:
|
| 23 |
+
```json
|
| 24 |
+
{
|
| 25 |
+
"documents": [
|
| 26 |
+
{
|
| 27 |
+
"text": "Retrieval-Augmented Generation (RAG) is an AI framework for retrieving facts from an external knowledge base.",
|
| 28 |
+
"metadata": {
|
| 29 |
+
"source": "wikipedia",
|
| 30 |
+
"topic": "RAG"
|
| 31 |
+
}
|
| 32 |
+
}
|
| 33 |
+
],
|
| 34 |
+
"chunk_size": 500,
|
| 35 |
+
"chunk_overlap": 50
|
| 36 |
+
}
|
| 37 |
+
```
|
| 38 |
+
* **Response**:
|
| 39 |
+
```json
|
| 40 |
+
{
|
| 41 |
+
"status": "success",
|
| 42 |
+
"message": "Successfully indexed 1 documents into 1 chunks.",
|
| 43 |
+
"documents_processed": 1,
|
| 44 |
+
"chunks_created": 1
|
| 45 |
+
}
|
| 46 |
+
```
|
| 47 |
+
|
| 48 |
+
### 2. Retrieve Context
|
| 49 |
+
* **Route**: `POST /retrieve`
|
| 50 |
+
* **Content-Type**: `application/json`
|
| 51 |
+
* **Description**: Performs a vector search and returns matching contexts.
|
| 52 |
+
* **Request Body**:
|
| 53 |
+
```json
|
| 54 |
+
{
|
| 55 |
+
"query": "What is RAG?",
|
| 56 |
+
"top_k": 3
|
| 57 |
+
}
|
| 58 |
+
```
|
| 59 |
+
* **Response**:
|
| 60 |
+
```json
|
| 61 |
+
{
|
| 62 |
+
"query": "What is RAG?",
|
| 63 |
+
"results": [
|
| 64 |
+
{
|
| 65 |
+
"text": "Retrieval-Augmented Generation (RAG) is an AI framework for retrieving facts from an external knowledge base.",
|
| 66 |
+
"score": 0.892,
|
| 67 |
+
"metadata": {
|
| 68 |
+
"source": "wikipedia",
|
| 69 |
+
"topic": "RAG",
|
| 70 |
+
"doc_index": 0
|
| 71 |
+
}
|
| 72 |
+
}
|
| 73 |
+
],
|
| 74 |
+
"context": [
|
| 75 |
+
"Retrieval-Augmented Generation (RAG) is an AI framework for retrieving facts from an external knowledge base."
|
| 76 |
+
]
|
| 77 |
+
}
|
| 78 |
+
```
|
| 79 |
+
|
| 80 |
+
### 3. Database Status
|
| 81 |
+
* **Route**: `GET /documents`
|
| 82 |
+
* **Description**: Gets collection metrics and database connection status.
|
| 83 |
+
* **Response**:
|
| 84 |
+
```json
|
| 85 |
+
{
|
| 86 |
+
"connection_type": "Cloud",
|
| 87 |
+
"collection_name": "rag_documents",
|
| 88 |
+
"vector_size": 384,
|
| 89 |
+
"vectors_count": 1,
|
| 90 |
+
"status": "green"
|
| 91 |
+
}
|
| 92 |
+
```
|
| 93 |
+
|
| 94 |
+
### 4. Reset Vector Store
|
| 95 |
+
* **Route**: `DELETE /documents`
|
| 96 |
+
* **Description**: Clears all records from the vector store.
|
| 97 |
+
* **Response**:
|
| 98 |
+
```json
|
| 99 |
+
{
|
| 100 |
+
"status": "success",
|
| 101 |
+
"message": "Vector database has been reset successfully."
|
| 102 |
+
}
|
| 103 |
+
```
|
| 104 |
+
|
| 105 |
+
### 5. Health Check
|
| 106 |
+
* **Route**: `GET /health`
|
| 107 |
+
* **Description**: Returns overall API and vector store health status.
|
| 108 |
+
|
| 109 |
+
---
|
| 110 |
+
|
| 111 |
+
## Local Setup & Development
|
| 112 |
+
|
| 113 |
+
### 1. Install Dependencies
|
| 114 |
+
Make sure you have Python 3.9+ installed. Run:
|
| 115 |
+
```bash
|
| 116 |
+
pip install -r requirements.txt
|
| 117 |
+
```
|
| 118 |
+
|
| 119 |
+
### 2. Run the Server
|
| 120 |
+
To run locally in development mode:
|
| 121 |
+
```bash
|
| 122 |
+
uvicorn main:app --reload --port 7860
|
| 123 |
+
```
|
| 124 |
+
Open [http://localhost:7860/docs](http://localhost:7860/docs) in your browser to test endpoints interactively using the Swagger UI.
|
| 125 |
+
|
| 126 |
+
---
|
| 127 |
+
|
| 128 |
+
## Deployment to Hugging Face Spaces
|
| 129 |
+
|
| 130 |
+
This backend is ready to run as a Docker Space on Hugging Face.
|
| 131 |
+
|
| 132 |
+
### Step 1: Create a Hugging Face Space
|
| 133 |
+
1. Visit [Hugging Face Spaces](https://huggingface.co/new-space).
|
| 134 |
+
2. Enter your Space name (e.g., `rag-backend-api`).
|
| 135 |
+
3. Under **SDK**, select **Docker**.
|
| 136 |
+
4. Choose the **Blank** template.
|
| 137 |
+
5. Set Space visibility (Public or Private) and click **Create Space**.
|
| 138 |
+
|
| 139 |
+
### Step 2: Configure Environment Variables / Secrets
|
| 140 |
+
Go to your Space's **Settings** tab, scroll to the **Variables and Secrets** section, and add your Qdrant credentials as secrets:
|
| 141 |
+
* `QDRANT_URL` (e.g., `https://xxxxxx-xxxx.eu-west3-1.gcp.qdrant.tech:6333`)
|
| 142 |
+
* `QDRANT_API_KEY` (Your Qdrant API Key)
|
| 143 |
+
* `QDRANT_COLLECTION` (Optional: The collection name to use, defaults to `rag_documents`)
|
| 144 |
+
|
| 145 |
+
### Step 3: Push Your Code
|
| 146 |
+
Clone the HF Space repository and push this project's code:
|
| 147 |
+
```bash
|
| 148 |
+
git init
|
| 149 |
+
git remote add origin https://huggingface.co/spaces/<your-username>/<your-space-name>
|
| 150 |
+
git add .
|
| 151 |
+
git commit -m "Deploy RAG Backend API"
|
| 152 |
+
git push -u origin main
|
| 153 |
+
```
|
| 154 |
+
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`.
|
__pycache__/main.cpython-314.pyc
ADDED
|
Binary file (12 kB). View file
|
|
|
__pycache__/test_api.cpython-314-pytest-9.0.3.pyc
ADDED
|
Binary file (16.6 kB). View file
|
|
|
__pycache__/vector_store.cpython-314.pyc
ADDED
|
Binary file (8.39 kB). View file
|
|
|
main.py
ADDED
|
@@ -0,0 +1,222 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
import logging
|
| 2 |
+
from typing import List, Optional
|
| 3 |
+
from fastapi import FastAPI, HTTPException, status
|
| 4 |
+
from fastapi.middleware.cors import CORSMiddleware
|
| 5 |
+
from pydantic import BaseModel, Field
|
| 6 |
+
from sentence_transformers import SentenceTransformer
|
| 7 |
+
from langchain_text_splitters import RecursiveCharacterTextSplitter
|
| 8 |
+
|
| 9 |
+
from vector_store import QdrantVectorStore
|
| 10 |
+
|
| 11 |
+
# Configure logging
|
| 12 |
+
logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s")
|
| 13 |
+
logger = logging.getLogger("rag_backend")
|
| 14 |
+
|
| 15 |
+
# Initialize FastAPI App
|
| 16 |
+
app = FastAPI(
|
| 17 |
+
title="RAG Backend API",
|
| 18 |
+
description="A highly performant RAG pipeline backend deployable to Hugging Face Spaces. It offers document ingestion (chunking, embedding) and vector retrieval.",
|
| 19 |
+
version="1.0.0",
|
| 20 |
+
docs_url="/docs",
|
| 21 |
+
redoc_url="/redoc"
|
| 22 |
+
)
|
| 23 |
+
|
| 24 |
+
# Enable CORS for ReactJS Frontend Integration
|
| 25 |
+
app.add_middleware(
|
| 26 |
+
CORSMiddleware,
|
| 27 |
+
allow_origins=["*"], # Allows all origins, ideal for external React UI. Customize if needed.
|
| 28 |
+
allow_credentials=True,
|
| 29 |
+
allow_methods=["*"],
|
| 30 |
+
allow_headers=["*"],
|
| 31 |
+
)
|
| 32 |
+
|
| 33 |
+
# Initialize Embedding Model and Vector Store
|
| 34 |
+
logger.info("Initializing SentenceTransformer model 'all-MiniLM-L6-v2'...")
|
| 35 |
+
embedding_model = SentenceTransformer("all-MiniLM-L6-v2")
|
| 36 |
+
logger.info("SentenceTransformer model initialized successfully.")
|
| 37 |
+
|
| 38 |
+
logger.info("Initializing Qdrant Vector Store...")
|
| 39 |
+
vector_store = QdrantVectorStore()
|
| 40 |
+
logger.info("Qdrant Vector Store initialized successfully.")
|
| 41 |
+
|
| 42 |
+
|
| 43 |
+
# Pydantic Schemas for Request/Response Validation
|
| 44 |
+
class DocumentInput(BaseModel):
|
| 45 |
+
text: str = Field(..., description="The main text content of the document to index.")
|
| 46 |
+
metadata: Optional[dict] = Field(default=None, description="Key-value pairs containing metadata (e.g. source, author, category).")
|
| 47 |
+
|
| 48 |
+
class IngestionRequest(BaseModel):
|
| 49 |
+
documents: List[DocumentInput] = Field(..., description="A list of documents to chunk, embed, and store.")
|
| 50 |
+
chunk_size: int = Field(default=500, ge=50, le=5000, description="The maximum size of each text chunk in characters.")
|
| 51 |
+
chunk_overlap: int = Field(default=50, ge=0, le=1000, description="The character overlap between adjacent chunks.")
|
| 52 |
+
|
| 53 |
+
class IngestionResponse(BaseModel):
|
| 54 |
+
status: str
|
| 55 |
+
message: str
|
| 56 |
+
documents_processed: int
|
| 57 |
+
chunks_created: int
|
| 58 |
+
|
| 59 |
+
class RetrievalRequest(BaseModel):
|
| 60 |
+
query: str = Field(..., description="The search query to match against stored documents.")
|
| 61 |
+
top_k: int = Field(default=3, ge=1, le=50, description="The maximum number of relevant chunks to retrieve.")
|
| 62 |
+
|
| 63 |
+
class RetrievalResult(BaseModel):
|
| 64 |
+
text: str
|
| 65 |
+
score: float
|
| 66 |
+
metadata: dict
|
| 67 |
+
|
| 68 |
+
class RetrievalResponse(BaseModel):
|
| 69 |
+
query: str
|
| 70 |
+
results: List[RetrievalResult]
|
| 71 |
+
context: List[str] # Array of strings to be used directly as LLM context
|
| 72 |
+
|
| 73 |
+
|
| 74 |
+
# API Endpoints
|
| 75 |
+
@app.get("/", status_code=status.HTTP_200_OK)
|
| 76 |
+
def root():
|
| 77 |
+
"""
|
| 78 |
+
Root endpoint serving basic API metadata.
|
| 79 |
+
"""
|
| 80 |
+
return {
|
| 81 |
+
"app": "RAG Backend Service",
|
| 82 |
+
"version": "1.0.0",
|
| 83 |
+
"documentation": "/docs",
|
| 84 |
+
"status": "online"
|
| 85 |
+
}
|
| 86 |
+
|
| 87 |
+
@app.get("/health", status_code=status.HTTP_200_OK)
|
| 88 |
+
def health():
|
| 89 |
+
"""
|
| 90 |
+
Health check endpoint returning system status.
|
| 91 |
+
"""
|
| 92 |
+
return {
|
| 93 |
+
"status": "healthy",
|
| 94 |
+
"vector_store": vector_store.get_status()
|
| 95 |
+
}
|
| 96 |
+
|
| 97 |
+
@app.post("/documents", response_model=IngestionResponse, status_code=status.HTTP_201_CREATED)
|
| 98 |
+
def ingest_documents(payload: IngestionRequest):
|
| 99 |
+
"""
|
| 100 |
+
Ingests, chunks, embeds, and stores documents in the vector database.
|
| 101 |
+
"""
|
| 102 |
+
if not payload.documents:
|
| 103 |
+
raise HTTPException(
|
| 104 |
+
status_code=status.HTTP_400_BAD_REQUEST,
|
| 105 |
+
detail="No documents were provided in the request."
|
| 106 |
+
)
|
| 107 |
+
|
| 108 |
+
# Initialize LangChain text splitter
|
| 109 |
+
text_splitter = RecursiveCharacterTextSplitter(
|
| 110 |
+
chunk_size=payload.chunk_size,
|
| 111 |
+
chunk_overlap=payload.chunk_overlap,
|
| 112 |
+
length_function=len
|
| 113 |
+
)
|
| 114 |
+
|
| 115 |
+
all_chunks: List[str] = []
|
| 116 |
+
all_metadatas: List[dict] = []
|
| 117 |
+
|
| 118 |
+
try:
|
| 119 |
+
# Split documents into chunks
|
| 120 |
+
for idx, doc in enumerate(payload.documents):
|
| 121 |
+
chunks = text_splitter.split_text(doc.text)
|
| 122 |
+
for chunk in chunks:
|
| 123 |
+
all_chunks.append(chunk)
|
| 124 |
+
# Propagate original document metadata, default to empty dict
|
| 125 |
+
meta = doc.metadata.copy() if doc.metadata else {}
|
| 126 |
+
meta["doc_index"] = idx
|
| 127 |
+
all_metadatas.append(meta)
|
| 128 |
+
|
| 129 |
+
if not all_chunks:
|
| 130 |
+
return IngestionResponse(
|
| 131 |
+
status="success",
|
| 132 |
+
message="No chunks were created from the input documents.",
|
| 133 |
+
documents_processed=len(payload.documents),
|
| 134 |
+
chunks_created=0
|
| 135 |
+
)
|
| 136 |
+
|
| 137 |
+
logger.info(f"Generating embeddings for {len(all_chunks)} chunks...")
|
| 138 |
+
# Compute embeddings in batch
|
| 139 |
+
embeddings = embedding_model.encode(all_chunks, show_progress_bar=False).tolist()
|
| 140 |
+
|
| 141 |
+
logger.info("Upserting vectors into Qdrant...")
|
| 142 |
+
# Store in Qdrant
|
| 143 |
+
chunks_inserted = vector_store.add_documents(
|
| 144 |
+
texts=all_chunks,
|
| 145 |
+
embeddings=embeddings,
|
| 146 |
+
metadatas=all_metadatas
|
| 147 |
+
)
|
| 148 |
+
|
| 149 |
+
return IngestionResponse(
|
| 150 |
+
status="success",
|
| 151 |
+
message=f"Successfully indexed {len(payload.documents)} documents into {chunks_inserted} chunks.",
|
| 152 |
+
documents_processed=len(payload.documents),
|
| 153 |
+
chunks_created=chunks_inserted
|
| 154 |
+
)
|
| 155 |
+
|
| 156 |
+
except Exception as e:
|
| 157 |
+
logger.error(f"Error during document ingestion: {e}")
|
| 158 |
+
raise HTTPException(
|
| 159 |
+
status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
|
| 160 |
+
detail=f"An error occurred while indexing documents: {str(e)}"
|
| 161 |
+
)
|
| 162 |
+
|
| 163 |
+
@app.post("/retrieve", response_model=RetrievalResponse, status_code=status.HTTP_200_OK)
|
| 164 |
+
def retrieve_context(payload: RetrievalRequest):
|
| 165 |
+
"""
|
| 166 |
+
Retrieves the top_k most similar document chunks for a query.
|
| 167 |
+
Returns both structured results and a flat array of context strings.
|
| 168 |
+
"""
|
| 169 |
+
try:
|
| 170 |
+
logger.info(f"Generating embedding for query: '{payload.query}'")
|
| 171 |
+
# Embed query text
|
| 172 |
+
query_embedding = embedding_model.encode(payload.query, show_progress_bar=False).tolist()
|
| 173 |
+
|
| 174 |
+
logger.info(f"Searching for top {payload.top_k} matches...")
|
| 175 |
+
# Search vector database
|
| 176 |
+
search_results = vector_store.search(query_embedding, top_k=payload.top_k)
|
| 177 |
+
|
| 178 |
+
results = []
|
| 179 |
+
context = []
|
| 180 |
+
for res in search_results:
|
| 181 |
+
results.append(RetrievalResult(
|
| 182 |
+
text=res["text"],
|
| 183 |
+
score=res["score"],
|
| 184 |
+
metadata=res["metadata"]
|
| 185 |
+
))
|
| 186 |
+
context.append(res["text"])
|
| 187 |
+
|
| 188 |
+
return RetrievalResponse(
|
| 189 |
+
query=payload.query,
|
| 190 |
+
results=results,
|
| 191 |
+
context=context
|
| 192 |
+
)
|
| 193 |
+
|
| 194 |
+
except Exception as e:
|
| 195 |
+
logger.error(f"Error during retrieval: {e}")
|
| 196 |
+
raise HTTPException(
|
| 197 |
+
status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
|
| 198 |
+
detail=f"An error occurred during retrieval: {str(e)}"
|
| 199 |
+
)
|
| 200 |
+
|
| 201 |
+
@app.get("/documents", status_code=status.HTTP_200_OK)
|
| 202 |
+
def get_documents_status():
|
| 203 |
+
"""
|
| 204 |
+
Retrieves statistics and connection information about the vector database.
|
| 205 |
+
"""
|
| 206 |
+
return vector_store.get_status()
|
| 207 |
+
|
| 208 |
+
@app.delete("/documents", status_code=status.HTTP_200_OK)
|
| 209 |
+
def clear_documents():
|
| 210 |
+
"""
|
| 211 |
+
Resets/clears the vector database collection.
|
| 212 |
+
"""
|
| 213 |
+
success = vector_store.clear()
|
| 214 |
+
if not success:
|
| 215 |
+
raise HTTPException(
|
| 216 |
+
status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
|
| 217 |
+
detail="Failed to reset the vector database collection."
|
| 218 |
+
)
|
| 219 |
+
return {
|
| 220 |
+
"status": "success",
|
| 221 |
+
"message": "Vector database has been reset successfully."
|
| 222 |
+
}
|
requirements.txt
ADDED
|
@@ -0,0 +1,11 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
fastapi>=0.100.0
|
| 2 |
+
uvicorn>=0.22.0
|
| 3 |
+
pydantic>=2.0.0
|
| 4 |
+
sentence-transformers>=2.2.0
|
| 5 |
+
langchain-text-splitters>=0.0.1
|
| 6 |
+
qdrant-client>=1.6.0
|
| 7 |
+
numpy>=1.20.0
|
| 8 |
+
gunicorn>=20.1.0
|
| 9 |
+
httpx>=0.24.0
|
| 10 |
+
pytest>=7.0.0
|
| 11 |
+
|
test_api.py
ADDED
|
@@ -0,0 +1,108 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
import os
|
| 2 |
+
import pytest
|
| 3 |
+
from fastapi.testclient import TestClient
|
| 4 |
+
|
| 5 |
+
# Set environment variables for testing before importing main
|
| 6 |
+
os.environ["QDRANT_COLLECTION"] = "test_rag_documents"
|
| 7 |
+
# Ensure we run in memory during tests by clearing cloud credentials if any exist in env
|
| 8 |
+
if "QDRANT_URL" in os.environ:
|
| 9 |
+
del os.environ["QDRANT_URL"]
|
| 10 |
+
if "QDRANT_API_KEY" in os.environ:
|
| 11 |
+
del os.environ["QDRANT_API_KEY"]
|
| 12 |
+
|
| 13 |
+
from main import app
|
| 14 |
+
|
| 15 |
+
client = TestClient(app)
|
| 16 |
+
|
| 17 |
+
def test_root_endpoint():
|
| 18 |
+
response = client.get("/")
|
| 19 |
+
assert response.status_code == 200
|
| 20 |
+
data = response.json()
|
| 21 |
+
assert data["app"] == "RAG Backend Service"
|
| 22 |
+
assert data["status"] == "online"
|
| 23 |
+
|
| 24 |
+
def test_health_endpoint():
|
| 25 |
+
response = client.get("/health")
|
| 26 |
+
assert response.status_code == 200
|
| 27 |
+
data = response.json()
|
| 28 |
+
assert data["status"] == "healthy"
|
| 29 |
+
assert "vector_store" in data
|
| 30 |
+
assert data["vector_store"]["connection_type"] == "In-Memory (Local)"
|
| 31 |
+
|
| 32 |
+
def test_rag_pipeline_flow():
|
| 33 |
+
# 1. Clear database before starting
|
| 34 |
+
client.delete("/documents")
|
| 35 |
+
|
| 36 |
+
# Check stats are empty
|
| 37 |
+
status_response = client.get("/documents")
|
| 38 |
+
assert status_response.status_code == 200
|
| 39 |
+
assert status_response.json()["vectors_count"] == 0
|
| 40 |
+
|
| 41 |
+
# 2. Ingest documents
|
| 42 |
+
payload = {
|
| 43 |
+
"documents": [
|
| 44 |
+
{
|
| 45 |
+
"text": "Antigravity is a concept of creating a place or object that is free from the force of gravity. It does not refer to the lack of weight under gravity experienced in free fall.",
|
| 46 |
+
"metadata": {"source": "physics_101", "category": "gravity"}
|
| 47 |
+
},
|
| 48 |
+
{
|
| 49 |
+
"text": "Photosynthesis is the process used by plants, algae and certain bacteria to harness energy from sunlight and turn it into chemical energy.",
|
| 50 |
+
"metadata": {"source": "biology_101", "category": "plants"}
|
| 51 |
+
}
|
| 52 |
+
],
|
| 53 |
+
"chunk_size": 100,
|
| 54 |
+
"chunk_overlap": 10
|
| 55 |
+
}
|
| 56 |
+
|
| 57 |
+
ingest_response = client.post("/documents", json=payload)
|
| 58 |
+
assert ingest_response.status_code == 201
|
| 59 |
+
ingest_data = ingest_response.json()
|
| 60 |
+
assert ingest_data["status"] == "success"
|
| 61 |
+
assert ingest_data["documents_processed"] == 2
|
| 62 |
+
assert ingest_data["chunks_created"] > 0
|
| 63 |
+
|
| 64 |
+
# 3. Verify statistics updated
|
| 65 |
+
status_response = client.get("/documents")
|
| 66 |
+
assert status_response.json()["vectors_count"] == ingest_data["chunks_created"]
|
| 67 |
+
|
| 68 |
+
# 4. Search retrieval for gravity topic
|
| 69 |
+
retrieve_payload = {
|
| 70 |
+
"query": "How does antigravity work or what is it?",
|
| 71 |
+
"top_k": 2
|
| 72 |
+
}
|
| 73 |
+
retrieve_response = client.post("/retrieve", json=retrieve_payload)
|
| 74 |
+
assert retrieve_response.status_code == 200
|
| 75 |
+
retrieve_data = retrieve_response.json()
|
| 76 |
+
|
| 77 |
+
assert retrieve_data["query"] == retrieve_payload["query"]
|
| 78 |
+
assert len(retrieve_data["results"]) > 0
|
| 79 |
+
assert len(retrieve_data["context"]) > 0
|
| 80 |
+
|
| 81 |
+
# First result should match the antigravity text (higher similarity score)
|
| 82 |
+
assert "Antigravity" in retrieve_data["results"][0]["text"]
|
| 83 |
+
assert retrieve_data["results"][0]["metadata"]["category"] == "gravity"
|
| 84 |
+
|
| 85 |
+
# 5. Search retrieval for photosynthesis
|
| 86 |
+
retrieve_payload_bio = {
|
| 87 |
+
"query": "How do plants harness energy from sunlight?",
|
| 88 |
+
"top_k": 1
|
| 89 |
+
}
|
| 90 |
+
retrieve_response_bio = client.post("/retrieve", json=retrieve_payload_bio)
|
| 91 |
+
assert retrieve_response_bio.status_code == 200
|
| 92 |
+
retrieve_data_bio = retrieve_response_bio.json()
|
| 93 |
+
assert "Photosynthesis" in retrieve_data_bio["results"][0]["text"]
|
| 94 |
+
assert retrieve_data_bio["results"][0]["metadata"]["category"] == "plants"
|
| 95 |
+
|
| 96 |
+
# 6. Clear database
|
| 97 |
+
clear_response = client.delete("/documents")
|
| 98 |
+
assert clear_response.status_code == 200
|
| 99 |
+
assert clear_response.json()["status"] == "success"
|
| 100 |
+
|
| 101 |
+
# Check stats are empty again
|
| 102 |
+
status_response = client.get("/documents")
|
| 103 |
+
assert status_response.json()["vectors_count"] == 0
|
| 104 |
+
|
| 105 |
+
if __name__ == "__main__":
|
| 106 |
+
import sys
|
| 107 |
+
import pytest
|
| 108 |
+
sys.exit(pytest.main([__file__]))
|
vector_store.py
ADDED
|
@@ -0,0 +1,142 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
import os
|
| 2 |
+
import uuid
|
| 3 |
+
import logging
|
| 4 |
+
from typing import List, Dict, Any, Optional
|
| 5 |
+
from qdrant_client import QdrantClient
|
| 6 |
+
from qdrant_client.http import models
|
| 7 |
+
from qdrant_client.http.exceptions import UnexpectedResponse
|
| 8 |
+
|
| 9 |
+
logger = logging.getLogger("rag_backend")
|
| 10 |
+
|
| 11 |
+
class QdrantVectorStore:
|
| 12 |
+
def __init__(self):
|
| 13 |
+
self.url = os.getenv("QDRANT_URL")
|
| 14 |
+
self.api_key = os.getenv("QDRANT_API_KEY")
|
| 15 |
+
self.collection_name = os.getenv("QDRANT_COLLECTION", "rag_documents")
|
| 16 |
+
self.vector_size = 384 # Default dimension for all-MiniLM-L6-v2
|
| 17 |
+
|
| 18 |
+
# Connect to Qdrant Cloud if credentials are provided, otherwise fallback to in-memory
|
| 19 |
+
if self.url and self.api_key:
|
| 20 |
+
logger.info(f"Connecting to Qdrant Cloud at {self.url}...")
|
| 21 |
+
self.client = QdrantClient(
|
| 22 |
+
url=self.url,
|
| 23 |
+
api_key=self.api_key
|
| 24 |
+
)
|
| 25 |
+
self.is_cloud = True
|
| 26 |
+
else:
|
| 27 |
+
logger.warning("QDRANT_URL and QDRANT_API_KEY not found in environment variables. Falling back to local In-Memory Qdrant...")
|
| 28 |
+
self.client = QdrantClient(location=":memory:")
|
| 29 |
+
self.is_cloud = False
|
| 30 |
+
|
| 31 |
+
self._ensure_collection()
|
| 32 |
+
|
| 33 |
+
def _ensure_collection(self):
|
| 34 |
+
"""Ensures that the target collection exists in Qdrant."""
|
| 35 |
+
try:
|
| 36 |
+
# Check if collection exists by getting its info
|
| 37 |
+
self.client.get_collection(self.collection_name)
|
| 38 |
+
logger.info(f"Collection '{self.collection_name}' already exists.")
|
| 39 |
+
except (UnexpectedResponse, Exception):
|
| 40 |
+
# Collection does not exist or error, create it
|
| 41 |
+
logger.info(f"Collection '{self.collection_name}' not found. Creating a new one...")
|
| 42 |
+
self.client.create_collection(
|
| 43 |
+
collection_name=self.collection_name,
|
| 44 |
+
vectors_config=models.VectorParams(
|
| 45 |
+
size=self.vector_size,
|
| 46 |
+
distance=models.Distance.COSINE
|
| 47 |
+
)
|
| 48 |
+
)
|
| 49 |
+
logger.info(f"Collection '{self.collection_name}' created successfully.")
|
| 50 |
+
|
| 51 |
+
def add_documents(self, texts: List[str], embeddings: List[List[float]], metadatas: Optional[List[Dict[str, Any]]] = None) -> int:
|
| 52 |
+
"""
|
| 53 |
+
Upserts document chunks and their corresponding embeddings and payloads into Qdrant.
|
| 54 |
+
"""
|
| 55 |
+
if not texts:
|
| 56 |
+
return 0
|
| 57 |
+
|
| 58 |
+
if metadatas is None:
|
| 59 |
+
metadatas = [{} for _ in range(len(texts))]
|
| 60 |
+
|
| 61 |
+
points = []
|
| 62 |
+
for i, (text, embedding, metadata) in enumerate(zip(texts, embeddings, metadatas)):
|
| 63 |
+
point_id = str(uuid.uuid4())
|
| 64 |
+
payload = {
|
| 65 |
+
"text": text,
|
| 66 |
+
"metadata": metadata
|
| 67 |
+
}
|
| 68 |
+
points.append(
|
| 69 |
+
models.PointStruct(
|
| 70 |
+
id=point_id,
|
| 71 |
+
vector=embedding,
|
| 72 |
+
payload=payload
|
| 73 |
+
)
|
| 74 |
+
)
|
| 75 |
+
|
| 76 |
+
# Qdrant client upsert in batches
|
| 77 |
+
self.client.upsert(
|
| 78 |
+
collection_name=self.collection_name,
|
| 79 |
+
wait=True,
|
| 80 |
+
points=points
|
| 81 |
+
)
|
| 82 |
+
return len(points)
|
| 83 |
+
|
| 84 |
+
def search(self, query_embedding: List[float], top_k: int = 3) -> List[Dict[str, Any]]:
|
| 85 |
+
"""
|
| 86 |
+
Searches the Qdrant collection for similar embeddings.
|
| 87 |
+
Returns a list of dicts with text, metadata, and score.
|
| 88 |
+
"""
|
| 89 |
+
results = self.client.query_points(
|
| 90 |
+
collection_name=self.collection_name,
|
| 91 |
+
query=query_embedding,
|
| 92 |
+
limit=top_k
|
| 93 |
+
)
|
| 94 |
+
|
| 95 |
+
search_results = []
|
| 96 |
+
for hit in results.points:
|
| 97 |
+
search_results.append({
|
| 98 |
+
"text": hit.payload.get("text", ""),
|
| 99 |
+
"metadata": hit.payload.get("metadata", {}),
|
| 100 |
+
"score": hit.score
|
| 101 |
+
})
|
| 102 |
+
return search_results
|
| 103 |
+
|
| 104 |
+
def clear(self) -> bool:
|
| 105 |
+
"""
|
| 106 |
+
Deletes and recreates the collection to reset the database.
|
| 107 |
+
"""
|
| 108 |
+
try:
|
| 109 |
+
self.client.delete_collection(self.collection_name)
|
| 110 |
+
self.client.create_collection(
|
| 111 |
+
collection_name=self.collection_name,
|
| 112 |
+
vectors_config=models.VectorParams(
|
| 113 |
+
size=self.vector_size,
|
| 114 |
+
distance=models.Distance.COSINE
|
| 115 |
+
)
|
| 116 |
+
)
|
| 117 |
+
logger.info(f"Collection '{self.collection_name}' has been reset.")
|
| 118 |
+
return True
|
| 119 |
+
except Exception as e:
|
| 120 |
+
logger.error(f"Error resetting collection '{self.collection_name}': {e}")
|
| 121 |
+
return False
|
| 122 |
+
|
| 123 |
+
def get_status(self) -> Dict[str, Any]:
|
| 124 |
+
"""
|
| 125 |
+
Returns connection and collection stats.
|
| 126 |
+
"""
|
| 127 |
+
try:
|
| 128 |
+
collection_info = self.client.get_collection(self.collection_name)
|
| 129 |
+
vectors_count = collection_info.points_count
|
| 130 |
+
status = collection_info.status.value if hasattr(collection_info.status, "value") else str(collection_info.status)
|
| 131 |
+
except Exception as e:
|
| 132 |
+
logger.error(f"Error retrieving collection info: {e}")
|
| 133 |
+
vectors_count = 0
|
| 134 |
+
status = "unknown"
|
| 135 |
+
|
| 136 |
+
return {
|
| 137 |
+
"connection_type": "Cloud" if self.is_cloud else "In-Memory (Local)",
|
| 138 |
+
"collection_name": self.collection_name,
|
| 139 |
+
"vector_size": self.vector_size,
|
| 140 |
+
"vectors_count": vectors_count,
|
| 141 |
+
"status": status
|
| 142 |
+
}
|