Neptune GraphRAG Toolkit을 활용하여 정교한 비정형 데이터 검색하기

본 게시글은 AWS Database Blog에 게시된 ‘Introducing the GraphRAG Toolkit by Ian Robinson and Abdellah Ghassel’을 한국어 번역 및 편집하였습니다.

Amazon Neptune이 그래프 기반 검색 증강 생성(RAG, Retrieval-Augmented Generation) 워크플로를 누구나 더 쉽게 구축할 수 있도록, Neptune 기반의 오픈 소스 Python 라이브러리 GraphRAG Toolkit을 선보였습니다.

이 툴킷은 비정형 데이터에서 자동으로 벡터 임베딩이 포함된 그래프를 구축하고, 사용자의 질문에 답할 때 이 그래프를 활용해 구조적으로 관련된 정보를 검색할 수 있는 질의응답 전략 프레임워크를 제공합니다.

이 포스트에서 다루는 내용

이 글에서는 GraphRAG Toolkit을 바로 써볼 수 있도록 다음과 같은 두 가지를 중심으로 설명합니다.

그래프 도입의 이점 : 기존 RAG 애플리케이션에 그래프를 더했을 때 어떤 장점이 생기는지 살펴봅니다.
설치 및 환경 설정 : 빠르게 시작할 수 있는 환경 구성과 툴킷 설치 방법을 안내합니다.

왜 RAG 애플리케이션에 그래프를 추가해야 할까요?

먼저 실제와 비슷한 시나리오를 통해, 그래프가 없는 RAG와 그래프 기반 RAG의 차이를 직관적으로 살펴보겠습니다.

최근 수집된 다양한 뉴스 기사와 업계 보고서를 바탕으로, 지금 뜨겁게 주목받고 있는 Example 기업의 물류 상황과 잠재적인 위기 시나리오를 정리해 봅니다.

혁신적인 제품과 글로벌 공급망

미국 오스틴에 있는 Example 기업 연구소는 생성형 AI 기술을 이용해, 사용자와 대화할 수 있는 개인용 데스크톱 애완동물 위젯(Widget)을 개발했습니다.
이 혁신적인 기기는 현재 대만에서 생산되고 있으며, Example 기업은 전 세계 유통 채널 확장을 위해 국제 배송·보관 전문 업체인 AnyCompany 물류사와 전략적 파트너십을 체결했습니다.

영국 시장의 폭발적인 수요

아직 8월이지만, 영국에서는 이미 올해 크리스마스 인기 장난감 ‘톱 10’ 예측이 발표되었습니다.
업계 분석가들은 ‘위젯’에 대한 수요가 폭발할 것으로 보고 있습니다. 실제로 런던과 맨체스터 등 주요 도시 소매업체들은 이미 1,500만 달러 상당(100만 개 이상)의 물량을 선주문했습니다.
이 주문량은 크리스마스가 가까워질수록 계속 늘어날 것으로 예상됩니다.

물류 혁신: Fictitious 운하의 등장

AnyCompany 물류사는 물류 효율을 극대화하기 위해, 최근 개통된 Fictitious 운하를 모든 물류 경로에 적극 활용하겠다고 발표합니다.

배송 시간 단축 : 대만에서 영국까지의 배송 시간이 기존 2주에서 3일로 크게 단축됩니다.
비용 절감 : 많은 제조·유통 업체들이 항공 운송 대신 해상 운송으로 전환하면서, 이 운하는 향후 5년간 가장 붐비는 수로가 될 것으로 예상됩니다.

뜻밖의 재난: 산사태로 인한 공급망 마비

하지만 호재만 있는 것은 아닙니다.
Fictitious 운하 남쪽 유역에서 500만 톤이 넘는 암석이 산사태로 쏟아져 수역을 완전히 막아버렸다는 소식이 전해집니다.

현재 상황: 수많은 컨테이너선이 운하 안에 갇혀, 국제 공급망이 큰 혼란에 빠졌습니다.
영향: 유럽으로 향하는 선적이 최소 수개월 이상 지연될 가능성이 큽니다.

결론 : 영국 크리스마스 재고에 비상

결국 영국 소매업체들이 공들여 준비해 온 크리스마스 시즌 ‘위젯’ 재고 확보에 비상이 걸렸습니다.
수요는 폭발적으로 증가하는데, 물류 대란까지 겹치면서 올해 연말 유통 시장에 상당한 타격이 예상됩니다.

