LightRAG: 벡터 검색만으로 부족한 RAG를 지식 그래프로 보강하는 실전형 프레임워크

AI 애플리케이션을 만들다 보면 금방 한계가 보입니다.
문서를 청크로 쪼개고 임베딩해서 검색하는 전통적인 RAG는 “관련 문장 몇 개 찾기”에는 꽤 강하지만, 개념 간 관계, 엔티티 연결, 문서 전체를 관통하는 맥락을 묻는 순간 답변 품질이 흔들립니다.

LightRAG는 바로 그 지점을 노립니다.
이 프로젝트는 “그래프 기반 RAG는 좋은데 너무 무겁다”와 “벡터 기반 RAG는 가볍지만 얕다” 사이에서, 지식 그래프와 벡터 검색을 함께 쓰되 실제 서비스에 붙이기 쉬운 형태로 정리한 오픈소스입니다. 논문에서는 이를 dual-level retrieval이라고 설명하고, 저장소 구현은 여기에 서버, WebUI, 다양한 스토리지 백엔드, 멀티모달 확장까지 붙이면서 꽤 실전적인 플랫폼으로 발전시켰습니다. (arXiv)

 

LightRAG/CLAUDE.md at main · HKUDS/LightRAG

 

프로젝트 소개

LightRAG는 HKUDS 팀이 공개한 오픈소스 RAG 프레임워크입니다. 핵심 아이디어는 단순합니다. 문서를 청크로만 저장하지 않고, LLM으로부터 엔티티와 관계를 추출해 지식 그래프를 만들고, 동시에 청크·엔티티·관계에 대한 벡터 인덱스를 함께 유지합니다. 질의가 들어오면 질문에서 저수준 키워드와 고수준 키워드를 나누어 해석하고, 그래프와 벡터 검색을 조합해 답변 컨텍스트를 구성합니다. 이 접근은 논문에서 제안된 구조와 저장소의 실제 구현 설명이 일치합니다. (arXiv)

이 프로젝트는 단순 라이브러리로 끝나지 않습니다. 현재 저장소에는 다음이 함께 들어 있습니다.

• Python 기반 코어 엔진
• FastAPI 기반 서버
• React 19 + TypeScript 기반 WebUI
• Ollama 호환 인터페이스
• JSON, PostgreSQL, Neo4j, Milvus, MongoDB, Qdrant, OpenSearch 등 다양한 스토리지 백엔드
• RAGAS 기반 평가 도구
• 3D 그래프 뷰어
• 멀티모달 문서 처리를 위한 RAG-Anything 연동

즉, LightRAG는 “논문 구현체”라기보다 Graph-enhanced RAG를 서비스 단위로 운영하려는 팀을 위한 프레임워크에 가깝습니다. (GitHub)

기술 스택도 꽤 선명합니다. 코어는 Python, 서버는 FastAPI/Uvicorn/Gunicorn, UI는 React 19 + TypeScript + Bun/Vite입니다. 패키지 구성에서는 OpenAI, Anthropic, Ollama, Gemini, Bedrock, LlamaIndex 계열까지 연결할 수 있도록 설계되어 있고, 서버 실행용 CLI도 제공됩니다. (GitHub)

왜 이 프로젝트가 등장했을까

LightRAG를 이해하려면 먼저 기존 RAG의 불편함을 봐야 합니다.

전통적인 RAG는 보통 이런 흐름입니다.

1. 문서를 청크로 분리한다.
2. 청크를 임베딩한다.
3. 질문과 가까운 청크를 검색한다.
4. 그 청크를 LLM에 넣어 답변한다.

이 방식은 빠르고 단순하지만, 개발자가 곧바로 맞닥뜨리는 문제가 있습니다.

첫째, 문서가 관계를 잃습니다.
“이 인물과 저 사건이 왜 연결되는가”, “이 요구사항이 어느 설계 요소와 이어지는가” 같은 질문은 문장 단위 유사도만으로는 어렵습니다.

둘째, 질문의 해상도에 따라 검색 전략이 달라져야 합니다.
어떤 질문은 특정 엔티티 하나를 정확히 찾아야 하고, 어떤 질문은 여러 엔티티를 아우르는 상위 주제를 요약해야 합니다.

