ApeRAG

ApeRAG is a production-ready RAG (Retrieval-Augmented Generation) platform that combines Graph RAG, vector search, and full-text search with advanced AI agents. Build sophisticated AI applications with hybrid retrieval, multimodal document processing, intelligent agents, and enterprise-grade management features.

ApeRAG is the best choice for building your own Knowledge Graph, Context Engineering, and deploying intelligent AI agents that can autonomously search and reason across your knowledge base.

阅读中文文档

• Quick Start
• Key Features
• Kubernetes Deployment (Recommended for Production)
• Development
• Build Docker Image
• Acknowledgments
• License

Quick Start

Before installing ApeRAG, make sure your machine meets the following minimum system requirements:

• CPU >= 2 Core
• RAM >= 4 GiB
• Docker & Docker Compose

The easiest way to start ApeRAG is through Docker Compose. Before running the following commands, make sure that Docker and Docker Compose are installed on your machine:

git clone https://github.com/apecloud/ApeRAG.git
cd ApeRAG
cp envs/env.template .env
docker-compose up -d --pull always

After running, you can access ApeRAG in your browser at:

• Web Interface: http://localhost:3000/web/
• API Documentation: http://localhost:8000/docs

MCP (Model Context Protocol) Support

ApeRAG supports MCP (Model Context Protocol) integration, allowing AI assistants to interact with your knowledge base directly. After starting the services, configure your MCP client with:

{
  "mcpServers": {
    "aperag-mcp": {
      "url": "http://localhost:8000/mcp/",
      "headers": {
        "Authorization": "Bearer your-api-key-here"
      }
    }
  }
}

Authentication (by priority):

1. HTTP Authorization Header (Recommended): Authorization: Bearer your-api-key
2. Environment Variable (Fallback): APERAG_API_KEY=your-api-key