벡터 기반 RAG vs GraphRAG : 왜 답이 달라질까요?

여러분이 이 상황을 분석하는 연구원이라고 해봅시다.
가장 먼저 떠오르는 질문 중 하나는 아마도 “영국에서 Example 기업의 판매 전망은 어떤가?”일 것입니다.

벡터 기반 RAG에 물어본 경우

벡터 기반 RAG 애플리케이션에 이 질문을 던졌을 때, 다음과 같은 답을 얻었습니다.

“제공된 맥락을 바탕으로, 다가오는 크리스마스 시즌 동안 영국에서 Example 기업의 ‘위젯’ 제품에 대한 판매 전망은 매우 좋은 것으로 보입니다. 업계 애널리스트들은 위젯 대화형 데스크톱 애완동물에 대한 엄청난 수요를 예측했으며, 심지어 크리스마스 톱 10 장난감 중 하나로 선정했습니다. 런던과 맨체스터 같은 영국 주요 도시의 소매업체들은 이미 1,500만 달러 상당의 100만 개 이상의 주문을 했으며, 크리스마스가 다가올수록 주문 수량이 더욱 증가할 것으로 예상됩니다. 이러한 상황을 종합해 볼 때, Example 기업은 중요한 연말연시 쇼핑 기간 동안 영국 시장에서 매우 높은 판매량과 매출을 기대할 수 있을 것으로 보입니다.”

즉, 수요 관점의 정보만 반영된 “매우 낙관적인” 답변입니다.

GraphRAG 기반 애플리케이션에 물어본 경우

이번에는 GraphRAG Toolkit으로 구축한 애플리케이션에 같은 질문을 던져 보았습니다.

“검색 결과를 바탕으로, 영국에서 Example 기업의 위젯 대화형 데스크톱 애완동물에 대한 판매 전망은 초기에는 매우 밝아 보이지만, 향후 판매를 저해할 수 있는 잠재적인 공급망 문제가 존재합니다.

런던과 맨체스터 같은 영국 주요 도시의 소매업체들이 엄청난 수요를 예상하며 이미 위젯 제품 100만 개 이상을 주문했습니다. 업계 애널리스트들도 이 장난감에 대한 높은 수요를 예측하고 있습니다.

이러한 예상 수요를 충족하기 위해 Example 기업은 영국을 포함한 전 세계 유통 채널을 확장하기 위해 AnyCompany 물류사와 파트너십을 맺었습니다. AnyCompany 물류사는 새로 개통된 Fictitious 운하를 통해 배송을 경유함으로써 대만에서 영국까지의 배송 시간을 2주에서 단 3일로 크게 단축할 계획을 발표했습니다.

그러나 산사태로 인해 Fictitious 운하에 주요 막힘이 발생했다는 보고가 있으며, 500만 톤 이상의 암석이 남쪽 수역을 막아 컨테이너선들이 갇히고 있는 상황입니다. 이로 인해 국제 공급망이 차질을 빚고 영국을 포함한 유럽으로 향하는 상품의 배송이 수개월 지연될 가능성이 있습니다.

따라서 사전 주문과 예상 수요를 바탕으로 영국에서 Example 기업의 위젯 제품에 대한 초기 판매 전망은 매우 유망해 보이지만, Fictitious 운하 막힘으로 인한 공급망 문제가 신속하게 해결되지 않을 경우 향후 몇 달 동안 수요를 충족하는 데 차질이 생길 위험이 있습니다.”

이번 답변은 수요와 공급망 리스크를 함께 고려한, 훨씬 현실적인 전망을 제시합니다.

왜 이렇게 큰 차이가 나는 걸까요? 그래프가 주는 결정적 차이

핵심은 검색 방식의 차이입니다.

벡터 검색의 한계: “비슷한 말”만 잘 찾는다

벡터 검색은 질문과 의미적으로 유사하거나 언어적으로 비슷한 정보에 최적화되어 있습니다.
질문과 표현·의미가 많이 다른 정보는, 설령 구조적으로 매우 중요하더라도 검색되기 어렵습니다.

우리 예시에서,

