Multi-tenant Multimodal Document Intelligent Retrieval System

Enterprise-grade RAG service built on RAG-Anything and LightRAG

CI Python FastAPI LightRAG Docker License

English | 简体中文

Features • Quick Start • Architecture • API Documentation • Deployment

📖 Introduction

🎯 Key Highlights

✨ Features

🏗️ Architecture

System Architecture Diagram

Multi-tenant Architecture

Core Technology Stack

🚀 Quick Start

Option 1: One-click Deployment (Recommended)

# 1. Clone the project
git clone https://github.com/BukeLy/rag-api.git
cd rag-api
# 2. Configure environment variables
cp env.example .env
nano .env # Fill in your API keys
# 3. Run deployment script
chmod +x deploy.sh
./deploy.sh
# Select deployment mode:
# 1) Production Mode - Standard container deployment
# 2) Development Mode - Code hot-reload
# 4. Verify service
curl http://localhost:8000/

Option 2: Docker Compose

Production Mode

# Configure environment variables
cp env.example .env
nano .env
# Start services
docker compose -f docker-compose.yml up -d
# View logs
docker compose -f docker-compose.yml logs -f

Development Mode (Code Hot-reload)

# Start development environment
docker compose -f docker-compose.dev.yml up -d
# Or use quick script
./scripts/dev.sh
# Code changes will auto-reload without restart

Option 3: Local Development

# Install uv (Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh
# Install dependencies
uv sync
# Configure environment variables
cp env.example .env
nano .env
# Start services
uv run uvicorn main:app --host 0.0.0.0 --port 8000 --reload

Environment Variable Configuration

# LLM Configuration (Function-oriented naming)
LLM_API_KEY=your_llm_api_key
LLM_BASE_URL=https://ark.cn-beijing.volces.com/api/v3
LLM_MODEL=ep-xxx-xxx
# LLM_REQUESTS_PER_MINUTE=800 # Rate limit (optional)
# LLM_TOKENS_PER_MINUTE=40000 # Rate limit (optional)
# LLM_MAX_ASYNC=8 # [Optional, expert mode] Manual concurrency control
# # Auto-calculated when unset: min(RPM, TPM/3500) = 11
# Embedding Configuration (Function-oriented naming)
EMBEDDING_API_KEY=your_embedding_api_key
EMBEDDING_BASE_URL=https://api.siliconflow.cn/v1
EMBEDDING_MODEL=Qwen/Qwen3-Embedding-0.6B
EMBEDDING_DIM=1024
# EMBEDDING_MAX_ASYNC=32 # [Optional, expert mode] Auto-calculated when unset: 800
# MinerU Mode (Remote recommended)
MINERU_MODE=remote
MINERU_API_TOKEN=your_token
MINERU_HTTP_TIMEOUT=60 # MinerU download timeout (seconds, default 60)
FILE_SERVICE_BASE_URL=http://your-ip:8000
# VLM Chart Enhancement Configuration 🆕
# ⚠️ Note: Only effective in MINERU_MODE=remote
RAG_VLM_MODE=off # off / selective / full
RAG_IMPORTANCE_THRESHOLD=0.5 # Importance threshold (selective mode)
RAG_CONTEXT_WINDOW=2 # Context window (full mode)
RAG_CONTEXT_MODE=page # page / chunk
RAG_MAX_CONTEXT_TOKENS=3000 # Max context tokens
# Task Storage Configuration 🆕
TASK_STORE_STORAGE=redis # memory / redis (production recommends redis)
# Document Insert Verification Configuration 🆕
DOC_INSERT_VERIFICATION_TIMEOUT=300 # Verification timeout (seconds, default 5 minutes)
DOC_INSERT_VERIFICATION_POLL_INTERVAL=0.5 # Poll interval (seconds, default 500ms)
# Model Call Timeout Configuration 🆕
MODEL_CALL_TIMEOUT=90 # Model call max timeout (seconds, default 90)

📚 API Documentation

Core Endpoints

1️⃣ Upload Document

# Single file upload (default mode)
curl -X POST "http://localhost:8000/insert?tenant_id=your_tenant&doc_id=doc1" \
 -F "file=@document.pdf" \
 -F "parser=auto"
# VLM chart enhancement mode 🆕
# off: Markdown only (fastest, default)
curl -X POST "http://localhost:8000/insert?tenant_id=your_tenant&doc_id=doc2&vlm_mode=off" \
 -F "file=@document.pdf"