Important: Use your deployed API origin if not local (e.g. https://your-host/mcp/). Replace your-api-key-here with a valid API key from your ApeRAG settings.

The MCP server provides:

• Collection browsing: List and explore your knowledge collections
• Hybrid search: Search using vector, full-text, and graph methods
• Intelligent querying: Ask natural language questions about your documents

Enhanced Document Parsing

For enhanced document parsing capabilities, ApeRAG supports an advanced document parsing service powered by MinerU, which provides superior parsing for complex documents, tables, and formulas.

# Enable advanced document parsing service
DOCRAY_HOST=http://aperag-docray:8639 docker compose --profile docray up -d

# Enable advanced parsing with GPU acceleration 
DOCRAY_HOST=http://aperag-docray-gpu:8639 docker compose --profile docray-gpu up -d

# Enable advanced document parsing service
make compose-up WITH_DOCRAY=1

# Enable advanced parsing with GPU acceleration (recommended)
make compose-up WITH_DOCRAY=1 WITH_GPU=1

Development & Contributing

For developers interested in source code development, advanced configurations, or contributing to ApeRAG, please refer to our Development Guide for detailed setup instructions.

Key Features

1. Advanced Index Types: Five comprehensive index types for optimal retrieval: Vector, Full-text, Graph, Summary, and Vision - providing multi-dimensional document understanding and search capabilities.

2. Intelligent AI Agents: Built-in AI agents with MCP (Model Context Protocol) tool support that can automatically identify relevant collections, search content intelligently, and provide web search capabilities for comprehensive question answering.

3. Enhanced Graph RAG with Entity Normalization: Deeply modified LightRAG implementation with advanced entity normalization (entity merging) for cleaner knowledge graphs and improved relational understanding.

4. Multimodal Processing & Vision Support: Complete multimodal document processing including vision capabilities for images, charts, and visual content analysis alongside traditional text processing.

5. Hybrid Retrieval Engine: Sophisticated retrieval system combining Graph RAG, vector search, full-text search, summary-based retrieval, and vision-based search for comprehensive document understanding.

6. MinerU Integration: Advanced document parsing service powered by MinerU technology, providing superior parsing for complex documents, tables, formulas, and scientific content with optional GPU acceleration.

7. Production-Grade Deployment: Full Kubernetes support with Helm charts and KubeBlocks integration for simplified deployment of production-grade databases (PostgreSQL, Redis, Qdrant, Elasticsearch, Neo4j).

8. Enterprise Management: Built-in audit logging, LLM model management, graph visualization, comprehensive document management interface, and agent workflow management.

9. MCP Integration: Full support for Model Context Protocol (MCP), enabling seamless integration with AI assistants and tools for direct knowledge base access and intelligent querying.

10. Developer Friendly: FastAPI backend, React frontend, async task processing with Celery, extensive testing, comprehensive development guides, and agent development framework for easy contribution and customization.

Kubernetes Deployment (Recommended for Production)

Enterprise-grade deployment with high availability and scalability

Deploy ApeRAG to Kubernetes using our provided Helm chart. This approach offers high availability, scalability, and production-grade management capabilities.

Prerequisites

• Kubernetes cluster (v1.20+)
• kubectl configured and connected to your cluster
• Helm v3+ installed

Clone the Repository

First, clone the ApeRAG repository to get the deployment files:

git clone https://github.com/apecloud/ApeRAG.git
cd ApeRAG

Step 1: Deploy Database Services

ApeRAG requires PostgreSQL, Redis, Qdrant, and Elasticsearch. You have two options:

Option A: Use existing databases - If you already have these databases running in your cluster, edit deploy/aperag/values.yaml to configure your database connection details, then skip to Step 2.

Option B: Deploy databases with KubeBlocks - Use our automated database deployment (database connections are pre-configured):

# Navigate to database deployment scripts
cd deploy/databases/

# (Optional) Review configuration - defaults work for most cases
# edit 00-config.sh

# Install KubeBlocks and deploy databases
bash ./01-prepare.sh          # Installs KubeBlocks
bash ./02-install-database.sh # Deploys PostgreSQL, Redis, Qdrant, Elasticsearch

# Monitor database deployment
kubectl get pods -n default

# Return to project root for Step 2
cd ../../

Wait for all database pods to be in Running status before proceeding.

Step 2: Deploy ApeRAG Application

# If you deployed databases with KubeBlocks in Step 1, database connections are pre-configured
# If you're using existing databases, edit deploy/aperag/values.yaml with your connection details

# Deploy ApeRAG
helm install aperag ./deploy/aperag --namespace default --create-namespace

# Monitor ApeRAG deployment
kubectl get pods -n default -l app.kubernetes.io/instance=aperag

Configuration Options

Resource Requirements: By default, includes doc-ray service (requires 4+ CPU cores, 8GB+ RAM). To disable: set docray.enabled: false in values.yaml.

Advanced Settings: Review values.yaml for additional configuration options including images, resources, and Ingress settings.

Access Your Deployment

Once deployed, access ApeRAG using port forwarding:

# Forward ports for quick access
kubectl port-forward svc/aperag-frontend 3000:3000 -n default
kubectl port-forward svc/aperag-api 8000:8000 -n default

# Access in browser
# Web Interface: http://localhost:3000
# API Documentation: http://localhost:8000/docs

For production environments, configure Ingress in values.yaml for external access.

Troubleshooting

Database Issues: See deploy/databases/README.md for KubeBlocks management, credentials, and uninstall procedures.

Pod Status: Check pod logs for any deployment issues:

kubectl logs -f deployment/aperag-api -n default
kubectl logs -f deployment/aperag-frontend -n default

Acknowledgments

ApeRAG integrates and builds upon several excellent open-source projects:

LightRAG

The graph-based knowledge retrieval capabilities in ApeRAG are powered by a deeply modified version of LightRAG:

• Paper: "LightRAG: Simple and Fast Retrieval-Augmented Generation" (arXiv:2410.05779)
• Authors: Zirui Guo, Lianghao Xia, Yanhua Yu, Tu Ao, Chao Huang
• License: MIT License