ApeRAG
Author: apecloud
Description: Production-ready RAG (Retrieval-Augmented Generation) platform with Graph RAG + hybrid retrieval (vector/full-text/graph/summary/vision), AI agents, and built-in MCP (Model Context Protocol) server support so assistants can browse collections, run hybrid searches, and ask natural-language questions over your knowledge base. Includes Docker Compose quick-start, optional advanced document parsing via MinerU (doc-ray), and Kubernetes/Helm deployment for production (with KubeBlocks scripts to provision PostgreSQL/Redis/Qdrant/Elasticsearch). Hosted demo + MCP endpoint example: https://rag.apecloud.com/mcp/ using Authorization: Bearer <api-key> (fallback env var APERAG_API_KEY).
Stars: 1.1k
Forks: 120
License: Apache License 2.0
Category: Enterprise
Overview
Installation
git clone https://github.com/apecloud/ApeRAG.git
cd ApeRAG
cp envs/env.template .env
docker-compose up -d --pull always# 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=1git clone https://github.com/apecloud/ApeRAG.git
cd ApeRAGcd deploy/databases/
# (Optional) edit 00-config.sh
bash ./01-prepare.sh
bash ./02-install-database.sh
kubectl get pods -n default
cd ../../helm install aperag ./deploy/aperag --namespace default --create-namespace
kubectl get pods -n default -l app.kubernetes.io/instance=aperagkubectl port-forward svc/aperag-frontend 3000:3000 -n default
kubectl port-forward svc/aperag-api 8000:8000 -n defaultCollection browsing
List and explore your knowledge collections via the MCP server
Hybrid search
Search your knowledge base using vector, full-text, and graph retrieval methods
Intelligent querying
Ask natural-language questions about your documents and get answers based on the knowledge base
FAQs
How does ApeRAG's hybrid search combining vector, full-text, and graph retrieval compare to using separate dedicated tools like Qdrant and Neo4j together?
ApeRAG trades deployment simplicity for reduced configurability. Separate tools let you tune each retrieval mode independently, optimize resource allocation per workload, and upgrade components without coordinating across a bundled stack. The integrated approach eliminates cross-service result merging and authentication overhead, but you inherit ApeRAG's modified LightRAG implementation rather than choosing your preferred graph engine.
Can ApeRAG be deployed without all four databases (PostgreSQL, Redis, Qdrant, Elasticsearch) for a lighter setup?
No, all four databases are mandatory in ApeRAG's architecture. Each serves a distinct function: PostgreSQL stores metadata, Redis handles async job queuing via Celery, Qdrant provides vector embeddings, and Elasticsearch enables full-text indexing. Removing any component breaks core retrieval modes. Teams needing lighter infrastructure should evaluate single-database alternatives like standalone Qdrant or Neo4j GraphRAG.
What types of documents and file formats can ApeRAG's MinerU-powered doc-ray service parse, and how does vision-based retrieval work for charts and diagrams?
MinerU handles PDFs containing tables, formulas, charts, and images through its parsing pipeline. Vision-based retrieval processes visual elements like charts and diagrams alongside text by extracting and indexing them separately, enabling semantic queries against both textual content and visual information within documents, though specific image format support and embedding methodology are not detailed in public documentation.
What are the common challenges when setting up an MCP server?
Common MCP server setup challenges include transport protocol mismatches, authentication configuration errors, and dependency management. Servers using SSE transport require client compatibility verification, while Bearer token provisioning often lacks clear documentation. Environment variable conflicts, missing headers, and firewall restrictions blocking localhost or remote endpoints frequently cause connection failures during initial configuration.
What are the best practices for securing an MCP server?
Best practices include enforcing Bearer token authentication with environment-variable storage, restricting server endpoints to localhost or internal networks, enabling TLS encryption for production deployments, implementing rate limiting to prevent abuse, auditing MCP tool access logs for anomalies, and using SSE transport with authorization headers to prevent unauthorized client connections.
How can I optimize the performance of an MCP server?
Optimize MCP servers by implementing protocol-native progress indicators for long-running operations, configuring low-latency stdio transport with minimal startup args, and integrating monitoring for automated resource management. Apply caching hierarchies, connection pooling, and lazy loading while profiling for bottlenecks. Use centralized governance to enforce scoped permissions, and match transport type to your environment for efficient data exchange without over-provisioned access overhead.