“AnyCompany 물류사가 Fictitious 운하를 사용한다는 사실”과
“산사태로 운하가 막혀 있다는 소식”은

질문인 “영국에서 Example 기업의 판매 전망”과 텍스트적으로 크게 닮지 않았습니다.
그래서 벡터 검색만 사용하는 RAG에서는 이 중요한 정보들이 맥락에서 빠져버립니다.

하지만 실제로는, 이 정보가 있어야만 정확하고 완전한 답변을 만들 수 있습니다.

연관성 vs 유사성: 그래프가 보는 더 넓은 세계

여기서 중요한 개념이 ‘연관성’입니다.

질문과 관련된 모든 것은, 직접적이든 간접적이든 어떤 방식으로든 연결되어 있습니다.
의미적 유사성은 그 연결 방식 중 딱 하나일 뿐입니다.

사물이나 개념은 다음과 같은 다양한 방식으로 서로 연관될 수 있습니다.

시간적 인접성
공간적 인접성
인과관계
부모-자식 관계
부분-전체 관계
사회적, 조직적, 법적, 분류학적 관계 등

도메인에 따라 어떤 관계가 더 중요한지, 얼마나 강한지는 크게 달라집니다.
결국 “의미적으로 비슷하다”는 것은 RAG 검색 도구 상자 안에 있는 여러 도구 중 하나일 뿐입니다.

그래프로 모델링하면 생기는 일

우리가 다루는 영역을 그래프 모델로 표현하고, 그래프의 간선(relationship)을 통해 중요한 관계들을 연결해 두면, 다음과 같은 일이 가능해집니다.

질문과 직접적으로 비슷하진 않지만
정확하고 완전한 답을 위해 꼭 필요한 정보를
구조적인 연결을 따라 찾아올 수 있습니다.

그래서 GraphRAG는 단순히 “판매 전망이 밝다” 수준이 아니라, 공급망 리스크까지 고려한 입체적인 답변을 만들어낼 수 있습니다.

유사성 기반 검색은 여전히 중요하다

물론 유사성 기반 벡터 검색은 여전히 중요한 RAG 전략입니다.
질문과 의미적으로 가까운 문맥은 언제나 좋은 답변의 기본 토대를 제공합니다.

하지만 이 정도로는 부족한 경우가 많습니다.

비교가 필요할 때
논리적인 주장과 반론이 필요할 때
여러 출처를 아우르는 요약이 필요할 때

벡터 검색만으로는 도달하지 못하는, 더 풍부하고 차별화된 맥락이 필요해집니다.
그래프에 담긴 다양한 관계가, 바로 이 추가적인 관련 정보를 찾아오는 통로가 됩니다.

GraphRAG Toolkit 한눈에 보기

대부분의 RAG 애플리케이션은 크게 두 가지 축으로 구성됩니다.

인덱싱(Indexing) : 콘텐츠를 가공해 저장하는 단계
쿼리(Querying) : 질문에 답하기 위해 저장된 콘텐츠를 검색·활용하는 단계

GraphRAG Toolkit은 데이터를 그래프 스토어와 벡터 스토어에 인덱싱하고, 이 그래프에서 관련 콘텐츠를 검색하는 질의응답 솔루션까지 함께 구성할 수 있도록 도와주는 오픈 소스 Python 라이브러리입니다.

GraphRAG Toolkit 아키텍처

툴킷의 첫 번째 버전은 웹페이지, PDF, JSON 문서 등 비정형·반정형 텍스트 콘텐츠를 대상으로 그래프 기반 RAG 애플리케이션을 구축하는 데 초점을 맞추고 있습니다.
설치와 실행에 대한 자세한 내용은 다음에 나오는 GraphRAG Toolkit 설치 섹션에서 다룹니다.

인덱싱(Indexing) : 몇 줄의 코드로 그래프와 벡터 스토어 구축

콘텐츠 인덱싱은 단 몇 줄의 코드로 시작할 수 있습니다.

from graphrag_toolkit import LexicalGraphIndex
from graphrag_toolkit.storage import GraphStoreFactory
from graphrag_toolkit.storage import VectorStoreFactory

from llama_index.readers.web import SimpleWebPageReader

import nest_asyncio
nest_asyncio.apply()

