Neo4j의 공식 GraphRAG for Python 패키지는 Neo4j가 직접 제공하는 1st-party 패키지이며, 현재 neo4j-genai의 이름을 이어받은 후속 패키지입니다. 공식 문서는 neo4j-genai가 deprecated 되었고 더 이상 유지보수되지 않는다고 명시하며, 최신 설치 방법은 pip install neo4j-graphrag입니다. 또한 문서 기준으로 지원 버전은 Neo4j 5.18.1 이상, Neo4j Aura 5.18.0 이상, Python 3.10~3.14입니다.
GraphRAG가 왜 필요한가
기존 RAG는 대체로 “질문 → 임베딩 검색 → 관련 문서 조각 반환 → LLM 생성” 흐름으로 동작합니다. 이 방식은 단순하고 강력하지만, 문서 간 관계나 엔티티 간 연결이 중요한 질문에서는 맥락이 부족해지기 쉽습니다. Neo4j는 GraphRAG를 통해 지식 그래프의 구조를 검색에 활용하고, 더 정확하고 확장 가능한 GenAI 애플리케이션과 agentic system을 만들 수 있다고 설명합니다.
즉, GraphRAG의 핵심은 단순히 “비슷한 문단을 찾는 것”이 아니라, 문서 속 엔티티와 관계를 함께 활용해 답을 구성하는 것입니다. Neo4j GraphRAG 패키지는 바로 이 지점에서 지식 그래프 생성, 벡터 검색, 그래프 탐색, 자연어 기반 Cypher 변환을 묶어 제공합니다.
Neo4j GraphRAG Python 패키지의 정체
Neo4j GraphRAG Python 패키지는 “Neo4j를 GenAI 애플리케이션에 쉽게 통합하기 위한 포괄적인 Python 라이브러리”로 설명됩니다. 공식 개발자 가이드는 이 패키지가 비정형 텍스트에서 엔티티를 추출하고, 임베딩을 생성하고, Neo4j에 그래프를 만드는 파이프라인을 지원한다고 밝힙니다. 또한 graph search, vector search, vector database 연동을 위한 retriever들을 제공합니다.
공식 문서의 Quickstart는 GraphRAG 질의를 수행하기 위해 필요한 구성요소를 세 가지로 정리합니다. 첫째는 Neo4j driver, 둘째는 Retriever, 셋째는 LLM입니다. 그리고 이 세 가지를 결합해 GraphRAG 객체를 만들고 search()를 호출하는 구조를 제시합니다.
전체 구조를 한 장으로 이해하기
GraphRAG를 가장 단순하게 풀면 아래 흐름입니다.
- 사용자가 질문한다.
- 질문에 맞는 retriever가 Neo4j 그래프나 벡터 인덱스에서 관련 컨텍스트를 찾는다.
- LLM이 그 컨텍스트를 바탕으로 답변을 생성한다.
Neo4j 공식 문서의 Quickstart도 동일한 구조를 보여줍니다. driver로 Neo4j에 연결하고, embedder로 질문을 벡터화한 뒤, VectorRetriever로 검색하고, OpenAILLM 같은 LLM으로 최종 답변을 생성합니다.
이 구조의 장점은 검색 대상이 단순 텍스트 조각에만 머무르지 않는다는 점입니다. 지식 그래프를 함께 활용하면 엔티티 간 관계, 속성, 연결 경로까지 검색에 포함할 수 있어, 문맥이 긴 질문이나 구조화된 질문에 더 유리합니다. Neo4j의 개발자 가이드는 이런 점을 “knowledge graph creation”과 “graph search” 지원으로 설명합니다.
공식 문서 기준 설치와 실행 조건
최신 안정판 설치는 pip install neo4j-graphrag입니다. Neo4j 문서는 이 패키지가 Python 3.10 이상을 요구한다고 안내합니다. 지원되는 Neo4j 버전은 5.18.1 이상이며, Aura는 5.18.0 이상입니다.
실무에서는 가상환경 사용이 권장됩니다. 공식 문서도 “python packages for user space in a virtual environment” 사용을 권장합니다. 보통은 아래처럼 시작하면 됩니다.
python -m venv .venv
source .venv/bin/activate
pip install neo4j-graphrag neo4j환경 변수에는 최소한 Neo4j 접속 정보와 LLM API 키가 들어가야 합니다. Quickstart 예시에서도 OPENAI_API_KEY가 환경 변수에 있어야 한다고 설명합니다.
가장 기본이 되는 RAG 사용 흐름
Neo4j 공식 Quickstart는 GraphRAG를 구성하는 핵심 순서를 아주 명확하게 보여줍니다. 먼저 GraphDatabase.driver()로 Neo4j에 연결하고, OpenAIEmbeddings 같은 embedder를 준비한 뒤, VectorRetriever를 생성합니다. 그 다음 OpenAILLM을 만들고, 마지막으로 GraphRAG(retriever=retriever, llm=llm)로 묶어서 질문을 실행합니다.
아래 예시는 공식 Quickstart의 흐름을 블로그용으로 다시 정리한 것입니다.
from neo4j import GraphDatabase
from neo4j_graphrag.retrievers import VectorRetriever
from neo4j_graphrag.embeddings import OpenAIEmbeddings
from neo4j_graphrag.llm import OpenAILLM
from neo4j_graphrag.generation import GraphRAG
URI = "neo4j://localhost:7687"
AUTH = ("neo4j", "password")
INDEX_NAME = "index-name"
driver = GraphDatabase.driver(URI, auth=AUTH)
embedder = OpenAIEmbeddings(model="text-embedding-3-large")
retriever = VectorRetriever(driver, INDEX_NAME, embedder)
llm = OpenAILLM(model_name="gpt-5", model_params={"temperature": 0})
rag = GraphRAG(retriever=retriever, llm=llm)
response = rag.search(
query_text="Neo4j에서 유사도 검색은 어떻게 하나요?",
retriever_config={"top_k": 5},
)
print(response.answer)공식 문서상 GraphRAG.search()는 질문 텍스트와 retriever 설정을 받아 답변을 생성하며, Quickstart 예시에서는 top_k를 전달해 검색 결과 수를 조정합니다.
Neo4j GraphRAG에서 중요한 Retriever들
Neo4j 개발자 가이드는 이 패키지가 knowledge graph construction pipeline뿐 아니라 여러 retriever를 제공한다고 설명합니다. 그중 대표적으로 Neo4j Vector Retriever, Vector Cypher Retriever, Vector Database Retriever가 소개됩니다.
Vector Retriever
Vector Retriever는 전통적인 의미 기반 검색에 가장 가까운 방식입니다. 질문을 임베딩으로 변환하고, 벡터 인덱스에서 유사한 청크를 찾아 컨텍스트로 사용합니다. 공식 문서의 Quickstart가 바로 이 구조를 보여줍니다.
Vector Cypher Retriever
VectorCypherRetriever는 벡터 유사도 검색 뒤에 Cypher 기반 그래프 탐색을 더하는 방식입니다. 공식 문서와 GraphAcademy 설명에 따르면, 이 retriever는 의미적으로 가까운 노드를 먼저 찾은 다음, 그 결과를 바탕으로 그래프 구조를 따라 추가 컨텍스트를 얻습니다.
Text2Cypher Retriever
Text2CypherRetriever는 사용자의 자연어 질의를 Cypher 쿼리로 바꿔 Neo4j에서 직접 레코드를 조회합니다. 공식 문서 소스는 이 retriever가 LLM을 사용해 natural language query를 Cypher로 변환한 뒤 결과를 조회한다고 설명합니다. 또 neo4j_schema를 사용해 Cypher 생성을 돕는다고 적고 있습니다.
이 세 가지는 서로 경쟁 관계라기보다, 질문 유형에 따라 선택하는 도구에 가깝습니다. 의미 유사도가 중요하면 Vector Retriever, 관계 확장이 중요하면 Vector Cypher Retriever, 구조화된 그래프 질의가 필요하면 Text2Cypher Retriever가 어울립니다. 이 구분은 공식 문서가 제공하는 기능 설명을 바탕으로 한 실무적 해석입니다.
지식 그래프는 어떻게 만들어지나
Neo4j GraphRAG는 비정형 문서를 바로 RAG에 쓰는 것뿐 아니라, 먼저 지식 그래프를 구성하는 흐름을 제공합니다. 개발자 가이드는 entity extraction, embeddings 생성, graph 생성이 함께 이루어지는 pipeline을 강조합니다.
공식 문서에서는 SimpleKGPipeline을 “쉽게 시작할 수 있는 방법”으로 소개합니다. 예시에서는 ENTITIES와 RELATIONS를 명시해 어떤 엔티티와 관계를 추출할지 정의하고, 그 결과를 그래프에 저장하는 흐름을 보여줍니다.
예를 들어 의료 문서라면 Person, Company, Location 같은 엔티티와 WORKS_AT, LOCATED_AT, COMPETES_WITH 같은 관계를 미리 정의할 수 있습니다. 그러면 LLM이 텍스트를 읽으면서 해당 스키마에 맞는 지식 그래프를 구성하게 됩니다. 이 예시는 공식 문서에 나온 엔티티·관계 정의 방식을 블로그용으로 풀어쓴 것입니다.
어디에 쓰면 가장 효과적인가
GraphRAG는 문서 QA만을 위한 도구가 아닙니다. Neo4j는 이를 GenAI 애플리케이션 전반에 적용 가능한 라이브러리로 소개하며, 그래프 검색, 벡터 검색, 벡터 DB 연동까지 포함한 다양한 패턴을 제공합니다.
실무적으로는 다음과 같은 분야에서 특히 잘 맞습니다. 첫째, 내부 지식 검색입니다. 둘째, 고객 문의나 기술문서 기반 챗봇입니다. 셋째, 보안 분석처럼 엔티티와 관계가 중요한 영역입니다. 넷째, 코드 분석이나 의존성 추적처럼 연결성이 중요한 영역입니다. 이런 적용 방향은 Neo4j가 GraphRAG를 “more accurate, agile, and extensible GenAI apps and agentic systems”로 설명하는 맥락과 잘 맞습니다.
특히 보안 영역에서는 로그, 사용자, 호스트, 프로세스, 파일, IP 간 관계를 그래프로 만들면, 단일 이벤트가 아니라 사건의 흐름을 따라가기가 쉬워집니다. 이 부분은 공식 문서의 기능 설명을 기반으로 한 실무적 확장 해석입니다.
보안 관점에서 꼭 봐야 할 점
GraphRAG는 강력하지만, 운영 관점에서는 관리 포인트도 분명합니다. 우선 Text2CypherRetriever는 자연어를 Cypher로 변환하는 구조이므로, 허용 가능한 스키마와 질의 범위를 명확히 해야 합니다. 공식 문서가 이 retriever에 neo4j_schema와 예시 입력을 사용할 수 있다고 설명하는 만큼, 스키마 통제가 품질과 안전성 모두에 중요합니다.
둘째, 그래프에 민감정보를 넣을 때는 접근권한과 데이터 분리가 중요합니다. Neo4j 자체가 그래프 DB이기 때문에, 어떤 노드와 관계를 누가 볼 수 있는지, 어떤 속성이 노출되어도 되는지 먼저 정해두는 것이 좋습니다. 이 부분은 공식 문서의 기능 설명과 실제 운영 관행을 결합한 권고입니다.
셋째, retriever 선택이 곧 보안·정확도 정책이 됩니다. 벡터 검색만 쓰면 편하지만 관계형 증거가 약해질 수 있고, Text2Cypher를 너무 넓게 열어두면 질의 범위가 과도해질 수 있습니다. 따라서 질문 유형별로 retriever를 나누고, 결과를 검증하는 후처리 단계를 두는 구성이 적절합니다. 이 판단은 공식 retriever 설명을 근거로 한 운영 권장사항입니다.
운영 시 체크포인트
GraphRAG를 실제 서비스로 돌릴 때는 다음 네 가지를 먼저 점검하는 편이 좋습니다.
첫째, Neo4j 버전과 Python 버전이 공식 지원 범위에 있는지 확인합니다.
둘째, 그래프 스키마와 엔티티/관계 정의가 일관적인지 확인합니다.
셋째, retriever별 목적이 분리되어 있는지 확인합니다.
넷째, LLM과 embedding API 키, Neo4j 접속 정보가 안전하게 관리되는지 확인합니다.
이 네 가지가 정리되면, GraphRAG는 단순한 “RAG with graph”가 아니라 조직의 지식 구조를 검색 가능한 형태로 재구성하는 플랫폼이 됩니다. Neo4j의 공식 문서가 파이프라인, retriever, API 문서를 별도로 제공하는 이유도 이 구조를 실제 애플리케이션 수준으로 끌어올리기 위해서입니다.
한 번에 이해하는 핵심 요약
Neo4j GraphRAG Python은 공식 1st-party 패키지이며, neo4j-genai의 후속으로 자리 잡았습니다. 기본 설치는 pip install neo4j-graphrag이고, Neo4j 5.18.1+, Aura 5.18.0+, Python 3.10+ 환경이 권장됩니다.
이 패키지는 Neo4j driver, retriever, LLM을 묶어 GraphRAG 파이프라인을 구성하며, 벡터 검색, 그래프 탐색, 자연어→Cypher 변환, 지식 그래프 생성 파이프라인을 함께 제공합니다. 그래서 문서 검색보다 관계 중심의 질문, 구조화된 데이터 질의, 설명 가능성이 중요한 업무에 특히 잘 맞습니다.
댓글