LLM Knowledge Graph Builder 백엔드 아키텍처 및 API 개요

소개

여러분은 문서, 이메일, 소셜 게시물 등 엄청난 양의 데이터에 둘러싸여 있죠. 이 모든 것을 이해하는 게 정말 큰 도전 과제 같아요. 의미 있는 연결을 찾기 위해 데이터를 선별하는 건 늘 어려운 일이었으니까요.

여기 Neo4j LLM Knowledge Graph Builder가 등장합니다! 이 도구는 Large Language Model(LLM)의 강력한 기능과 Graph Database를 결합해서, 복잡하고 구조화되지 않은 데이터를 명확하고 연결된 Knowledge Graph로 바꿔줘요. PDF, 웹 페이지 등 어떤 파일이든 업로드하기만 하면, GraphRAG를 사용해서 탐색하고, Query하고, 심지어 채팅까지 할 수 있는 Knowledge Graph가 만들어지는 거죠. 데이터에 두뇌를 심어주는 것과 같아요! 프로세스에 대한 간략한 개요를 확인하고 자세히 알아보기.

이 포스팅은 Neo4j LLM Knowledge Graph Builder의 다양한 측면을 다루는 시리즈의 일부랍니다.

Knowledge Graph 추출
프론트엔드 아키텍처 및 통합
백엔드 아키텍처 및 API 개요(현재)
GraphRAG 리트리버

이번 포스팅에서는 백엔드 아키텍처를 자세히 살펴보고, API 설계 및 구현에 대한 포괄적인 개요를 제공할 예정이에요.

아키텍처 개요

백엔드는 GenAI 및 문서 로더(예: YouTube Loader, GCSFileLoader, UnstructuredLoader, PyMuPDFLoader)용 LangChain과의 통합을 특징으로 하는 FastAPI 프레임워크를 사용하여 Python을 기반으로 구축되었어요. 이 API는 콘텐츠를 추출하고 그래프를 생성하기 위해 다양한 소스에서 문서를 로드, 처리 및 상호 작용하기 위한 확장 가능하고 효율적인 솔루션을 제공하죠. 이 오픈 소스 프로젝트는 GitHub(LLMGraphBuilder)에서 확인할 수 있어요. 백엔드 API 사양 문서도 한번 확인해 보세요.

백엔드 아키텍처

API의 목적

이러한 API의 주요 목표는 다양한 문서 소스에서 콘텐츠를 가져와 LangChain의 LLM Graph Transformer를 사용해서 처리하는 거예요. 이렇게 처리된 데이터는 GraphRAG 검색기로 구동되는 AI 기반 대화 인터페이스를 위해 Neo4j 데이터베이스에 저장할 그래프 문서 형식의 엔터티와 관계를 추출하는 데 사용되죠. 이 솔루션은 정보 검색 및 콘텐츠 요약과 같은 시나리오에 특히 유용해요.

아키텍처 세부정보

백엔드는 라우팅 및 요청 처리를 위해 FastAPI를 활용해서 빠른 응답 시간과 손쉬운 확장성을 보장해요. 다음 구성 요소/라이브러리는 시스템의 핵심이라고 할 수 있죠.

