FalkorDB/GraphRAG-SDK

GraphRAG‑SDK – 그래프 기반 검색 보강 생성 프레임워크

무엇인가요 – 문서(텍스트, PDF, 마크다운, CSV 등)의 컬렉션을 FalkorDB에 저장된 지식 그래프로 변환할 수 있는 Python SDK입니다. 자연어 질문에 대해 해당 그래프를 검색하고 탐색하여 답변을 생성합니다. 이 라이브러리는 검색 단계가 LLM보다 더 중요하다는 아이디어를 중심으로 설계되었으며, 그래프의 노드와 엣지에 기반하여 답변을 근거화함으로써 환각을 크게 줄일 수 있습니다.

왜 중요한가요 – 전통적인 RAG 파이프라인은 평면적인 벡터 유사도 검색에 의존하여 종종 다단계 사실을 놓치고 추적 가능성이 없습니다. GraphRAG‑SDK는 다음과 같은 기능을 추가합니다:

관계 탐색 – 텍스트적으로 유사하지 않아도 엔티티를 통해 연결된 사실을 발견할 수 있습니다.
출처 엣지 (MENTIONED_IN) – 모든 답변은 그 근거가 된 정확한 소스 청크로 거슬러 올라갈 수 있습니다.
거부 지원 – 그래프에 충분한 증거가 없을 경우, 라이브러리는 "증거 부족"이라고 명시적으로 응답하고 답변을 창작하지 않습니다.
벤치마크 최고 수준의 정확도 – README에 따르면 GraphRAG‑Bench에서 전체 정확도가 71.48 %이며, 표준 벡터 RAG 베이스라인을 능가합니다.

핵심 개념

개념	역할
그래프 스키마	선택적 `GraphSchema`를 통해 엔티티 유형(예: `Person`, `Organization`)과 관계 유형(예: `WORKS_AT`)을 선언할 수 있습니다. 스키마는 추출을 안내하고 타입화된, 검증 가능한 사실을 보장합니다.
인제스트	`rag.ingest(text, document_id)`는 LLM으로 엔티티/관계를 추출하고, 중복 제거, 임베딩 생성, FalkorDB에 노드/엣지를 업서트합니다.
최종화	`rag.finalize()`는 문서 간 중복 제거 및 누락된 임베딩을 보완합니다. 이 작업은 그래프 크기에 비례하므로 일괄 변경 후 한 번만 실행해야 합니다.
검색 + 생성	`rag.completion(question, return_context=True)`는 그래프 기반 검색(벡터, 전체 텍스트, 선택적 텍스트 → Cypher)을 수행한 후, 검색된 컨텍스트를 LLM에 전달하여 답변을 생성합니다.
인크리멘탈 업데이트	`update()`, `delete_document()`, `apply_changes()`를 통해 소스 리포지토리(예: CI 파이프라인)와 그래프를 동기화할 수 있으며, 처음부터 다시 빌드할 필요가 없습니다.

일반적인 워크플로우 (5분 데모)

설치 – pip install graphrag-sdk[litellm] (PDF 지원이 필요하면 [pdf] 추가). FalkorDB 컨테이너 실행 (docker run … falkordb/falkordb:latest).
GraphRAG 인스턴스 생성 – ConnectionConfig (호스트 + 그래프 이름으로 테넌트 격리)와 LLM/임베딩 제공자(라이브러리가 LiteLLM에 얇은 래퍼를 제공하므로 OpenAI 호환 모델은 모두 작동)를 제공합니다.
문서 인제스트 – 각 소스에 대해 ingest()를 호출합니다. LLM이 엔티티를 추출하고, 임베딩 생성기가 벡터를 생성하며, SDK는 Cypher 업서트를 작성합니다.
최종화 – 일괄 처리 후 finalize()를 한 번 실행하여 중복 제거 및 인덱싱을 수행합니다.
질의 – await rag.completion("Where does Alice work?")는 Answer 객체를 반환하며, answer.answer와 요청 시 전체 검색 트레일(ans.context)을 포함합니다.

설치 및 빠른 시작 스크립트

pip install graphrag-sdk[litellm]
# FalkorDB (Docker) 시작 및 OpenAI 키 설정
export OPENAI_API_KEY=sk-…

import asyncio
from graphrag_sdk import GraphRAG, ConnectionConfig, LiteLLM, LiteLLMEmbedder

async def main():
    async with GraphRAG(
        connection=ConnectionConfig(host="localhost", graph_name="demo"),
        llm=LiteLLM(model="openai/gpt-4o-mini"),
        embedder=LiteLLMEmbedder(model="openai/text-embedding-3-large", dimensions=256),
    ) as rag:
        await rag.ingest(text="Alice Johnson works at Acme Corp in London.", document_id="doc1")
        await rag.finalize()
        ans = await rag.completion("Where does Alice work?", return_context=True)
        print(ans.answer)
        print(ans.context)   # 출처 엣지, 소스 청크 등

asyncio.run(main())

주요 기능 (README에 기재)

벤치마크 최고 수준의 정확도 (작성 시점 기준 GraphRAG‑Bench에서 1위).
그래프 기반 검색과 출처 엣지로 인한 환각 감소.
빠르고 다중 테넌트 – 각 그래프는 이름으로 격리되며, FalkorDB는 밀리초 미만의 Cypher 쿼리를 제공합니다.
모듈식 파이프라인 – 커스텀 인제스트 전략, LLM 제공자, 임베딩 백엔드를 자유롭게 교체 가능.
인크리멘탈 업데이트 – 안전하고 동일성 보장된 update(); 크래시 복구 메커니즘; CI용 배치 처리.
확장 가능한 스키마 – 온톨로지 선언 또는 진화 가능; SDK는 들어오는 문서에서 새로운 유형을 탐지할 수 있음.
관측성 훅 – 2026년 Q2 출시 예정. 프로덕션 수준의 메트릭스 추가 예정.

누가 사용해야 할까

기업 – 법무, 의료, 금융 등 환각이 허용되지 않는 신뢰성 있고 감사 가능한 RAG 답변이 필요한 분야.
개발자 – 챗봇, Q&A 어시스턴트, 내부 지식 기반을 구축하는 사람으로, 다단계 사실, 엔티티 중심 쿼리가 필요한 사람.
연구자 – 그래프 기반 RAG와 순수 벡터 RAG의 비교에 관심 있는 사람. SDK에는 벤치마크 스크립트와 재현성 문서 포함.

더 배우기

전체 문서: https://docs.falkordb.com/graphrag
시작 가이드, 아키텍처 개요, 신뢰성/근거 문서 (모두 README에서 링크됨).
예제 갤러리 (graphrag_sdk/examples/…)는 빠른 시작, PDF 인제스트, 커스텀 전략, 온톨로지 진화, "근거 있는 답변과 거부" 패턴을 다룹니다.

커뮤니티 및 기여

Apache 2.0 라이선스로 오픈소스.
지원 및 기능 요청을 위한 활성 Discord, GitHub Discussions, 이슈 트래커.
기여 가이드와 코드 오브 콘덕트 제공.

결론 – GraphRAG‑SDK는 FalkorDB의 그래프 엔진과 LLM 기반 엔티티 추출을 결합한 프로덕션 준비 완료된 Python 중심 프레임워크로, 단순 벡터 검색 파이프라인보다 정확도가 높고, 추적 가능하며, 제어 가능한 RAG 시스템을 제공합니다.

FalkorDB/GraphRAG-SDK

GraphRAG‑SDK – 그래프 기반 검색 보강 생성 프레임워크

관련