Hybrid Rag System

Hybrid rag system is a FastAPI reference project for a retrieval-augmented medical assistant. It uses a local disease dataset, OpenAI embeddings, Milvus hybrid search, and an OpenAI chat model to answer symptom-related questions with retrieved context.

This project is for educational and reference purposes only. It is not a medical device and must not be used as a substitute for professional medical advice, diagnosis, or treatment.

Features

• FastAPI API with /ask and /health endpoints
• Hybrid retrieval with dense OpenAI embeddings and Milvus BM25 sparse search
• Config-driven setup through .env
• Dataset ingestion script for rebuilding the Milvus collection
• Public-repo hygiene with secrets excluded from Git

Project Structure

.
├── app/
│   ├── main.py                 # FastAPI routes
│   ├── config.py               # Environment-backed settings
│   ├── schemas.py              # Request/response models
│   └── services/
│       ├── openai_client.py    # OpenAI client and embeddings
│       └── rag.py              # Retrieval and response generation
├── data/
│   └── disease_diagnosis_dataset.csv
├── scripts/
│   └── ingest_dataset.py       # Builds/rebuilds the Milvus collection
├── main.py                     # Uvicorn entry point
├── requirements.txt
├── .env.example
└── .gitignore

Requirements

• Python 3.12 recommended
• A running Milvus instance
• An OpenAI API key

Setup

Create and activate a virtual environment:

python -m venv .venv
.\.venv\Scripts\activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

Create your local environment file:

Copy-Item .env.example .env

Then set OPENAI_API_KEY in .env.

Environment Variables

Variable	Purpose	Default
OPENAI_API_KEY	OpenAI API key used for embeddings and chat completions	Required
OPENAI_EMBEDDING_MODEL	Embedding model for dense vectors	text-embedding-3-large
OPENAI_CHAT_MODEL	Chat model used for final answers	gpt-4o-mini
MILVUS_URI	Milvus server URI	http://localhost:19530
MILVUS_TOKEN	Milvus token, if required	root:Milvus
MILVUS_COLLECTION_NAME	Collection used for hybrid search	Disease_Hybrid_Collection_final
DATASET_PATH	CSV dataset path	data/disease_diagnosis_dataset.csv
RESPONSE_MAX_TOKENS	Max tokens for generated answer	300
RESPONSE_TEMPERATURE	Chat response temperature	0.5

Build the Vector Collection

Start Milvus first, then run:

python scripts\ingest_dataset.py

The script recreates the configured collection and inserts embedded dataset records.

Run the API

uvicorn main:app --reload

Health check:

curl http://127.0.0.1:8000/health

Ask a question:

curl -X POST http://127.0.0.1:8000/ask `
  -H "Content-Type: application/json" `
  -d "{\"query\":\"I have fever, cough, and body aches\",\"top_k\":5}"

Security Notes

• .env is ignored by Git and should never be committed.
• .env.example is safe to commit because it contains placeholders only.
• Rotate any API keys or tokens that were previously present in local files before publishing this repository.
• Review git status before pushing and confirm no generated folders such as .venv, .idea, or __pycache__ are staged.