LangChain 통합: GenAI와의 상호작용을 처리해서 로드된 문서를 기반으로 자연어 응답을 가능하게 해요.
: 다음을 포함한 다양한 소스의 데이터 수집을 지원해요.
– Google Cloud Storage(GCS) 파일 로더: 다양한 파일 형식(예: PDF, Word, 텍스트)을 지원해서 GCS에서 문서를 읽어와요.
– PyMuPDF 로더: PDF 문서의 데이터 추출에 사용돼요.
– Unstructured 파일 로더: 다양한 유형의 파일 데이터를 로드하고 추출하는데, 현재 텍스트 파일, PowerPoint, HTML, PDF, 이미지 등의 로딩을 지원해요.
– YouTube 로더: YouTube 비디오를 텍스트로 변환해서 LangChain을 통해 검색 가능하게 만들어줘요.
– Wikipedia 로더: wikipedia.org의 위키 페이지를 문서 형식으로 로드해요.
– S3 디렉터리 로더: S3 디렉터리 객체에서 문서 객체를 로드하죠.
– 웹 기반 로더: HTML 웹페이지의 텍스트를 문서 형식으로 로드해요.
: Vector Embedding은 텍스트 콘텐츠의 관련성을 측정하는 데 사용돼요. 이걸 사용하면 텍스트 분석 및 유사성 비교와 같은 작업에 도움이 될 수 있죠. 예를 들어 "cat"과 "kitty"와 같은 단어는 유사한 의미를 가지는데, Vector Embedding은 이러한 의미적 유사성을 포착할 수 있어요. 저희는 애플리케이션에서 세 가지 유형의 임베딩을 지원하고 있어요.
– 문장 Transformer 임베딩: LangChain을 이용한 Hugging Face 임베딩 모델을 사용해요. 모델 "all-MiniLM-L6-v2"는 텍스트를 384차원 밀집 벡터 공간에 매핑하죠.
– OpenAI 임베딩: 모델 "text-embedding-ada-002"는 텍스트를 1536차원 밀집 벡터 공간에 매핑해요.
– Vertex AI 임베딩: 모델 "textembedding-gecko@003"은 텍스트를 768차원 밀도 벡터 공간에 매핑합니다.
Neo4j 그래프: 이 LangChain 유틸리티는 Neo4j 데이터베이스에 대한 연결을 처리해서 그래프 데이터를 검색 및 저장하고, 그래프 스키마를 제공하고, 다양한 Index 유형과 상호 작용해요.
Neo4j 벡터: Neo4j에 저장된 벡터 Index를 사용하는 검색기를 생성할 수 있어요. 이 검색기는 특정 문서 이름으로 필터링하고 점수 임계값을 설정하는 옵션을 사용해서 유사성 점수를 기반으로 문서를 검색하도록 구성할 수 있죠. 그런 다음 벡터 검색은 GraphRAG 벡터 Index의 문서부터 시작해서 Knowledge Graph에서 추가 문맥 정보를 가져오는 검색 쿼리에요.

API 설계 원칙

: LangChain 프레임워크를 사용하면 API가 최소한의 구성으로 다양한 LLM 모델, 데이터 로더 및 챗봇 검색 메커니즘에 적응할 수 있어요.
: FastAPI는 여러 문서 업로드 및 쿼리를 동시에 처리할 수 있도록 확장에 대한 비동기 지원을 제공해요.
: Pydantic 모델을 활용해서 요청 및 응답 데이터를 검증하죠.
HTTP 상태 코드: 성공, 오류 또는 리디렉션을 나타내는 적절한 HTTP 상태 코드를 반환해요.
: 백엔드는 사용자 상태를 유지하거나 처리하기 위한 것이 아니에요. 그건 모두 프런트 엔드에서 관리되죠. 연결 세부 정보와 사용자 컨텍스트는 모든 요청과 함께 전달되므로 원활한 확장이 가능해요. GCP Cloud Run에서는 이는 설계에 따라 시행되는데, 즉 인스턴스는 임시적이고 자동으로 확장될 수 있으므로 모든 영구 상태는 외부(예: Cloud Storage, Firestore)에 저장해야 해요.
개방형 API 및 문서: FastAPI는 다음 위치에서 Swagger 및 Redoc 문서를 자동으로 생성해줘요.
– /문서(스웨거 UI)
– /재독(UI 재작성)

API 예제 연습

Neo4j 데이터베이스에 API를 연결해볼게요.

curl -X 'POST' 
  'https://dev-backend-967196130891.us-central1.run.app/connect' 
  -H 'accept: application/json' 
  -H 'Content-Type: application/x-www-form-urlencoded' 
  -d 'uri=neo4j%2Ds%3A%2F%2Fdemo.neo4jlabs.com&userName=test&password=token&database=test1&email=abc%40gmail.com'

응답:

{
  "status": "Success",
  "data": {
    "db_vector_dimension": 384,
    "application_dimension": 384,
    "message": "Connection Successful",
    "gds_status": true,
    "write_access": true,
    "elapsed_api_time": "1.41",
    "gcs_file_cache": "True"
  }
}

API 엔드포인트 세부정보

문서 업로드, 콘텐츠 추출, 데이터베이스 저장, 챗봇 콘텐츠 쿼리, 처리된 데이터 검색을 위한 엔드포인트를 통해 각 기능에 대한 구조화된 액세스를 제공해요.

모든 API는 다섯 가지 범주로 분류할 수 있어요.

각 주요 API 엔드포인트에 대한 자세한 사양은 다음과 같아요.

하부 구조

/connect(인프라)

