검색·RAG안정

GraphRAG

문서를 지식 그래프와 커뮤니티 요약으로 바꿔 '전체를 관통하는 질문'에 답한다 — 그래프 RAG의 원형

직접 해보기 5빠른 시작

저장소 논문 공식 사이트

종류: 오픈소스
라이선스: MIT
언어: Python
사실 확인: 2026.10.24

pip install graphrag

TRY IT

직접 해보기

OVERVIEW

개요

무엇인가

GraphRAG는 Microsoft Research가 2024년에 공개한 그래프 기반 검색 증강 생성 파이프라인입니다. 문서를 청크 벡터로만 두지 않고, 언어 모델로 개체(사람·조직·제품)와 관계를 뽑아 지식 그래프를 만든 뒤, 밀접하게 연결된 개체 묶음(커뮤니티)마다 요약 보고서를 미리 써 둡니다.

기본 RAG는 질문과 가장 비슷한 청크 몇 개를 가져옵니다. 5,000개 청크에서 상위 5개면 전체의 0.1%입니다. "고객 불만 5,000건에서 반복되는 패턴은?" 같은 전체 조망 질문은 그 0.1%로 답할 수 없습니다. GraphRAG는 이 문제를 검색이 아니라 '질문 중심 요약(Query-Focused Summarization)'으로 보고, 커뮤니티 요약을 모아 답을 합성합니다.

2026년 저장소 README는 스스로를 "대부분 유지보수 모드"라고 적습니다. 새 PR과 새 기능은 받지 않고 버그 수정·의존성 갱신·CVE 대응만 합니다. 그래서 지금은 운영 플랫폼보다 방법론의 기준점으로 읽는 편이 맞습니다.

어떻게 동작하나

1. 텍스트 분할

문서를 600토큰 단위 TextUnit으로 나눈다. 논문에서 600토큰 청크는 2,400토큰 청크보다 개체를 거의 2배 많이 뽑았다.

2. 개체·관계 추출

청크마다 언어 모델이 개체와 관계를 뽑는다. 이어서 "빠뜨린 개체가 있나?"를 다시 묻는 글리닝으로 20~40%를 더 찾는다.

3. 그래프·커뮤니티

같은 이름의 개체를 한 노드로 합치고, Leiden 알고리즘으로 커뮤니티를 계층적으로 나눈다.

4. 커뮤니티 요약

커뮤니티마다 제목·핵심 요약·영향도·핵심 발견을 담은 보고서를 미리 생성한다. 질의 때 이 보고서가 핵심 재료가 된다.

질의는 네 가지 모드로 나뉩니다. 질문의 성격에 맞는 모드를 고르는 것이 비용과 품질을 함께 정합니다.

모드	무엇을 하나	맞는 질문	쿼리당 토큰(글 기준)
Basic	그래프 없이 벡터로 청크 검색 — 비교 기준선	"이 API의 인증 헤더 형식은?"	약 2,000~3,000
Local	질문 속 개체에서 출발해 이웃·관계·커뮤니티 보고서·원문을 모은다	"카모마일의 약효 성분은?"	약 11,500
Global	커뮤니티 보고서를 map-reduce로 종합한다	"이 문서들의 핵심 주제는?"	약 150,000 (동적 커뮤니티 선택 시 약 35,000)
DRIFT	커뮤니티 보고서로 초안과 후속 질문을 만들고 로컬 검색으로 파고든다	여러 개체 비교 + 넓은 맥락	Local과 Global 사이

2024년 말 추가된 동적 커뮤니티 선택은 값싼 모델로 보고서의 관련성을 먼저 매기고, 무관한 보고서와 그 하위 커뮤니티를 통째로 가지치기합니다. Microsoft는 Global 검색 비용이 평균 77% 줄고 품질은 통계적으로 같았다고 보고했습니다.

빠른 시작

공식 문서의 명령줄 빠른 시작 그대로입니다. 작은 텍스트 한 권으로 시작합니다.

bash

python -m pip install graphrag
graphrag init            # settings.yaml, .env, input/ 생성 — .env에 GRAPHRAG_API_KEY 입력
curl https://www.gutenberg.org/cache/epub/24022/pg24022.txt -o ./input/book.txt
graphrag index           # 결과는 ./output 에 parquet 파일로 쌓인다

graphrag query "What are the top themes in this story?"            # 기본값은 global
graphrag query "Who is Scrooge and what are his main relationships?" --method local

--method는 local·global·drift·basic 중 하나입니다. 새 도메인에 넣을 때는 graphrag prompt-tune으로 추출 프롬프트부터 데이터에 맞춥니다 — README가 강하게 권하는 단계이고, Microsoft의 자동 튜닝 실험에서 튜닝된 프롬프트는 기본 프롬프트보다 개체를 2.7배(4,896 대 1,796) 더 뽑았습니다. LLM 대신 NLP로 그래프를 짓는 --method fast 색인과, 새 문서만 반영하는 graphrag update도 있습니다.

언제 쓰고, 언제 피하나

ICLR 2026 GraphRAG-Bench는 그래프가 이기는 과제와 지는 과제를 갈라 보였습니다(소설 데이터셋, 과제별 최고 정확도).

과제	일반 RAG	GraphRAG 계열	판단
사실 검색	60.9%	52.9%	그래프가 오히려 노이즈
복잡 추론	42.9%	53.4%	여러 문서를 이어야 할 때
맥락 요약	51.3%	64.4%	흩어진 정보를 종합할 때
평균 프롬프트 토큰	879	331,375 (MS-GraphRAG 글로벌)	약 377배

잘 맞는다: 문서 사이의 관계를 추적하거나 코퍼스 전체의 패턴을 요약해야 하는 분석 — 공급망 리스크, 법률 문서 간 상충, 회의록의 의사결정 흐름, 고객 불만 패턴.
다른 방법을 먼저 본다: 질문 대부분이 단일 문서 사실 조회인 사내 Q&A, 지연이 짧아야 하는 챗봇, 매일 문서가 바뀌는 코퍼스. 실패 질의 중 관계·다중 홉 질문이 10% 미만이면 하이브리드 검색과 리랭킹으로 충분한 경우가 많습니다.

한계와 주의

색인이 비싸다. 모든 청크에 LLM 추출이 돌고 커뮤니티 요약이 그 위에 또 든다. README도 "비용이 큰 작업이니 작게 시작하라"고 경고한다. 문서 100건으로 색인 토큰과 시간을 먼저 재고 외삽한다.
엔티티 중복이 사슬을 끊는다. "울산시"와 "울산광역시"가 다른 노드가 되면 다중 홉 경로가 사라진다. 추출 품질이 곧 그래프 품질이다.
답이 없는 질문에 약하다. 글로벌 검색은 답할 수 없는 질문에서 정확도 13.95%였다 — 없는 패턴을 합성하는 경향이 있다.
유지보수 모드다. 신규 핵심 플랫폼으로 삼기보다 LightRAG, 임베딩 각도로 문서 그래프를 짓는 G³RAG, 질의 시점 SQL 조인(SAG) 같은 대안과 함께 비교한다.
블로그 글의 단어당 색인 비용(GPT-4o-mini 기준 100만 단어 약 $11 등)은 2025년 공식 비용 가이드 기준이다. 글에 나온 --estimate-cost 플래그는 2026-10 기준 CLI(3.3.0)에서 확인되지 않았다.

DEEP DIVE