셋째, GraphRAG 계열은 좋아도 무겁습니다.
그래프 구축과 요약 파이프라인이 복잡해지면 운영 비용과 개발 복잡도가 같이 올라갑니다.

LightRAG 논문은 이런 문제를 배경으로, 그래프 구조를 도입하되 검색은 너무 무겁지 않게 유지하는 방법으로 dual-level retrieval과 graph-enhanced text indexing를 제안합니다. 저장소 구현도 그 철학을 따릅니다. 즉, “그래프를 쓰되 연구용 장난감이 아니라 개발자가 붙일 수 있게” 만든 쪽입니다. (arXiv)

핵심 기능

1) 엔티티·관계 추출 기반 지식 그래프 생성

LightRAG의 가장 큰 차별점은 문서를 넣으면 단순 청크 저장에서 끝나지 않고, 엔티티와 관계를 추출해 그래프로 축적한다는 점입니다. 이 그래프는 질의 시 “관련 노드”, “연결된 관계”, “주변 컨텍스트”를 찾는 기반이 됩니다. 저장소 설명에서도 GRAPH_STORAGE가 별도 계층으로 존재하며, NetworkX, Neo4j, PostgreSQL AGE, OpenSearch 등의 구현체를 선택할 수 있습니다. (GitHub)

2) 질의 모드가 명확하다

LightRAG는 질의 모드를 노출합니다.

• naive: 전통적인 기본 검색
• local: 질문과 가까운 구체적 맥락 중심
• global: 더 넓은 전역 지식 중심
• hybrid: local + global 조합
• mix: 지식 그래프와 벡터 검색을 함께 활용
• bypass: 검색 파이프라인을 우회하는 특수 모드

이게 중요한 이유는, 개발자가 “질문 성격에 따라 retrieval strategy를 바꾸는” 실험을 쉽게 할 수 있기 때문입니다. 단순한 FAQ라면 naive나 local로 충분할 수 있고, 리서치 보조나 복합 문서 QA라면 hybrid/mix가 더 자연스럽습니다. 특히 저장소에서는 reranker를 쓸 경우 mix 모드를 권장하고 있습니다. (GitHub)

3) 스토리지 백엔드가 꽤 유연하다

LightRAG는 저장을 한 군데에 몰아넣지 않습니다. KV, Vector, Graph, Document Status를 분리하고 각각 다른 구현체를 바꿔 끼울 수 있게 설계했습니다. 개발 초기에는 파일 기반 JSON/NetworkX/NanoVectorDB로 시작하고, 운영 환경에서는 PostgreSQL, Neo4j, Milvus, Qdrant, MongoDB, OpenSearch로 옮겨갈 수 있습니다. 최근 릴리스에서는 OpenSearch를 4개 스토리지를 모두 커버하는 통합 백엔드로 추가했습니다. (GitHub)

이 구조는 꽤 실용적입니다.
예를 들어 프로토타입 단계에서는 로컬 파일 기반으로 빠르게 시작하고, 서비스화 단계에서 그래프는 Neo4j, 벡터는 Milvus/Qdrant, 혹은 아예 OpenSearch 하나로 묶는 식의 전환이 가능합니다. 즉, LightRAG는 검색 전략뿐 아니라 운영 구조도 단계적으로 성장시키기 쉬운 편입니다. (GitHub)

4) 서버와 WebUI가 바로 붙어 있다

오픈소스 RAG 프로젝트의 흔한 문제는 “코어는 멋진데 서비스로 올리기 어렵다”는 점입니다. LightRAG는 이 부분을 꽤 신경 썼습니다. FastAPI 기반 서버가 있고, WebUI에서는 문서 인덱싱, 질의, 지식 그래프 탐색을 할 수 있습니다. 여기에 Ollama 호환 인터페이스까지 제공해서 Open WebUI 같은 도구에서 LightRAG를 하나의 모델처럼 연결하는 흐름도 노립니다. (GitHub)

5) 멀티모달 확장성이 있다

최근 저장소에는 RAG-Anything 연동이 추가되어 PDF, Office 문서, 이미지, 표, 수식 등 멀티모달 문서를 다루는 방향으로 확장되고 있습니다. 즉, LightRAG 자체는 텍스트/그래프 중심이지만, 현재 생태계는 “멀티모달 문서까지 포함한 지식 그래프형 RAG”로 커지고 있습니다. (GitHub)