# selective: Selective processing of important charts (balance performance and quality)
curl -X POST "http://localhost:8000/insert?tenant_id=your_tenant&doc_id=doc3&vlm_mode=selective" \
 -F "file=@document.pdf"
# full: Complete RAG-Anything processing (highest quality, context enhancement enabled)
curl -X POST "http://localhost:8000/insert?tenant_id=your_tenant&doc_id=doc4&vlm_mode=full" \
 -F "file=@document.pdf"
# Response
{
 "task_id": "task-xxx-xxx",
 "doc_id": "doc1",
 "filename": "document.pdf",
 "vlm_mode": "off",
 "status": "pending"
}

2️⃣ Batch Upload

curl -X POST "http://localhost:8000/batch?tenant_id=your_tenant" \
 -F "files=@doc1.pdf" \
 -F "files=@doc2.docx" \
 -F "files=@image.png"
# Response
{
 "batch_id": "batch-xxx-xxx",
 "total_files": 3,
 "accepted_files": 3,
 "tasks": [...]
}

3️⃣ Intelligent Query (Query API v2.0)

# Basic query
curl -X POST "http://localhost:8000/query?tenant_id=your_tenant" \
 -H "Content-Type: application/json" \
 -d '{
 "query": "What are the core viewpoints in the document?",
 "mode": "hybrid"
 }'
# Advanced query (multi-turn dialogue + custom prompt)
curl -X POST "http://localhost:8000/query?tenant_id=your_tenant" \
 -H "Content-Type: application/json" \
 -d '{
 "query": "Can you elaborate on the second point?",
 "mode": "hybrid",
 "conversation_history": [
 {"role": "user", "content": "What are the key points?"},
 {"role": "assistant", "content": "There are mainly three points..."}
 ],
 "user_prompt": "Please answer in professional academic language",
 "response_type": "list"
 }'
# Streaming query (SSE)
curl -N -X POST "http://localhost:8000/query/stream?tenant_id=your_tenant" \
 -H "Content-Type: application/json" \
 -d '{
 "query": "What are the core viewpoints in the document?",
 "mode": "hybrid"
 }'
# Response (real-time streaming output)
data: {"chunk": "Based on", "done": false}
data: {"chunk": "document content", "done": false}
data: {"done": true}

4️⃣ Task Status Query

curl "http://localhost:8000/task/task-xxx-xxx?tenant_id=your_tenant"
# Response
{
 "task_id": "task-xxx-xxx",
 "status": "completed",
 "progress": 100,
 "result": {...}
}

5️⃣ Tenant Management

# Get tenant statistics
curl "http://localhost:8000/tenants/stats?tenant_id=your_tenant"
# Clear tenant cache
curl -X DELETE "http://localhost:8000/tenants/cache?tenant_id=your_tenant"
# View instance pool status (admin)
curl "http://localhost:8000/tenants/pool/stats"

VLM Mode Comparison 🆕

Query Mode Comparison

Query API v2.0 Advanced Parameters

🎯 Usage Examples

Python SDK

import requests
# Configuration
BASE_URL = "http://localhost:8000"
TENANT_ID = "your_tenant"
# Upload document
with open("document.pdf", "rb") as f:
 response = requests.post(
 f"{BASE_URL}/insert",
 params={"tenant_id": TENANT_ID, "doc_id": "doc1"},
 files={"file": f}
 )
 task_id = response.json()["task_id"]
 print(f"Task ID: {task_id}")
# Query
response = requests.post(
 f"{BASE_URL}/query",
 params={"tenant_id": TENANT_ID},
 json={
 "query": "What is the main content of the document?",
 "mode": "hybrid",
 "top_k": 10
 }
)
result = response.json()
print(f"Answer: {result['answer']}")

Complete cURL Example

# 1. Upload PDF document
TASK_ID=$(curl -X POST "http://localhost:8000/insert?tenant_id=demo&doc_id=report" \
 -F "file=@report.pdf" | jq -r '.task_id')
echo "Task ID: $TASK_ID"
# 2. Wait for processing completion
while true; do
 STATUS=$(curl -s "http://localhost:8000/task/$TASK_ID?tenant_id=demo" | jq -r '.status')
 echo "Status: $STATUS"
 if [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ]; then
 break
 fi
 sleep 2
