Unified Knowledge Graph RAG on AWS

🇰🇷 한국어 README · 🤝 Contributing

An AWS-native knowledge graph RAG (Retrieval-Augmented Generation) framework that turns large, multilingual document corpora into a knowledge graph on Amazon Neptune and Amazon OpenSearch Service and answers questions over it with Amazon Bedrock, using multi-hop graph traversal to reason across document boundaries. It reimplements Microsoft GraphRAG and LightRAG, with HippoRAG 2's Personalized PageRank and an opt-in RAPTOR summary tree, on one shared stack, so you choose the retrieval methodology per query rather than per deployment and build only the methodologies you use. Running several methodologies on one stack, triple-hybrid search, incremental indexing, and multilingual processing are deliberate enhancements over the source papers.

What each of them adds over GraphRAG and LightRAG, and where the framework deliberately departs from them: Beyond the papers.

Read the AWS Open Source Blog introduction for an overview of the architecture, both retrieval methodologies, and benchmark results.

Why this framework

• Four methodologies on one AWS stack. GraphRAG (community summaries), LightRAG (dual-level keywords), HippoRAG 2 (Personalized PageRank over entities and passages) and RAPTOR (a summary tree, opt-in) share ingestion, indexing, caching and search; only the retrieval algorithm differs, chosen per query. indexing.methodologies builds only what the selected ones read (Methodology profiles). Every answer returns the sources that were actually in the model's context.
• Triple-hybrid search. BM25, vector search and Neptune graph traversal, fused with Reciprocal Rank Fusion and reranked with a Bedrock rerank model (the chunk-only strategies skip the graph; global maps community reports instead).
• Incremental indexing. With the doc-status registry on (providers.doc_status.enabled), only new and changed documents are re-indexed and merged into the live graph; deleting a document removes only what no other document states (Incremental indexing).
• Bring your own knowledge graph. Seed graphs (JSONL, CSV or an RDF A-Box) merge a graph you already have into the extracted one as virtual documents: documents stay canonical, and the seed adds descriptions, properties, IRIs and edges (Seed graphs).
• Multilingual. Optional translation at indexing and query time, per-language analyzers (for example nori for Korean) and multilingual keyword extraction.
• Prompt tuning, evaluation and visualization. run-prompt-tuning writes domain-adapted prompts from a corpus sample (Domain adaptation); run-eval adds LLM-free coverage, retrieval and answer-match metrics to LangChain, RAGAS and assertion judges, with paired strategy comparisons, metered cost and decline statistics (Evaluation); run-visualization renders an exported graph (Visualization).
• Pluggable. Storage and model backends sit behind ports, and renderers, parsers, schema and seed sources and providers register from your own package through registries. A new search strategy or evaluator is an in-tree change (a fork or a contribution): strategies are keyed by the closed SearchStrategy enum (extension guide).

Architecture

Ingestion is a resumable 13-stage pipeline (parse, chunk, extract entities and relationships, resolve, detect communities with LLM-written reports, index, and for raptor build a summary tree) into the graph and search stores: Neptune and OpenSearch on AWS, embedded SQLite or containers in local mode.

Every strategy runs in one chain over the same indexes and token budget. Pick one with --search-strategy (CLI) or RAGInput.search_strategy (Python):

See Retrieval for per-strategy behavior and the Design Doc for the layer map, algorithms, data model and the detailed ingestion, incremental and retrieval diagrams.

Quickstart

Choose how to run

The AWS paths call Amazon Bedrock, so enable the required models first. Local mode is for development and evaluation only: the embedded stores serve one host and about 100,000 documents per index, the containers have no authentication or TLS, and small local models extract weaker graphs.

Prerequisites

Python 3.11–3.12 and uv (pip also works). Local mode needs Ollama (and Docker with Compose 2.23.1+ only for the stores in containers); the AWS paths need credentials with Bedrock access and, for existing resources, a Neptune cluster and an OpenSearch domain (the framework connects to services and never creates them); the CDK stack needs what iac/README.md lists.

Install and configure

git clone https://github.com/awslabs/unified-kg-rag-on-aws.git
cd unified-kg-rag-on-aws
uv sync --extra eval --extra viz        # or: pip install -e '.[eval,viz]'
cp config-template.yaml config.yaml     # then set your Bedrock region and service endpoints

OpenSearch authenticates with a username and password by default (aws.opensearch.use_iam: false): copy .env-template to .env in the directory you run the CLIs from and fill in the credentials. For a domain that authorizes IAM (SigV4) requests, set aws.opensearch.use_iam: true instead. uv sync alone installs ingestion and queries; run-eval's LangChain and RAGAS judges need the eval extra and run-visualization's interactive graph the viz extra (its static charts need none). Parsing Markdown and HTML needs the optional unstructured extra (uv sync --extra unstructured), which downloads a spaCy model (en_core_web_sm) from GitHub at the first such file; without network access, install it beforehand. The deployed image leaves the extra out; built with --build-arg UV_EXTRAS="--extra unstructured", it also installs the model at build time (iac/README.md). PDF, TXT, CSV, and JSON work out of the box.

