📖 Introduction

RAG API is an enterprise-grade Retrieval-Augmented Generation (RAG) service that combines the powerful document parsing capabilities of RAG-Anything with the efficient knowledge graph retrieval technology of LightRAG, providing intelligent Q&A capabilities for your documents.

🎯 Key Highlights

• 🏢 Multi-tenant Isolation - Complete tenant data isolation for enterprise multi-tenant scenarios
• 🎨 Multimodal Parsing - Support for PDF, Word, images and more, with full OCR, tables, and formulas coverage
• ⚡ High-performance Retrieval - Knowledge graph-based hybrid retrieval with 6-15 second query response
• 🔄 Flexible Deployment - Support for production and development modes with one-click switching
• 📦 Ready to Use - One-click Docker deployment, service starts in 3 minutes
• 🎛️ Multiple Parsing Engines - DeepSeek-OCR (Remote API) + MinerU (Local/Remote API) + Docling (Fast)
• 🎨 RAG-Anything VLM Enhancement - Three modes (off/selective/full) for deep chart understanding
• 💾 Task Persistence - Redis storage support, tasks recoverable after container restart/instance rebuild

✨ Features

🏗️ Architecture

System Architecture Diagram

graph TB
    subgraph "Client Layer"
        Client[Client Application]
        WebUI[Web Interface]
    end
    
    subgraph "API Gateway Layer"
        FastAPI[FastAPI Service]
        Auth[Tenant Authentication]
    end
    
    subgraph "Business Logic Layer"
        TenantMgr[Tenant Manager]
        TaskQueue[Task Queue]
        
        subgraph "Document Processing"
            DeepSeekOCR[DeepSeek-OCR<br/>Fast OCR 80% cases]
            MinerU[MinerU Parser<br/>Complex multimodal]
            Docling[Docling Parser<br/>Fast lightweight]
            FileRouter[Smart Router<br/>Complexity scoring]
        end
        
        subgraph "RAG Engine"
            LightRAG[LightRAG Instance Pool<br/>LRU Cache 50]
            KG[Knowledge Graph Engine]
            Vector[Vector Retrieval Engine]
        end
    end
    
    subgraph "Storage Layer"
        DragonflyDB[(DragonflyDB<br/>KV Storage)]
        Qdrant[(Qdrant<br/>Vector Database)]
        Memgraph[(Memgraph<br/>Graph Database)]
        Local[(Local Files<br/>Temp Storage)]
    end
    
    subgraph "External Services"
        LLM[LLM<br/>Entity Extraction/Generation]
        Embedding[Embedding<br/>Vectorization]
        Rerank[Rerank<br/>Reranking]
    end
    
    Client --> FastAPI
    WebUI --> FastAPI
    FastAPI --> Auth
    Auth --> TenantMgr
    TenantMgr --> TaskQueue
    TenantMgr --> LightRAG
    
    TaskQueue --> FileRouter
    FileRouter --> DeepSeekOCR
    FileRouter --> MinerU
    FileRouter --> Docling
    DeepSeekOCR --> LightRAG
    MinerU --> LightRAG
    Docling --> LightRAG
    
    LightRAG --> KG
    LightRAG --> Vector
    
    KG --> DragonflyDB
    KG --> Memgraph
    Vector --> Qdrant
    LightRAG --> Local
    
    LightRAG --> LLM
    LightRAG --> Embedding
    Vector --> Rerank
    
    style FastAPI fill:#00C7B7
    style LightRAG fill:#FF6B6B
    style DeepSeekOCR fill:#5DADE2
    style MinerU fill:#4ECDC4
    style Docling fill:#95E1D3
    style TenantMgr fill:#F38181

Multi-tenant Architecture

graph TB
    subgraph "Tenant A"
        A_Config[Tenant A Config<br/>Independent API Key]
        A_Instance[LightRAG Instance A<br/>Dedicated LLM/Embedding]
        A_Data[(Tenant A Data<br/>Fully Isolated)]
        AConfig --> AInstance
        AInstance --> AData
    end