doc_urls = [
    'https://docs.aws.amazon.com/neptune/latest/userguide/intro.html',
    'https://docs.aws.amazon.com/neptune-analytics/latest/userguide/what-is-neptune-analytics.html',
    'https://docs.aws.amazon.com/neptune-analytics/latest/userguide/neptune-analytics-features.html',
    'https://docs.aws.amazon.com/neptune-analytics/latest/userguide/neptune-analytics-vs-neptune-database.html'
]

docs = SimpleWebPageReader(
    html_to_text=True,
    metadata_fn=lambda url:{'url': url}
).load_data(doc_urls)

graph_store = GraphStoreFactory.for_graph_store(
    'neptune-db://my-graph.cluster-<your-cluster-id>.us-east-1.neptune.amazonaws.com'
)

vector_store = VectorStoreFactory.for_vector_store(
    'aoss://https://<your-cluster-id>.us-east-1.aoss.amazonaws.com'
)

graph_index = LexicalGraphIndex(
    graph_store, 
    vector_store
)

graph_index.extract_and_build(docs)

이 예시에서 사용된 LexicalGraphIndex는 콘텐츠를 인덱싱하는 핵심 진입점입니다.
연속 수집 방식으로 동작하기 때문에, 추출·구축 파이프라인이 돌아가는 동안에도 그래프에 데이터가 쌓이고 바로 쿼리할 수 있습니다.

또한 추출(extract) 단계와 구축(build) 단계를 분리해 실행할 수도 있습니다.
이 방식은 일회성 작업이거나, 동일한 추출 결과를 여러 그래프 버전으로 재구축하고 싶을 때 유용합니다.

LexicalGraphIndex는 내부적으로 그래프 스토어와 벡터 스토어를 함께 사용합니다.

예시에서는 그래프 저장소로 Neptune Database를,
벡터 저장소로 Amazon OpenSearch Serverless를 사용합니다.

현재 기준으로 툴킷은 다음을 지원합니다.

그래프 스토어 : Neptune Database, Amazon Neptune Analytics
벡터 스토어 : OpenSearch Serverless
임베딩 및 응답 생성용 파운데이션 모델(FM) : Amazon Bedrock

인덱싱 예시에서는 Neptune 문서 여러 페이지를 소스로 사용하고, LlamaIndex의 SimpleWebPageReader로 문서를 파싱해 인덱스로 로드합니다.
데이터 소스에 따라 SimpleDirectoryReader, JSONReader 등 다른 LlamaIndex 리더를 사용할 수도 있습니다.

쿼리(Querying) : 질문에 답하는 과정도 단순하게

쿼리, 즉 질문에 대한 답변 생성 과정도 인덱싱만큼 간단합니다.

from graphrag_toolkit import LexicalGraphQueryEngine
from graphrag_toolkit.storage import GraphStoreFactory
from graphrag_toolkit.storage import VectorStoreFactory

import nest_asyncio
nest_asyncio.apply()

graph_store = GraphStoreFactory.for_graph_store(
    'neptune-db://my-graph.cluster-<your-cluster-id>.us-east-1.neptune.amazonaws.com'
)

vector_store = VectorStoreFactory.for_vector_store(
    'aoss://https://<your-cluster-id>.us-east-1.aoss.amazonaws.com'
)

query_engine = LexicalGraphQueryEngine.for_traversal_based_search(
    graph_store, 
    vector_store
)

response = query_engine.query('''What are the differences between Neptune Database and Neptune Analytics?''') 
# 'Neptune Database와 Neptune Analytics의 차이점은 무엇인가요?'를 쿼리합니다.

print(response.response)

쿼리는 사실 두 단계로 이루어져 있습니다.

그래프·벡터 저장소에서 관련 정보 검색
검색된 정보를 대규모 언어 모델(LLM)에 전달해 최종 답변 생성

LexicalGraphQueryEngine은 이 두 단계를 한 번에 처리해 줍니다.

인덱싱 단계에서 이미 그래프 스토어와 벡터 스토어를 지정했지만, 인덱싱과 쿼리는 서로 다른 환경·머신·시간에 실행될 수 있는 별도 프로세스입니다.
그래서 쿼리 단계에서도 해당 저장소의 위치를 다시 지정해 줍니다.

GraphRAG Toolkit 설치: CloudFormation으로 빠르게 시작하기