done
# 3. Query document content
curl -X POST "http://localhost:8000/query?tenant_id=demo" \
 -H "Content-Type: application/json" \
 -d '{
 "query": "What are the main conclusions of this report?",
 "mode": "hybrid"
 }' | jq '.answer'

🛠️ Deployment

System Requirements

Server Deployment

Quick Deployment on Aliyun/Tencent Cloud

# SSH login to server
ssh root@your-server-ip
# Clone project
git clone https://github.com/BukeLy/rag-api.git
cd rag-api
# Run one-click deployment script
chmod +x deploy.sh
./deploy.sh
# The script will automatically:
# 1. Install Docker and Docker Compose
# 2. Configure environment variables
# 3. Optimize system parameters
# 4. Start services
# 5. Verify health status

External Storage Configuration

# Configure in .env
USE_EXTERNAL_STORAGE=true
# DragonflyDB configuration (KV Storage)
KV_STORAGE=RedisKVStorage
REDIS_URI=redis://dragonflydb:6379/0
# Qdrant configuration (vector storage)
VECTOR_STORAGE=QdrantVectorDBStorage
QDRANT_URL=http://qdrant:6333
# Memgraph configuration (graph storage)
GRAPH_STORAGE=MemgraphStorage
MEMGRAPH_URI=bolt://memgraph:7687
MEMGRAPH_USERNAME=
MEMGRAPH_PASSWORD=

Docker Compose Configuration

# Production mode
docker compose -f docker-compose.yml up -d
# Development mode
docker compose -f docker-compose.dev.yml up -d

Performance Optimization

Tuning Parameters

# ⚡ Concurrency Control (Recommended: use auto-calculation)
# LLM_MAX_ASYNC=8 # [Expert mode] Manually specify LLM concurrency
# # Auto-calculated when unset: min(RPM, TPM/3500) ≈ 11
# EMBEDDING_MAX_ASYNC=32 # [Expert mode] Manually specify Embedding concurrency
# # Auto-calculated when unset: min(RPM, TPM/500) ≈ 800
# RERANK_MAX_ASYNC=16 # [Expert mode] Manually specify Rerank concurrency
# # Auto-calculated when unset: min(RPM, TPM/500) ≈ 800
# Retrieval count (affects query quality and speed)
TOP_K=20 # Entity/relationship retrieval count
CHUNK_TOP_K=10 # Text chunk retrieval count
# Document processing concurrency
DOCUMENT_PROCESSING_CONCURRENCY=10 # Remote mode can be set high, local mode set to 1

Mode Selection

🏢 Multi-tenant Usage

Tenant Isolation

Tenant Configuration Management 🆕

# 1️⃣ Configure independent DeepSeek-OCR API key for Tenant A
curl -X PUT "http://localhost:8000/tenants/tenant_a/config" \
 -H "Content-Type: application/json" \
 -d '{
 "ds_ocr_config": {
 "api_key": "sk-tenant-a-ds-ocr-key",
 "base_url": "https://api.siliconflow.cn/v1",
 "model": "deepseek-ai/DeepSeek-OCR",
 "timeout": 90
 }
 }'
# 2️⃣ Configure independent MinerU API token for Tenant B
curl -X PUT "http://localhost:8000/tenants/tenant_b/config" \
 -H "Content-Type: application/json" \
 -d '{
 "mineru_config": {
 "api_token": "tenant-b-mineru-token",
 "base_url": "https://mineru.net",
 "model_version": "vlm"
 }
 }'
# 3️⃣ Configure multiple services simultaneously (LLM + Embedding + DeepSeek-OCR)
curl -X PUT "http://localhost:8000/tenants/tenant_c/config" \
 -H "Content-Type: application/json" \
 -d '{
 "llm_config": {
 "api_key": "sk-tenant-c-llm-key",
 "model": "gpt-4"
 },
 "embedding_config": {
 "api_key": "sk-tenant-c-embedding-key",
 "model": "Qwen/Qwen3-Embedding-0.6B",
 "dim": 1024
 },
 "ds_ocr_config": {
 "api_key": "sk-tenant-c-ds-ocr-key"
 }
 }'