Neo4j 데이터베이스 자격 증명을 사용하여 프런트 엔드를 백엔드에 인증하고 연결해요. 이 API의 응답을 기반으로 프런트 엔드 UI는 연결 상태와 Graph Data Science 또는 AuraDB와 같은 데이터베이스 유형 아이콘을 표시하죠. 또한 데이터베이스의 기존 `Vector Embedding` 차원 및 애플리케이션에서 지원하는 `Vector Embedding` 차원에 대한 응답을 확인하고 반환해요. 기존 데이터베이스의 `Vector Embedding` 차원이 다른 경우 연결 모달 팝업에 경고가 표시될 거예요.

/backend_connection_configuration(인프라)

백엔드 환경 구성을 기반으로 Neo4j 데이터베이스에 대한 연결 객체를 생성하고 UI에서 로그인 대화 상자를 표시/숨기기 위한 상태를 반환해요 (예: env가 구성된 경우 로그인 팝업을 통해 자격 증명을 전달할 필요가 없어요).

/drop_and_create_Vector_index(인프라)

기존 `Vector` `Index` 크기가 필수 크기와 다른 경우 `Vector` `Index`를 삭제하고 생성해요.

/schema(인프라)

기존 Neo4j 데이터베이스 데이터에서 `Label`과 `Relationship`을 가져와요. 사용자는 설정 패널에서 그래프 생성을 위한 `Schema`(예: `Node` 및 `Relationship` `Label`)를 설정할 수 있어요.

/delete_document_and_entities(인프라)

여러 파일의 `Node`와 `Relationship`을 삭제해요. 사용자는 삭제할 여러 문서를 선택할 수 있으며 문서와 청크 `Node`만 삭제하도록 선택하여 해당 문서에서 추출된 엔터티를 유지할 수 있어요.

문서 처리

/upload(문서 처리)

대용량 파일을 작은 청크로 나누어 업로드를 처리해요. 이 방법을 사용하면 서버에 과부하를 주지 않고 대용량 파일을 효율적으로 업로드할 수 있죠.

/url/scan(문서 처리)

S3 버킷, GCS 버킷, Wikipedia, 웹 페이지, YouTube 비디오 및 로컬 파일을 포함하여 지원되는 모든 소스에 대한 문서 소스 `Node`를 생성해요. 지원되는 콘텐츠 소스는 다음과 같아요:

S3 버킷— 사용자는 버킷 URL과 폴더 내의 모든 PDF 파일을 전달해요. 하위 폴더가 나열될 거예요.
GCS 버킷— 사용자는 GCS 프로젝트 ID, GCS 버킷, 폴더 이름을 전달한 다음 해당 폴더 및 하위 폴더 아래의 모든 PDF에 액세스하도록 인증해요. 사용자가 폴더 이름을 전달하지 않은 경우 사용자에게 버킷 읽기 액세스 권한이 있으면 버킷 및 해당 하위 폴더 아래의 모든 PDF가 나열될 거예요.
위키피디아— URL의 텍스트 콘텐츠가 처리돼요. URL은 사용자에 의해 전달되죠.
웹 URL— 모든 웹 URL의 텍스트 콘텐츠가 처리돼요.
동영상 스크립트 — YouTube 동영상의 텍스트 스크립트를 처리해요.

/extract(문서 처리)

이전에 업로드된 소스 콘텐츠에서 `Node`와 `Relationship`을 추출해요. 이 기능의 단계는 다음과 같아요:

Read 각 LangChain 로더에서 LangChain 문서 객체 형태로 제공되는 소스의 내용이에요.
문서를 여러 청크로 나누고 `Relationship`을 만들어요.
– PART_OF— 문서 `Node`에서 모든 청크 `Node`로
– FIRST_CHUNK— 문서 `Node`에서 첫 번째 청크 `Node`까지
– NEXT_CHUNK— 문서의 다음 청크를 가리키는 청크에서
– HAS_ENTITY— `LLM`에서 추출된 청크 `Node`와 엔터티 사이
청크 `Embedding` 계산 및 저장 `Vector` `Index`를 생성해요.
`Node` 및 `Relationship` 추출 LangChain `LLM` Graph Transformer를 사용하여 해당 `LLM`의 그래프 문서 형식이에요.
라이브러리는 `LLM`에서 그래프 문서 형식으로 `Node`와 `Relationship`을 가져오는 데 사용돼요. 사용자 및 시스템 `Prompt`, `LLM` 체인, 그래프 문서 `Schema`는 라이브러리 자체에서 정의되죠.
업로드된 파일 삭제 추출 후 GCS에서 또는 실패한 경우 추가 조사를 위해 다른 GCS 버킷에 복사해요.
그래프 구조를 개선하고 고급 검색 기능을 활성화하며 커뮤니티 감지를 통합하여 향상된 통찰력을 제공해요. 후처리 API는 다양한 작업을 통합하여 `Knowledge Graph`가 강화되고 최적화되며 다운스트림 애플리케이션에 사용할 수 있도록 준비되도록 도와주죠.

