Submit
apecloud

ApeRAG

Community apecloud
Updated

ApeRAG: Best choice for building your own Knowledge Graph and for Context Engineering

ApeRAG

HarryPotterKG.png

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

ApeRAG is the best choice for building your own Knowledge Graph and for Context Engineering.

阅读中文文档

  • 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
cp frontend/deploy/env.local.template frontend/.env
docker compose up -d

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

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"
      }
    }
  }
}

Important: Replace http://localhost:8000 with your actual ApeRAG API URL and 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.

Enhanced Document Parsing Commands 
# 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

Or use the Makefile shortcuts (requires GNU Make):

# 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. Hybrid Retrieval Engine:Combines Graph RAG, vector search, and full-text search for comprehensive document understanding and retrieval.

2. Graph RAG with LightRAG:Enhanced version of LightRAG for advanced graph-based knowledge extraction, enabling deep relational and contextual queries.

3. 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.

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

5. Multimodal Document Processing:Supports various document formats (PDF, DOCX, etc.) with intelligent content extraction and structure recognition.

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

7. 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.

8. Developer Friendly:FastAPI backend, React frontend, async task processing with Celery, extensive testing, and comprehensive development guides 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

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

We have extensively modified LightRAG to support production-grade concurrent processing, distributed task queues (Celery/Prefect), and stateless operations. See our LightRAG modifications changelog for details.

License

ApeRAG is licensed under the Apache License 2.0. See the LICENSE file for details.

MCP Server · Populars

MCP Server · New