subgraph "Tenant B"         B_Config[Tenant B Config<br/>Independent API Key]         B_Instance[LightRAG Instance B<br/>Dedicated LLM/Embedding]         B_Data[(Tenant B Data<br/>Fully Isolated)]         BConfig --> BInstance         BInstance --> BData     end
subgraph "Tenant C"         C_Config[Using Global Config]         C_Instance[LightRAG Instance C<br/>Shared LLM/Embedding]         C_Data[(Tenant C Data<br/>Fully Isolated)]         CConfig --> CInstance         CInstance --> CData     end
Pool[Instance Pool Manager<br/>LRU Cache + Config Isolation]     Global[Global Config<br/>Default API Key]
Pool --> A_Instance     Pool --> B_Instance     Pool --> C_Instance
C_Config -.fallback.-> Global
style Pool fill:#F38181     style Global fill:#95E1D3     style A_Config fill:#FFD93D     style B_Config fill:#FFD93D     style C_Config fill:#E8E8E8

Core Technology Stack

🚀 Quick Start

Option 1: One-click Deployment (Recommended)

Suitable for production and testing environments:

# 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/

Access Swagger Documentation: http://localhost:8000/docs

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

Minimum configuration (required):

# LLM Configuration (Function-oriented naming)
LLMAPIKEY=yourllmapi_key
LLMBASEURL=https://ark.cn-beijing.volces.com/api/v3
LLM_MODEL=ep-xxx-xxx
LLMREQUESTSPER_MINUTE=800        # Rate limit (optional)
LLMTOKENSPER_MINUTE=40000        # Rate limit (optional)
LLMMAXASYNC=8                    # [Optional, expert mode] Manual concurrency control
                                   # Auto-calculated when unset: min(RPM, TPM/3500) = 11
Embedding Configuration (Function-oriented naming)
EMBEDDINGAPIKEY=yourembeddingapi_key
EMBEDDINGBASEURL=https://api.siliconflow.cn/v1
EMBEDDING_MODEL=Qwen/Qwen3-Embedding-0.6B
EMBEDDING_DIM=1024
EMBEDDINGMAXASYNC=32             # [Optional, expert mode] Auto-calculated when unset: 800
MinerU Mode (Remote recommended)
MINERU_MODE=remote
MINERUAPITOKEN=your_token
MINERUHTTPTIMEOUT=60              # MinerU download timeout (seconds, default 60)
FILESERVICEBASE_URL=http://your-ip:8000
VLM Chart Enhancement Configuration 🆕
⚠️ Note: Only effective in MINERU_MODE=remote
RAGVLMMODE=off                    # off / selective / full
RAGIMPORTANCETHRESHOLD=0.5        # Importance threshold (selective mode)
RAGCONTEXTWINDOW=2                # Context window (full mode)
RAGCONTEXTMODE=page               # page / chunk
RAGMAXCONTEXT_TOKENS=3000         # Max context tokens
Task Storage Configuration 🆕
TASKSTORESTORAGE=redis            # memory / redis (production recommends redis)
Document Insert Verification Configuration 🆕
DOCINSERTVERIFICATION_TIMEOUT=300        # Verification timeout (seconds, default 5 minutes)
DOCINSERTVERIFICATIONPOLLINTERVAL=0.5  # Poll interval (seconds, default 500ms)
Model Call Timeout Configuration 🆕
MODELCALLTIMEOUT=90               # Model call max timeout (seconds, default 90)

⚡ Auto Concurrency Calculation:

• LLM: When LLMMAXASYNC is unset, auto-calculated as min(RPM, TPM/3500) ≈ 11
• Embedding: When EMBEDDINGMAXASYNC is unset, auto-calculated as min(RPM, TPM/500) ≈ 800
• Rerank: When RERANKMAXASYNC is unset, auto-calculated as min(RPM, TPM/500) ≈ 800