/chunk 엔터티(문서 처리)

검색 모드(예: 벡터 및 벡터 + 전체 텍스트)를 기반으로 특정 chunk 및 chunk 메타데이터와 연관된 항목 및 관계를 가져와요.

/sources_list(문서 처리)

Neo4j Graph Database의 모든 소스(문서 Node) 목록을 가져와요.

/post_processing(문서 처리)

모든 문서 처리가 끝나면 생성돼요. k- 기본적으로 0.8인 KNN_MIN_SCORE를 기반으로 하는 유사한 문서 chunk 간의 최근접 이웃 관계는 계층적 커뮤니티 클러스터를 계산하고, LLM을 사용하여 커뮤니티 요약을 생성하고, 검색기, Neo4j Bloom 및 기타 다운스트림 애플리케이션이 이를 활용할 수 있도록 데이터베이스의 모든 Label에 대한 전체 텍스트 Index를 다시 생성해요.

후처리(Post-processing)의 일부로 다음 작업이 수행돼요.

텍스트 chunk 유사성 구체화
Neo4j Bloom에서 하이브리드 검색 및 전체 텍스트 검색 활성화
엔터티 유사성 구체화
그래프 스키마 통합

후처리에 대한 자세한 정보는 에서 확인할 수 있어요.

/update_extract_status(문서 처리)

지정된 파일의 추출 상태에 대한 지속적인 업데이트를 제공해요. 서버에서 보낸 이벤트를 사용하여 클라이언트에 업데이트를 스트리밍하죠.

/canceled_job(문서 처리)

처리 작업을 취소해요.

/retry_processing(문서 처리)

취소, 완료 또는 실패한 파일 소스를 다시 처리해요. 사용자에게는 파일 재처리에 대한 세 가지 옵션이 있어요.

— 파일은 처음부터(즉, 첫 번째 chunk를 다시) 처리돼요.
엔터티를 삭제하고 처음부터 시작— 파일 소스가 이미 처리되었고 기존 Node와 Relationship이 있는 경우 해당 항목이 삭제되고 파일은 첫 번째 chunk부터 다시 처리돼요.
마지막으로 처리된 위치부터 시작— 취소되거나 실패한 파일은 마지막으로 성공적으로 처리된 chunk 위치부터 처리돼요. 완료된 파일에는 이 옵션을 사용할 수 없어요.

상태가 재처리로 설정되면 사용자는 Knowledge Graph 생성을 위해 파일을 다시 클릭하여 처리할 수 있어요.

/get_neighbours(시각화)

특정 Node의 세부 정보를 그래프로 시각화하기 위해 Node의 요소 ID를 기반으로 주변 Node 및 Relationship을 가져와요. 챗봇 결과, 후처리 테이블 등의 상세보기에 사용되죠.

/graph_query(시각화)

특정 문서 또는 여러 문서 목록에 대한 그래프를 시각화해요. 그래프 시각화에 표시하기 위해 문서, chunk, 엔터티, Relationship 및 커뮤니티를 프런트 엔드로 반환하죠.

그래프 개선

/populate_graph_schema(그래프 향상)

제공된 입력 텍스트, 모델 및 스키마 설명 플래그를 기반으로 그래프 스키마를 채워요. LLM을 사용하여 Node Label 및 Relationship 유형에 대한 제안을 제공하고 제공된 텍스트를 (다소 공식적인) 스키마 설명 또는 엔터티 유형을 추론해야 하는 실제 산문 텍스트로 처리할 수 있어요.

/get_unconnected_nodes_list(그래프 향상)

다른 엔터티 Node에 연결되지 않고 추출된 chunk에만 연결되어 있는 Graph Database의 Node 목록을 검색해요.