Ingest, query, evaluate

uv run runs the CLIs in the project environment; with pip, activate the virtual environment instead and drop the uv run prefix.

# Index a corpus (incremental when the doc-status registry is on)
uv run run-ingestion --source-directory ./source --config-path config.yaml

# Query with either methodology, or chat with conversation memory
uv run run-rag --query "What are the main themes?" --search-strategy global --config-path config.yaml
uv run run-rag --query "How are Alice and Acme related?" --search-strategy mix --config-path config.yaml
uv run run-rag --interactive --use-memory --conversation-id my-session --config-path config.yaml

# Evaluate (RAGAS judge + graph-aware coverage, retrieval and answer-match metrics)
uv run run-eval --data-path eval_data.json --config-path config.yaml

# Optional: render the graph ingestion exported (it logs the file's path), or tune prompts to your domain
uv run run-visualization --data-path ./cache/<pipeline-id>/visualization/visualization_data.json --output-directory ./viz --config-path config.yaml
uv run run-prompt-tuning --source-directory ./source --output-path tuned_prompts.yaml --config-path config.yaml

The documentation hub has a guide per CLI (Evaluation covers the evaluation data format and the evaluators), the CLI Reference every flag, and the Configuration Reference every configuration key.

Deploy on AWS (optional)

The iac/ AWS CDK app provisions the whole stack: a VPC with endpoints, Neptune, OpenSearch, the DynamoDB document-status table, an S3 cache bucket, an ECS Fargate data plane, a Step Functions ingestion pipeline, CloudWatch dashboards and alarms, and an optional Bedrock Guardrail.

iac/README.md has the cdk synth, cdk bootstrap and cdk deploy --all commands and every -c key=value option. The stores are reachable only from inside the VPC, so the deployed Fargate tasks run the CLIs; After deploy has the commands to push the image, start an ingestion and run a query or an evaluation.

Cost and teardown. Neptune and OpenSearch bill hourly, and public network mode adds NAT gateways. The default dev environment tears down with cdk destroy --all; non-dev environments default to retaining stateful stores with deletion protection on. Review the hardening options (use_cmk, deletion_protection, Multi-AZ sizing, vpc_flow_logs) in iac/README.md before production use.

Documentation

Start at the documentation hub (한국어): reading paths by role, a page map and an "I want to" index.

Every flag is in the CLI Reference, every configuration key in the Configuration Reference, and the supported models in the Model Catalog. Release notes: CHANGELOG.md; security reports: SECURITY.md.

Security & Disclaimer

This project is a reference framework provided for educational and illustrative purposes. It is offered "AS IS" without warranty of any kind (see LICENSE). It should not be deployed to a production environment without your own additional security testing, threat modeling, and hardening.

• Run it in your own AWS account against your own resources; you are responsible for IAM policies, network configuration, data classification, and end-user authentication in your deployment.
• The optional CDK stack (iac/) provides secure defaults (private-VPC isolation, encryption at rest with AWS-managed keys or an optional customer-managed KMS key via use_cmk, enforced TLS, least-privilege IAM, an optional Bedrock Guardrail for PII and prompt-attack filtering), but you own the deployment and should review it for your environment.
• Enable the Bedrock Guardrail (aws.bedrock.guardrail) and apply rate limiting and monitoring appropriate to your use case before production use.
• To report a security issue, see SECURITY.md; please do not open a public issue.

Contributing

Contributions are welcome. See CONTRIBUTING.md for development setup, tests and the pull-request workflow, and Design Doc §15 for extension recipes; most extensions are a registry registration and need no dispatch-code edits.

License

This project is licensed under the Apache-2.0 License. See the LICENSE file for details. Maintained by AWS under the awslabs organization.

Acknowledgments

Thanks to Jihyeon Kang for significant contributions to the library's feature development and validation, and to Yusuke Tanimiya for a thorough review and real-corpus testing — both of which strengthened the framework ahead of release.

References

• Microsoft GraphRAG: From Local to Global: A Graph RAG Approach to Query-Focused Summarization · library
• LightRAG: Simple and Fast Retrieval-Augmented Generation · library
• HippoRAG 2: From RAG to Memory: Non-Parametric Continual Learning for Large Language Models · library
• RAPTOR: Recursive Abstractive Processing for Tree-Organized Retrieval · code

Further reading on GraphRAG (DRIFT search, dynamic community selection, auto-tuning, LazyGraphRAG) is listed in the Design Doc.