GraphRAG Toolkit은 GitHub 리포지토리에서 제공하는 빠른 시작 AWS CloudFormation 템플릿으로 손쉽게 체험해 볼 수 있습니다.

이 템플릿은 다음 리소스를 한 번에 생성합니다.

Neptune Database 클러스터(Neptune 서버리스 인스턴스 1개)
OpenSearch Serverless 컬렉션(퍼블릭 엔드포인트)
예제 코드가 포함된 Amazon SageMaker AI 노트북 인스턴스
VPC, 프라이빗/퍼블릭 서브넷, 인터넷 게이트웨이 등 네트워킹 리소스

예제 노트북은 Amazon Bedrock의 FM을 사용해 콘텐츠를 추출·임베딩하고, 응답을 생성합니다.

사전 요구사항

템플릿을 실행하기 전에 Amazon Bedrock에서 사용할 FM에 대한 액세스 권한을 먼저 활성화해야 합니다. (지난해 말 Amazon Bedrock, FM 모델 자동 활성화로 액세스가 간소화되었습니다)
기본 설정된 모델은 다음과 같습니다.

anthropic.claude-3-7-sonnet-20250219-v1:0
cohere.embed-english-v3

CloudFormation 스택은 이 모델들이 제공되는 AWS 리전에서 실행해야 하며, 노트북을 사용하기 전에 모델 액세스 활성화를 완료해야 합니다.

CloudFormation 스택 파라미터

스택 생성 시에는 스택 이름과 함께 몇 가지 주요 파라미터를 조정할 수 있습니다.

ApplicationId: Neptune 클러스터, OpenSearch Serverless 컬렉션 등 배포 리소스 이름에 쓰일 고유 ID
IamPolicyArn: SageMaker 노트북에 연결할 추가 IAM 정책의 ARN으로, 특정 S3 버킷이나 추가 Bedrock 모델에 대한 권한을 부여할 때 사용

스택 생성이 완료되면, 스택 Outputs 탭의 NeptuneSagemakerNotebook 항목에서 노트북 인스턴스 링크를 확인하고, 바로 인덱싱과 쿼리를 실습할 수 있습니다.

노트북 실행 : 예제 인덱싱과 쿼리 체험

가장 먼저 실행해 볼 노트북은 01 — Combined-Extract-and-Build 입니다.

첫 번째 셀 : GitHub 리포지토리에서 GraphRAG Toolkit 설치 (배포당 1회 실행이면 충분)
두 번째 셀 : 예제 콘텐츠 인덱싱 실행

인덱싱 노트북 실행 화면

인덱싱이 끝나면 03 — Querying 노트북으로 이동해, 툴킷에 포함된 다양한 쿼리 전략을 직접 실험해 볼 수 있습니다.

쿼리 노트북 실행 화면

리소스 정리: 비용을 피하려면 스택 삭제 필수

배포된 리소스는 모두 계정에 비용을 발생시킵니다.
사용을 마쳤다면, CloudFormation 스택 삭제를 통해 리소스를 정리하는 것을 잊지 마세요.
(예시 기준: US East (N. Virginia) 리전에서 시간당 약 1.5달러 수준)

자체 애플리케이션에 GraphRAG Toolkit 도입하기

빠른 시작 템플릿을 사용하지 않고, 기존 환경에 GraphRAG Toolkit을 통합해서 사용할 수도 있습니다.

이 경우에는 다음이 필요합니다.

사전에 프로비저닝된 그래프·벡터 저장소 리소스
적절한 파운데이션 모델에 대한 액세스 권한

툴킷과 종속성은 pip로 설치할 수 있으며, 최신 버전은 GitHub 릴리스를 통해 제공됩니다.

프로젝트 문서에는 인덱싱 및 쿼리 프로세스를 구성·실행하는 다양한 예제가 포함되어 있고, 이를 참고해 자체 Python 애플리케이션에 맞게 코드를 변형할 수 있습니다.
노트북이 아닌 애플리케이션 진입점에서는 if __name__ == '__main__' 블록 안에 실행 로직을 넣어 구성하면 됩니다.

import os

from graphrag_toolkit import LexicalGraphIndex
from graphrag_toolkit.storage import GraphStoreFactory
from graphrag_toolkit.storage import VectorStoreFactory

from llama_index.readers.web import SimpleWebPageReader