6) 평가 도구와 운영 도구가 있다

단순히 질의만 하는 것이 아니라 RAGAS 기반 평가 프레임워크, LLM query cache 정리 도구, 3D 그래프 뷰어 등 운영 관점의 부가 도구도 들어 있습니다. 이런 부분은 실제로 팀이 “데모용”이 아니라 “운영 가능한 제품” 방향을 보고 있다는 신호입니다. (GitHub)

프로젝트 아키텍처 분석

저장소 구조를 보면 LightRAG의 중심은 lightrag.py와 operate.py입니다. lightrag.py는 전체 오케스트레이터이고, operate.py는 실제 문서 처리·엔티티 추출·질의 로직의 중심입니다. 여기에 base.py가 스토리지 추상화를 제공하고, kg/ 아래에 각 저장소 구현이 붙습니다. llm/ 아래에는 OpenAI, Ollama, Gemini, Bedrock 등 모델 바인딩이 모듈화되어 있습니다. api/는 서버, lightrag_webui/는 프론트엔드입니다. (GitHub)

이 구조를 개발자 관점에서 다시 그리면 아래와 같습니다.

조금 더 실무적으로 해석해보면 이렇습니다.

문서 입력 단계에서는
청크를 잘게 나누고, 각 청크에서 엔티티와 관계를 뽑고, 그 결과를 그래프와 벡터 인덱스 양쪽에 저장합니다. 그래서 이후 질의 시에는 “문장 비슷한 것 찾기”만 하는 것이 아니라 “질문과 관련된 엔티티/관계를 중심으로 주변 맥락을 조합”할 수 있습니다. (arXiv)

질의 단계에서는
질문에서 저수준/고수준 키워드를 분리하고, local/global/hybrid/mix 같은 모드를 통해 검색 전략을 바꿉니다. 그리고 최종적으로 모아진 컨텍스트를 LLM에 넘겨 답변을 생성합니다. 프롬프트 템플릿 파일에도 keyword extraction, entity summarization 같은 전용 프롬프트가 존재합니다. (GitHub)

여기서 중요한 포인트는 LightRAG가 “그래프 DB 질의 엔진” 그 자체는 아니라는 점입니다. 그래프는 retrieval quality를 높이기 위한 보조 구조에 가깝습니다. 실제 이슈에서도 maintainers는 현재 질의가 일반적인 의미의 재귀적 multi-hop graph traversal을 중심으로 설계된 것은 아니라고 설명했습니다. 즉, “그래프가 있으니 Cypher처럼 다단계 추론을 마음껏 할 수 있다”라고 기대하면 어긋날 수 있습니다. (GitHub)

개발자가 바로 이해할 수 있는 최소 사용 예제

저장소에서 가장 먼저 봐야 할 포인트는 초기화가 명시적이라는 점입니다. LightRAG 인스턴스를 만든 뒤 반드시 initialize_storages()를 호출해야 합니다. 이 부분을 빼먹으면 바로 오류를 만날 가능성이 높습니다. 또한 저장소는 코어를 직접 임베딩하기보다, 일반적인 프로젝트 통합에서는 서버 API 사용을 권장합니다. (GitHub)

아래는 저장소 예제를 실무적으로 읽기 쉽게 다듬은 형태입니다.

import os
import asyncio

from lightrag import LightRAG, QueryParam
from lightrag.llm.openai import gpt_4o_mini_complete, openai_embed

WORKING_DIR = "./rag_storage"

async def main():
    os.makedirs(WORKING_DIR, exist_ok=True)

    rag = LightRAG(
        working_dir=WORKING_DIR,
        embedding_func=openai_embed,
        llm_model_func=gpt_4o_mini_complete,
        graph_storage="NetworkXStorage",      # 로컬 테스트용
        vector_storage="NanoVectorDBStorage", # 로컬 테스트용
    )

    await rag.initialize_storages()

    await rag.ainsert("""
    LightRAG is a graph-enhanced RAG framework.
    It extracts entities and relationships from documents.
    It supports local, global, hybrid, and mix retrieval modes.
    """)

    answer = await rag.aquery(
        "Why is LightRAG different from naive RAG?",
        param=QueryParam(mode="hybrid")
    )

    print(answer)
    await rag.finalize_storages()