See env.example for complete configuration.

📚 API Documentation

Core Endpoints

1️⃣ Upload Document

# Single file upload (default mode)
curl -X POST "http://localhost:8000/insert?tenantid=yourtenant&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?tenantid=yourtenant&docid=doc2&vlmmode=off" \
  -F "file=@document.pdf"
selective: Selective processing of important charts (balance performance and quality)
curl -X POST "http://localhost:8000/insert?tenantid=yourtenant&docid=doc3&vlmmode=selective" \
  -F "file=@document.pdf"
full: Complete RAG-Anything processing (highest quality, context enhancement enabled)
curl -X POST "http://localhost:8000/insert?tenantid=yourtenant&docid=doc4&vlmmode=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?tenantid=yourtenant" \
  -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)

New Advanced Features:

• ✨ Conversation History: Support for multi-turn conversation context
• ✨ Custom Prompts: Customize response style
• ✨ Response Format Control: paragraph/list/json
• ✨ Keyword Precision Retrieval: hlkeywords/llkeywords
• ✨ Streaming Output: Real-time generation viewing

# Basic query curl -X POST "http://localhost:8000/query?tenantid=yourtenant" \   -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?tenantid=yourtenant" \
  -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?tenantid=yourtenant" \
  -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?tenantid=yourtenant"
Response
{
  "task_id": "task-xxx-xxx",
  "status": "completed",
  "progress": 100,
  "result": {...}
}

5️⃣ Tenant Management

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

VLM Mode Comparison 🆕

| Mode | Speed | Quality | Resource Usage | Use Case | |------|------|------|----------|---------| | off | ⚡⚡⚡⚡⚡ | ⭐⭐⭐ | Very Low | Plain text documents, fast batch processing | | selective | ⚡⚡⚡⚡ | ⭐⭐⭐⭐ | Low | Documents with key charts (recommended) | | full | ⚡⚡ | ⭐⭐⭐⭐⭐ | High | Chart-intensive research reports, papers |

Processing Time Estimate (20-page PDF example):

• off: ~10 seconds(Markdown only)
• selective: ~30 seconds(5-10 important charts)
• full: ~120 seconds(complete context processing)

Query Mode Comparison

| Mode | Speed | Accuracy | Use Case | |------|------|--------|---------| | naive | ⚡⚡⚡⚡⚡ | ⭐⭐⭐ | Simple Q&A, fast retrieval | | local | ⚡⚡⚡⚡ | ⭐⭐⭐⭐ | Local entity relationship queries | | global | ⚡⚡⚡ | ⭐⭐⭐⭐ | Global knowledge graph reasoning | | hybrid | ⚡⚡⚡ | ⭐⭐⭐⭐⭐ | Hybrid retrieval (recommended) | | mix | ⚡⚡ | ⭐⭐⭐⭐⭐ | Complex questions, deep analysis |

Query API v2.0 Advanced Parameters

| Parameter | Type | Description | Example | |------|------|------|------| | conversation_history | List[Dict] | Multi-turn conversation context | [{"role": "user", "content": "..."}] | | user_prompt | str | Custom prompt | "Please answer in professional academic language" | | response_type | str | Response format | "paragraph", "list", "json" | | hl_keywords | List[str] | High priority keywords | ["artificial intelligence", "machine learning"] | | ll_keywords | List[str] | Low priority keywords | ["application", "case study"] | | onlyneedcontext | bool | Return context only (debug) | true | | maxentitytokens | int | Entity token limit | 6000 |

Complete API documentation:http://localhost:8000/docs

🎯 Usage Examples

Python SDK

import requests
Configuration
BASE_URL = "http://localhost:8000"
TENANTID = "yourtenant"
Upload document
with open("document.pdf", "rb") as f:
    response = requests.post(
        f"{BASE_URL}/insert",
        params={"tenantid": TENANTID, "doc_id": "doc1"},
        files={"file": f}
    )
    taskid = response.json()["taskid"]
    print(f"Task ID: {task_id}")