import nest_asyncio
nest_asyncio.apply()

def run_extract_and_build():

    graph_store = GraphStoreFactory.for_graph_store(
        'neptune-db://my-graph.cluster-<your-cluster-id>.us-east-1.neptune.amazonaws.com'
    )
    
    vector_store = VectorStoreFactory.for_vector_store(
        'aoss://https://<your-cluster-id>.us-east-1.aoss.amazonaws.com'
    )

    graph_index = LexicalGraphIndex(
        graph_store, 
        vector_store
    )

    doc_urls = [
        'https://docs.aws.amazon.com/neptune/latest/userguide/intro.html',
        'https://docs.aws.amazon.com/neptune-analytics/latest/userguide/what-is-neptune-analytics.html',
        'https://docs.aws.amazon.com/neptune-analytics/latest/userguide/neptune-analytics-features.html',
        'https://docs.aws.amazon.com/neptune-analytics/latest/userguide/neptune-analytics-vs-neptune-database.html'
    ]

    docs = SimpleWebPageReader(
        html_to_text=True,
        metadata_fn=lambda url:{'url': url}
    ).load_data(doc_urls)

    graph_index.extract_and_build(docs, show_progress=True)

if __name__ == '__main__':
    run_extract_and_build()

마무리 : RAG에 그래프를 더하면 생기는 일

이 글에서는 GraphRAG Toolkit을 활용해 그래프 기반 RAG 애플리케이션을 어떻게 시작할 수 있는지 살펴봤습니다.

그래프를 RAG에 결합하면 예제에서와 같이 단순 유사성 검색을 넘어, 인과·시간·조직 등 다양한 관계를 따라 중요한 힌트를 함께 끌어와 공급망 리스크까지 반영된 답변을 만들 수 있습니다. 더구나 GraphRAG Toolkit은 웹·PDF·JSON 같은 비정형 텍스트를 읽어, Neptune(또는 Neptune Analytics)에 그래프를, OpenSearch Serverless에 벡터를 자동 인덱싱합니다. 또한 그래프 탐색과 벡터 검색, Bedrock 기반 LLM 응답 생성을 한 번에 처리하는 end‑to‑end RAG 파이프라인을 손쉽게 구성할 수 있습니다.
이 오픈 소스 Python 라이브러리는 그래프를 활용해 구조적으로 관련된 정보를 더 풍부하게 검색하고, 그 정보를 바탕으로 더 정확하고 입체적인 답변을 만드는 데 도움을 줍니다.

추가 학습 리소스

Neptune + Bedrock으로 GraphRAG/지식 그래프 활용하기 (AWS 기술 블로그 — 한국어) : https://aws.amazon.com/ko/blogs/tech/using-knowledge-graphs-to-build-graphrag-applications-with-amazon-bedrock-and-amazon-neptune/
Neptune GraphRAG Toolkit 신규 기능 및 BYOKG 개념 소개 : https://aws.amazon.com/ko/about-aws/whats-new/2025/08/amazon-neptune-supports-byokg-rag-toolkit/
Neptune Database 및 Neptune Analytics 사용자 가이드 : https://docs.aws.amazon.com/neptune/latest/userguide/intro.html 및 https://docs.aws.amazon.com/neptune-analytics/latest/userguide/what-is-neptune-analytics.html
GraphRAG Toolkit README와 lexical-graph/byokg-rag 에 대한 가이드(구성 옵션, 파라미터 튜닝 참고) : https://github.com/awslabs/graphrag-toolkit/tree/main/docs

다음 글에서는 데모 데이터를 기반으로 GraphRAG Toolkit을 활용한 인덱싱과 쿼리에 대한 좀 더 심화된 내용을 다룰 예정입니다. 인덱싱 단계는 비정형 텍스트에서 정보를 추출(extract) 한 뒤, 이 결과를 그래프(Neptune)와 벡터 스토어(OpenSearch Serverless)에 적재하는 빌드(build) 과정으로 구성되는 전체 파이프라인을 중심으로 설명합니다. 쿼리 단계에서는 여러 Retrieval 전략을 활용해 벡터 검색과 그래프 탐색을 병행하며, 상황에 따라 Vector, Graph Traversal, Hybrid 전략을 선택적으로 적용하는 방법을 살펴볼 예정입니다.

AWS 기술 블로그