if __name__ == "__main__":
    asyncio.run(main())

이 예제에서 중요한 건 세 가지입니다.

1. 문서를 넣을 때 이미 그래프와 벡터 인덱스가 함께 만들어진다는 점
2. 질의할 때 retrieval mode를 바꿀 수 있다는 점
3. 로컬 파일 기반으로 시작한 뒤 운영형 스토리지로 옮기기 쉽다는 점입니다. (GitHub)

실전에서는 언제 쓰면 좋을까

LightRAG가 특히 잘 맞는 경우는 아래와 같습니다.

문서 사이 관계가 중요한 경우

예를 들어 기술 문서, 정책 문서, 제품 스펙, 규정집, 연구노트처럼 엔티티와 관계를 함께 이해해야 하는 도메인에서는 일반 RAG보다 장점이 큽니다. “어떤 기능이 어떤 제약과 연결되는가”, “이 컴포넌트가 어떤 장애 원인과 연관되는가” 같은 질문에 더 유리합니다. (arXiv)

단순 FAQ보다 복합 질의가 많은 경우

질문이 항상 “이 문장 어디 있어?” 수준이 아니라, 문서 전체의 구조적 이해를 요구한다면 local/global/hybrid 같은 모드가 도움이 됩니다. 특히 broad question과 specific question이 섞여 들어오는 내부 지식봇에서 잘 맞습니다. (GitHub)

프로토타입에서 운영까지 한 도구로 가고 싶은 경우

로컬 파일 기반으로 빠르게 검증하고, 이후 PostgreSQL/Neo4j/Milvus/OpenSearch 같은 운영형 백엔드로 이행하고 싶다면 LightRAG는 꽤 현실적인 선택지입니다. WebUI와 서버가 같이 있다는 점도 PoC 이후 확장에 유리합니다. (GitHub)

반대로, 이런 경우엔 과할 수 있다

모든 RAG에 그래프가 필요한 것은 아닙니다.

문서가 짧고, 질문이 단순하고, 정확히 “관련 청크 몇 개만 찾으면 되는” 시스템이라면 LightRAG는 다소 무거울 수 있습니다. 엔티티 추출과 관계 생성은 LLM 호출과 저장 비용을 늘리고, 파이프라인 복잡도도 높입니다. 실제 이슈를 보면 대용량 문서 처리에서 timeout이나 성능 튜닝 이슈를 겪는 사례도 있습니다. 즉, LightRAG는 단순함보다 품질과 구조적 검색을 택한 프레임워크입니다. (GitHub)

또 하나의 현실적인 포인트는, 현재 질의 엔진이 범용 그래프 추론기처럼 무제한 multi-hop traversal을 수행하는 방향은 아니라는 점입니다. 그래프를 “검색 품질 향상용 구조”로 이해하면 기대치가 맞습니다. (GitHub)

이 저장소를 읽고 느낀 핵심 인상

제가 이 프로젝트를 한 문장으로 요약하면 이렇습니다.

LightRAG는 GraphRAG의 아이디어를 더 실용적으로 축소·정리해서, 개발자가 실제 서비스에 얹을 수 있게 만든 프레임워크다.

좋았던 점은 다음입니다.

• retrieval mode가 명확해서 실험하기 쉽다
• 스토리지 분리가 잘 되어 있어 운영 전환이 수월하다
• 서버, UI, 도구, 평가 체계까지 같이 간다
• 최근 릴리스와 멀티모달 연동을 보면 단발성 프로젝트가 아니라 계속 진화 중이다

주의할 점도 분명합니다.

• 그래프 구축 비용이 있다
• 단순 FAQ에는 오버엔지니어링일 수 있다
• 성능, timeout, 스토리지 조합은 운영 전에 반드시 검증해야 한다
• 그래프가 있다고 해서 자동으로 깊은 그래프 추론이 되는 것은 아니다

그래도 “벡터 검색만으로는 아쉬운 RAG”를 만들고 있다면, LightRAG는 꽤 진지하게 검토할 가치가 있습니다. 특히 사내 지식 검색, 기술 문서 QA, 규정/정책 검색, 복합 문서 기반 코파일럿 같은 시나리오에서는 단순 RAG보다 더 설득력 있는 구조를 제공합니다. (arXiv)