/delete_unconnected_nodes(그래프 향상)

사용자가 입력한 내용을 사용하여 Neo4j 데이터베이스에서 연결되지 않은 항목을 삭제해요.

/get_duplicate_nodes_list(그래프 향상)

Neo4j 데이터베이스에서 중복 엔터티를 가져와요. 특정 Label(예: chunk, 세션, 문서)을 제외하고 임베딩 및 ID가 있는 Node를 일치시키는 Cypher Query를 사용하죠.

Query는 정의된 임계값(DUPLICATE_SCORE_VALUE)을 초과하는 임베딩의 코사인 유사성, 텍스트 하위 문자열 포함 또는 특정 제한(DUPLICATE_TEXT_DISTANCE) 미만의 텍스트 편집 거리를 포함한 다양한 조건을 기반으로 중복을 결정해요.

이 방법은 동일한 그룹 내의 Node를 비교하여 중복된 하위 집합이 제거되도록 보장해요. 이 메서드는 Query를 실행하고 총 중복 수와 함께 중복 Node 목록을 반환해요..

/merge_duplicate_nodes(그래프 향상)

사용자가 선택한 Neo4j 데이터베이스의 중복된 엔터티를 병합해요. 관계는 결과 엔터티로 전송된답니다.

채팅 경험

/chat_bot(채팅 경험)

여러 AI 모델과 Neo4j Graph Database를 활용해서 사용자 쿼리에 대한 답변을 제공하도록 설계된 챗봇 시스템이에요.

OpenAI, Google의 Vertex AI 등의 AI 모델과 상호 작용하고, 임베딩 모델을 사용해서 관련 정보 검색을 향상시키죠.

다양한 검색기를 사용하는데요 (참조: ) 사용자 쿼리에서 관련 정보를 추출하고 LLM을 사용해서 답변을 만들어내요. 관련 정보가 발견되지 않으면 챗봇이 사용자에게 잘 알려준답니다.

/clear_chat_bot(채팅 경험)

Neo4j 데이터베이스에 저장된 채팅 기록을 지워요.

/metric(채팅 경험)

충실도 및 답변 관련성과 같은 지표를 기반으로 다양한 검색기에 대한 챗봇 응답을 평가해요. 이를 위해 Ragas 라이브러리를 사용해서 이러한 측정항목을 계산한답니다.

/additional_metrics(채팅 경험)

컨텍스트 엔터티 회상, 의미 점수, 루즈 점수와 같은 지표를 기반으로 챗봇 응답을 평가해요. 이를 위해서는 사용자가 추가로 제공해야 하는 Ground Truth가 필요하죠. 이를 위해 Ragas 라이브러리를 사용해서 이러한 측정항목을 계산해요.

/fetch_chunktext(채팅 경험)

특정 청크 및 청크 메타데이터와 관련된 텍스트를 가져와요.

요약

FastAPI 프레임워크를 사용하여 Python을 기반으로 구축된 백엔드 아키텍처는 GenAI 기능을 통합하고 다양한 문서 소스를 관리하기 위한 강력하고 확장 가능한 접근 방식을 보여주고 있어요.

LangChain의 LLM Graph Transformer와 문서 로더 제품군을 사용하여 시스템은 다양한 입력의 콘텐츠를 효과적으로 처리하고 엔터티와 관계를 추출해서 Neo4j 데이터베이스에 저장된 의미 있는 그래프 문서를 생성하죠.

이 포괄적인 모듈식 설계는 백엔드를 AI 기반 대화 인터페이스 및 고급 데이터 상호 작용을 위한 다목적 기반으로 만들어준답니다.

LLM Knowledge Graph

에이치시스템즈의 LogTree는 Neo4j 기반 GraphRAG 플랫폼으로, 데이터를 자동으로 지식그래프화하고 자연어 질의로 즉시 답을 제공합니다.

Neo4j LLM 지식 그래프 빌더, 이렇게 시작하세요! (0)	2026.07.18
LLM 지식 그래프 빌더, 2025년 첫 번째 릴리스! (1)	2026.07.18
LlamaParse로 문서에서 Knowledge Graph 만들기 (0)	2026.07.17
#GraphCast: 생명과학 분야 그래프 - 복잡한 데이터를 연결하는 치료제 (0)	2026.07.17
지식 해방: Neo4j와 함께하는 Machine Learning 기법 (0)	2026.07.16

Graph Note