File size: 3,127 Bytes
dac03af | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 | # CortexRAG - API Deployment & Integration Guide
This document outlines the step-by-step roadmap to wrap the **CortexRAG** model into a production-ready FastAPI service, run it locally, expose it publicly via Cloudflare Tunnel, and provide integration documentation for external developers.
---
## Workflow Overview
```mermaid
flowchart LR
A[Local RAG Model] --> B[FastAPI Wrapper]
B --> C[Swagger Testing /docs]
C --> D[Cloudflare Tunnel]
D --> E[Public HTTPS Endpoint]
E --> F[Client Applications]
```
---
## Step-by-Step Implementation Roadmap
### Step 1: Model Code Verification & Preparation
- Verify model initialization, FAISS index loading, sentence-transformer embedding model, reranker, and LLM (e.g., Groq API / local LLM).
- Structure model code cleanly into a reusable class/module (e.g., `rag_pipeline.py`).
### Step 2: FastAPI Web Service (`app.py` / `main.py`)
- Create lightweight FastAPI application.
- Define request model (`QueryRequest`) and response model (`QueryResponse`).
- Define endpoint: `POST /query` (or `/predict`).
- Add lifecycle events (`lifespan` / `@app.on_event("startup")`) to load heavy ML/FAISS models once into memory on startup.
### Step 3: Local Testing via FastAPI Swagger UI
- Launch server locally:
```bash
uvicorn app:app --reload --host 127.0.0.1 --port 8000
```
- Navigate to `http://127.0.0.1:8000/docs` to test input payload, validation, error handling, and JSON output structure.
### Step 4: Developer Manual Verification
- Execute tests using `curl`, Postman, or Python `requests` script to verify:
- Valid queries return correct RAG answers and source documents.
- Invalid inputs return standard `422 Unprocessable Entity` or structured error messages.
### Step 5: Public Exposure via Cloudflare Tunnel
- Install Cloudflare CLI (`cloudflared`).
- Run ad-hoc public tunnel:
```bash
cloudflared tunnel --url http://127.0.0.1:8000
```
- Copy generated HTTPS URL (e.g., `https://your-tunnel-subdomain.trycloudflare.com`).
### Step 6: Public Endpoint Testing
- Validate public URL with live queries:
```bash
curl -X POST "https://your-tunnel-subdomain.trycloudflare.com/query" \
-H "Content-Type: application/json" \
-d "{\"question\": \"What are the symptoms of acute hypertension?\", \"top_k\": 5}"
```
### Step 7: Developer Integration Specification
Provide client developers with exact details required for integration:
| Attribute | Value |
| :--- | :--- |
| **Base URL** | `https://<your-cloudflare-tunnel-url>` |
| **Endpoint** | `/query` |
| **HTTP Method** | `POST` |
| **Headers** | `Content-Type: application/json` |
#### Request Body (JSON)
```json
{
"question": "What are the common side effects of Lisinopril?",
"top_k": 6
}
```
#### Response Body (JSON)
```json
{
"status": "success",
"question": "What are the common side effects of Lisinopril?",
"answer": "Common side effects include dizziness, cough, headache...",
"sources": [
{
"id": 1024,
"text": "Lisinopril documentation excerpt...",
"score": 0.89
}
],
"execution_time_seconds": 0.42
}
```
|