Query
response = requests.post(
    f"{BASE_URL}/query",
    params={"tenantid": TENANTID},
    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
TASKID=$(curl -X POST "http://localhost:8000/insert?tenantid=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/$TASKID?tenantid=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

Minimum Configuration:

• CPU: 2 cores
• RAM: 4GB
• Disk: 40GB SSD
• OS: Ubuntu 20.04+ / Debian 11+ / CentOS 8+

• CPU: 4 cores
• RAM: 8GB
• Disk: 100GB SSD
• OS: Ubuntu 22.04 LTS

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

Supports DragonflyDB + Qdrant + Memgraph external storage (enabled by default):

# Configure in .env
USEEXTERNALSTORAGE=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=

See External Storage Deployment Documentation。

Docker Compose Configuration

The project provides two configuration files:

| File | Purpose | Features | |------|------|------| | docker-compose.yml | Production mode | Code packaged in image, optimal performance | | docker-compose.dev.yml | Development mode | Code mounted externally, supports hot-reload |

Select configuration file:

# 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

Configure in .env:

# ⚡ Concurrency Control (Recommended: use auto-calculation)
LLMMAXASYNC=8                    # [Expert mode] Manually specify LLM concurrency
                                   # Auto-calculated when unset: min(RPM, TPM/3500) ≈ 11
EMBEDDINGMAXASYNC=32             # [Expert mode] Manually specify Embedding concurrency
                                   # Auto-calculated when unset: min(RPM, TPM/500) ≈ 800
RERANKMAXASYNC=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
CHUNKTOPK=10  # Text chunk retrieval count
Document processing concurrency
DOCUMENTPROCESSINGCONCURRENCY=10  # Remote mode can be set high, local mode set to 1

🎯 Concurrency Configuration Recommendations:

• Recommended: Don't set *MAXASYNC, let the system auto-calculate based on TPM/RPM
• Expert mode: If manual control needed, can set LLMMAXASYNC and other parameters
• Advantage: Auto-calculation completely avoids 429 errors (TPM limit reached)

Mode Selection

• MinerU Remote Mode (Recommended): High concurrency, resource-efficient
• MinerU Local Mode: Requires GPU, high memory usage
• Docling Mode: Fast and lightweight, suitable for simple documents

🏢 Multi-tenant Usage

Tenant Isolation

Each tenant has:

• ✅ Independent LightRAG instance
• ✅ Isolated data storage space
• ✅ Independent vector index
• ✅ Dedicated knowledge graph
• ✅ Independent service configuration (LLM, Embedding, Rerank, DeepSeek-OCR, MinerU)🆕

Tenant Configuration Management 🆕

Each tenant can independently configure 5 services with hot-reload support:

# 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 '{
    "dsocrconfig": {
      "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
    },
    "dsocrconfig": {
      "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
{
  "tenantid": "tenanta",
  "dsocrconfig": {
    "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"

Supported Configuration Items:

| Service | Config Field | Description | |------|---------|------| | LLM | llmconfig | Model, API key, baseurl, etc. | | Embedding | embedding_config | Model, API key, dimension, etc. | | Rerank | rerank_config | Model, API key, etc. | | DeepSeek-OCR | dsocrconfig | API key, timeout, mode, etc. | | MinerU | mineru_config | API token, version, timeout, etc. |

Configuration Priority: Tenant config > Global config

Use Cases:

• 🔐 Multi-tenant SaaS: Each tenant uses their own API key
• 💰 Pay-per-use: Track tenant usage through independent API keys
• 🎯 Differentiated Services: Different tenants use different models (GPT-4 vs GPT-3.5)
• 🧪 A/B Testing: Compare different models/parameters

Usage

All APIs require tenant_id parameter:

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

Instance Pool Management

• Capacity: Cache up to 50 tenant instances
• Strategy: LRU (Least Recently Used) automatic cleanup
• Config Isolation: Each tenant can use independent LLM, Embedding, parser configuration

📊 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/testconcurrentperf.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?tenantid=yourtenant"
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
│   ├── fileurlservice.py # Temporary file service
│   ├── mineru_client.py    # MinerU client
│   └── mineruresultprocessor.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

# View detailed logs
docker compose logs
Check port usage
netstat -tulpn | grep 8000
Check Docker status
docker ps -a

# Option 1: Upgrade to latest version (recommended) 
Modify LightRAG version in pyproject.toml
 
lightrag = "^1.4.9.4"

Rebuild image
docker compose down
docker compose up -d --build
Option 2: Clean old data (temporary solution)
rm -rf ./raglocalstorage
docker compose restart

# View supported formats curl http://localhost:8000/docs

# Stop services
docker compose down
Delete all volumes (clear database)
docker volume rm rag-apidragonflydbdata rag-apiqdrantdata rag-apimemgraphdata
Modify EMBEDDING_DIM in .env
EMBEDDING_DIM=1024  # or 4096, must match the model
Restart
docker compose up -d

# Modify .env MAX_ASYNC=8 TOP_K=20 CHUNKTOPK=10

# Switch to remote mode 
Modify in .env
 MINERU_MODE=remote MINERUAPITOKEN=your_token

Or limit concurrency
DOCUMENTPROCESSINGCONCURRENCY=1

# Modify .env
TASKSTORESTORAGE=redis
Restart services
docker compose restart
Verify
docker compose logs api | grep TaskStore
Should see: ✅ TaskStore: Redis connection successful

# Modify .env
VLM_TIMEOUT=300  # Increase to 5 minutes
RAGVLMMODE=selective  # downgrade to selective

# View detailed logs docker compose logs -f | grep VLM

Test single file
curl -X POST 'http://localhost:8000/insert?tenantid=test&docid=test&vlm_mode=off' \
  -F 'file=@test.pdf'

Performance Tuning Recommendations

| Scenario | MAXASYNC | TOPK | CHUNKTOPK | MINERU_MODE | |------|-----------|-------|-------------|-------------| | Fast response | 8 | 10 | 5 | remote | | Balanced mode | 8 | 20 | 10 | remote | | High accuracy | 4 | 60 | 20 | remote | | Resource limited | 4 | 20 | 10 | remote |

📖 Documentation

• 📘 Architecture Design Documentation - Detailed system architecture and design concepts
• 📗 Usage Guide - Complete API usage documentation and examples
• 📙 Deployment Mode Description - Production mode vs Development mode
• 📕 PR Workflow - Process guide for code contribution
• 📔 External Storage Deployment - Redis/PostgreSQL/Neo4j configuration
• 📊 API Comparison Analysis - rag-api vs LightRAG official API comparison
• 🌐 WebUI Integration Guide - Knowledge graph visualization integration

🤝 Contributing

We welcome all forms of contribution!

How to Contribute

• Fork the project

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

• Create feature branch

git checkout -b feature/your-feature-name

• Development and Testing

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

• Submit code

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

• Create Pull Request

Commit Conventions

Use semantic commit messages:

• feat: New feature
• fix: Bug fix
• docs: Documentation update
• style: Code formatting
• refactor: Code refactoring
• perf: Performance optimization
• test: Testing
• chore: Build/tools

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

🙏 Acknowledgments

This project is built on the following excellent open source projects:

• LightRAG - Efficient knowledge graph RAG framework
• RAG-Anything - Multimodal document parsing
• MinerU - Powerful PDF parsing tool
• Docling - Lightweight document parsing
• FastAPI - Modern Python web framework

📬 Contact Us

• GitHub: @BukeLy
• Email: buledream233@gmail.com
• Issues: Submit Issue
• Discussions: Join Discussion