# 4️⃣ Query tenant configuration (API key auto-masked)
curl "http://localhost:8000/tenants/tenant_a/config"
# Response example
{
 "tenant_id": "tenant_a",
 "ds_ocr_config": {
 "api_key": "sk-***-key", // Auto-masked
 "timeout": 90
 },
 "merged_config": {
 "llm": {...}, // Using Global Config
 "embedding": {...}, // Using Global Config
 "rerank": {...}, // Using Global Config
 "ds_ocr": {...}, // Using tenant config
 "mineru": {...} // Using Global Config
 }
}
# 5️⃣ Refresh config cache (config hot-reload)
curl -X POST "http://localhost:8000/tenants/tenant_a/config/refresh"
# 6️⃣ Delete tenant config (restore to global config)
curl -X DELETE "http://localhost:8000/tenants/tenant_a/config"

Usage

# Tenant A upload document
curl -X POST "http://localhost:8000/insert?tenant_id=tenant_a&doc_id=doc1" \
 -F "file=@doc.pdf"
# Tenant B upload document (fully isolated)
curl -X POST "http://localhost:8000/insert?tenant_id=tenant_b&doc_id=doc1" \
 -F "file=@doc.pdf"
# Tenant A query (can only query own documents)
curl -X POST "http://localhost:8000/query?tenant_id=tenant_a" \
 -H "Content-Type: application/json" \
 -d '{"query": "document content", "mode": "hybrid"}'

Instance Pool Management

📊 Monitoring & Maintenance

Common Commands

# View service status
docker compose ps
# View real-time logs
docker compose logs -f
# Restart services
docker compose restart
# Stop services
docker compose down
# View resource usage
docker stats
# Clean Docker resources
docker system prune -f

Maintenance Scripts

# Monitor service health
./scripts/monitor.sh
# Backup data
./scripts/backup.sh
# Update services
./scripts/update.sh
# Performance testing
./scripts/test_concurrent_perf.sh
# Performance monitoring
./scripts/monitor_performance.sh

Health Checks

# Complete health check (recommended)
./scripts/health_check.sh
./scripts/health_check.sh --verbose # verbose output
# API health check
curl http://localhost:8000/
# Tenant statistics
curl "http://localhost:8000/tenants/stats?tenant_id=your_tenant"
# Instance pool status
curl "http://localhost:8000/tenants/pool/stats"

🗂️ Project Structure

rag-api/
├── main.py # FastAPI application entry
├── api/ # API route modules
│ ├── __init__.py # Route aggregation
│ ├── insert.py # Document upload (single/batch)
│ ├── query.py # Intelligent query
│ ├── task.py # Task status query
│ ├── tenant.py # Tenant management
│ ├── files.py # File service
│ ├── models.py # Pydantic models
│ └── task_store.py # Task storage
├── src/ # Core business logic
│ ├── rag.py # LightRAG lifecycle management
│ ├── multi_tenant.py # Multi-tenant instance manager
│ ├── tenant_deps.py # Tenant dependency injection
│ ├── logger.py # Unified logging
│ ├── metrics.py # Performance metrics
│ ├── file_url_service.py # Temporary file service
│ ├── mineru_client.py # MinerU client
│ └── mineru_result_processor.py # Result processing
├── docs/ # Documentation
│ ├── ARCHITECTURE.md # Architecture design documentation
│ ├── USAGE.md # Detailed usage guide
│ ├── DEPLOY_MODES.md # Deployment mode description
│ ├── PR_WORKFLOW.md # PR workflow
│ └── ...
├── scripts/ # Maintenance scripts
│ ├── dev.sh # Development mode quick start
│ ├── monitor.sh # Service monitoring
│ ├── backup.sh # Data backup
│ ├── update.sh # Service update
│ └── ...
├── deploy.sh # One-click deployment script
├── docker-compose.yml # Production mode configuration
├── docker-compose.dev.yml # Development mode configuration
├── Dockerfile # Production image
├── Dockerfile.dev # Development image
├── pyproject.toml # Project dependencies
├── uv.lock # Dependency lock
├── env.example # Environment variable template
├── CLAUDE.md # Claude AI guide
└── README.md # This documentation

🐛 Troubleshooting

Common Issues

Performance Tuning Recommendations

📖 Documentation

🤝 Contributing

How to Contribute

git clone https://github.com/BukeLy/rag-api.git
cd rag-api

git checkout -b feature/your-feature-name

# Install dependencies
uv sync
# Run tests
uv run pytest
# Code formatting
uv run black .
uv run isort .

git add .
git commit -m "feat: Add new feature"
git push origin feature/your-feature-name

Commit Conventions

📄 License

🙏 Acknowledgments

📬 Contact Us

⭐ If this project helps you, please give it a Star!

Made with ❤️ by BukeLy

© 2025 RAG API. All rights reserved.