neo4j-labs/llm-graph-builder

Large Language Models (LLMs)와 LangChain 프레임워크의 힘을 사용하여 비정형 데이터(PDF, DOC, TXT, YouTube 비디오, 웹 페이지 등)를 Neo4j에 저장되는 구조화된 지식 그래프 (Knowledge Graph)로 변환합니다.

이 애플리케이션을 사용하면 다양한 소스(로컬 머신, GCS, S3 버킷 또는 웹 소스)에서 파일을 업로드하고, 선호하는 LLM 모델을 선택하여 지식 그래프 (Knowledge Graph)를 생성할 수 있습니다.

Python 3.12 이상(로컬/별도 백엔드 배포용) - Neo4j 데이터베이스
APOC가 설치된 5.23 이상.- 백엔드가 Cypher 변수 범위 서브쿼리 (variable-scope subquery) 구문 (CALL (variable) { ... })을 사용하기 때문에 Neo4j 5.23 이상이 필요하며, 이는 5.20과 같은 이전 Neo4j 5.x 릴리스에서는 지원되지 않습니다. Neo4j Aura 데이터베이스(무료 티어 포함)가 지원됩니다.- Neo4j Desktop을 사용하는 경우, 백엔드와 프론트엔드를 별도로 배포해야 합니다 (docker-compose는 지원되지 않음).

• Neo4j 5.23은 백엔드가 Cypher 변수 범위 서브쿼리 (variable-scope subquery) 구문을 사용하기 때문에 필요합니다.

• backend/example.env를 복사하여 backend 폴더에 .env 파일을 생성합니다. - 로그인 대화 상자를 건너뛰려면 .env 파일에 사용자 자격 증명을 미리 구성하세요: NEO4J_URI=<your-neo4j-uri> NEO4J_USERNAME=<your-username> NEO4J_PASSWORD=<your-password> NEO4J_DATABASE=<your-database-name>

• 실행:
  cd backend
  python3.12 -m venv venv
  source venv/bin/activate # Windows의 경우: venv\Scripts\activate
  pip install -r requirements.txt
  uvicorn score:app --reload

• 고급 LLM을 사용하여 비정형 데이터를 구조화된 지식 그래프 (Knowledge Graphs)로 원활하게 변환합니다.

• 노드 (nodes), 관계 (relationships) 및 그 속성 (properties)을 추출하여 구조화된 그래프를 생성합니다.

• 설정을 통해 구성된 사용자 정의 스키마 (custom schema) 또는 기존 스키마를 사용하여 그래프를 생성합니다.

• Neo4j Bloom에서 특정 또는 여러 데이터 소스의 그래프를 동시에 볼 수 있습니다.

• 대화형 쿼리 (conversational queries)를 통해 Neo4j 데이터베이스 내의 데이터와 상호작용합니다.

• 쿼리에 대한 응답의 출처에 관한 메타데이터 (metadata)를 검색합니다.

• 전용 채팅 인터페이스를 사용하려면 /chat-only route가 포함된 독립형 채팅 애플리케이션을 사용하세요.

• OpenAI

• Gemini

• Diffbot

• Azure OpenAI (개발 배포 버전)

• Anthropic (개발 배포 버전)

• Fireworks (개발 배포 버전)

• Groq (개발 배포 버전)

• Amazon Bedrock (개발 배포 버전)

• Ollama (개발 배포 버전)

• Deepseek (개발 배포 버전)

• 기타 OpenAI 호환 베이스 URL 모델 (개발 배포 버전)

• 각 사용자 및 데이터베이스 연결에 대한 LLM 토큰 사용량을 쉽게 모니터링하고 추적할 수 있습니다.

• 백엔드 설정에서 TRACK_USER_USAGE 환경 변수를 true로 설정하여 이 기능을 활성화하세요.

• 일간 및 월간 토큰 소비량과 제한 사항을 확인하여 사용량을 관리하고 초과 비용 발생을 방지할 수 있습니다.

• 제공된 API 엔드포인트를 사용하여 언제든지 남은 토큰 제한을 확인할 수 있습니다.

• 데이터에 대한 벡터 임베딩 (vector embeddings)을 생성하기 위해 다양한 임베딩 모델 (embedding models) 중에서 선택할 수 있습니다. 이는 프론트엔드의 Graph Settings > Processing Configuration > Select Embedding Model에서 구성할 수 있습니다.

• 지원되는 모델 제공업체에는 OpenAI, Gemini, Amazon Titan 및 Sentence Transformers가 포함됩니다.

• TRACK_USER_USAGE가 활성화되어 있으면 선택한 임베딩 모델이 사용자 프로필에 저장됩니다.

로컬에서 임베딩 모델을 구성하는 방법은 두 가지가 있습니다:

• 사용자 추적 사용 시 (TRACK_USER_USAGE=true**):

  • 백엔드의 .env 파일에서 TRACK_USER_USAGE를 true로 설정합니다.
  • 토큰 추적 데이터베이스 자격 증명(TOKEN_TRACKER_DB_URI, TOKEN_TRACKER_DB_USERNAME 등)을 제공합니다.
  • 프론트엔드에서 원하는 임베딩 모델을 선택합니다. 선택 사항은 저장되어 이후 세션에서 자동으로 사용됩니다.

• 사용자 추적 미사용 시 (TRACK_USER_USAGE=false**):

  • TRACK_USER_USAGE를 false로 설정합니다.
  • 백엔드의 .env 파일에 임베딩 모델과 제공업체를 직접 지정합니다.

EMBEDDING_MODEL 및 EMBEDDING_PROVIDER를 사용하여 파일을 생성합니다.

• 이 변수들이 설정되지 않은 경우, 애플리케이션은 기본값으로 Sentence Transformer 모델을 사용합니다.

• 이 모드에서는 프론트엔드에서 임베딩 모델을 변경할 수 없습니다.

• 설정 방법:

• Neo4j 데이터베이스
  5.23 이상 버전 및 APOC 설치 필수.

• 백엔드에서 Cypher 변수 범위 서브쿼리(variable-scope subquery) 구문(CALL (variable) { ... })을 사용하기 때문에 Neo4j 5.23 버전이 필요합니다. 이 구문은 5.20과 같은 이전 Neo4j 5.x 릴리스에서는 지원되지 않습니다. Neo4j Aura 데이터베이스(무료 티어 포함)도 지원됩니다.

• Neo4j Desktop을 사용하는 경우, 백엔드와 프론트엔드를 별도로 배포해야 합니다 (docker-compose는 지원되지 않습니다).

• 백엔드에서 Cypher 변수 범위 서브쿼리 구문을 사용하기 때문에 Neo4j 5.23 버전이 필요합니다.

기본 docker-compose 설정을 사용하여 애플리케이션을 실행합니다.

• 지원되는 LLM 모델:

기본적으로 OpenAI와 Diffbot만 활성화되어 있습니다. Gemini를 사용하려면 추가적인 GCP 설정이 필요합니다.

VITE_LLM_MODELS_PROD 변수를 사용하여 필요한 모델을 구성하십시오. 예시:
VITE_LLM_MODELS_PROD="gemini_3.5_flash,openai_gpt_5.4_mini,diffbot,anthropic_claude_4.5_haiku"

• Anthropic 모델:
  설정에서 최신 Claude 모델을 사용하십시오:
  LLM_MODEL_CONFIG_ANTHROPIC_CLAUDE_4_7_OPUS="claude-opus-4-7,anthropic_api_key"

• 입력 소스 (Input Sources):

기본적으로 다음 소스들이 활성화되어 있습니다:
local, YouTube, Wikipedia, AWS S3, web.

Google Cloud Storage (GCS) 통합을 추가하려면 gcs와 Google 클라이언트 ID를 포함하십시오:
VITE_REACT_APP_SOURCES="local,youtube,wiki,s3,gcs,web" VITE_GOOGLE_CLIENT_ID="your-google-client-id"

VITE_CHAT_MODES 변수를 사용하여 채팅 모드를 구성하십시오:

• 기본적으로 모든 모드가 활성화되어 있습니다:
  vector, graph_vector, graph, fulltext, graph_vector_fulltext, entity_vector, global_vector.
• 특정 모드만 지정하려면 변수를 업데이트하십시오. 예시:
  VITE_CHAT_MODES="vector,graph"

개발을 위해 백엔드와 프론트엔드를 독립적으로 실행할 수 있습니다.

• frontend/example.env를 복사하여 frontend 폴더에 .env 파일을 생성합니다.
• 필요에 따라 환경 변수 (environment variables)를 업데이트합니다.
• 실행:
  cd frontend

yarn yarn run dev

#### **Backend Setup (백엔드 설정)**
1. `backend/example.env`를 복사하여 `backend` 폴더에 `.env` 파일을 생성합니다.
2. 로그인 대화 상자를 건너뛰기 위해 `.env` 파일에 사용자 자격 증명 (user credentials)을 미리 구성합니다:
```bash
NEO4J_URI=<your-neo4j-uri>
NEO4J_USERNAME=<your-username>
NEO4J_PASSWORD=<your-password>
NEO4J_DATABASE=<your-database-name>

• 실행:
  cd backend
  ...

---
### **Cloud Deployment (클라우드 배포)**
다음 명령어를 사용하여 **Google Cloud Platform**에 애플리케이션을 배포하십시오:
#### **Frontend Deployment (프론트엔드 배포)**
```bash
gcloud run deploy dev-frontend \
--source . \
--region us-central1 \
...

gcloud run deploy dev-backend \
--set-env-vars "OPENAI_API_KEY=<your-openai-api-key>" \
--set-env-vars "DIFFBOT_API_KEY=<your-diffbot-api-key>" \
...

• ollama의 도커 이미지 (docker image)를 가져옵니다 (pull).
  docker pull ollama/ollama

• ollama 도커 이미지를 실행합니다.
  docker run -d -v ollama:/root/.ollama -p 11434:11434 --name ollama ollama/ollama

• 임의의 LLM 모델을 실행합니다 (예: llama3).
  docker exec -it ollama ollama run llama3

• docker compose에서 환경 변수 (env variable)를 구성합니다.
  LLM_MODEL_CONFIG_ollama_<model_name> # 예시: LLM_MODEL_CONFIG_ollama_llama3=${LLM_MODEL_CONFIG_ollama_llama3-llama3,http://host.docker.internal:11434}

• 백엔드 API URL을 구성합니다.
  VITE_BACKEND_API_URL=${VITE_BACKEND_API_URL-backendurl}

• 브라우저에서 애플리케이션을 열고 추출 (extraction)을 위한 ollama 모델을 선택합니다.

• 그래프 구축 (Graph Building)을 즐기십시오.

• 백엔드 환경 변수를 통해 URI와 비밀번호를 전달하거나, 로그인 대화 상자를 채우거나, Neo4j 자격 증명 (credentials) 파일을 드래그 앤 드롭하여 AURA DS 또는 AURA DB인 Neo4j Aura 인스턴스에 연결합니다.

• 구분을 위해 서로 다른 아이콘을 추가했습니다. AURA DB의 경우 데이터베이스 아이콘이, AURA DS의 경우 Neo4j 연결 (Connection) 상세 정보 레이블 바로 아래에 과학 분자 아이콘이 표시됩니다.

• 그래프를 생성하기 위해 비정형 소스 (unstructured sources) 목록에서 소스를 선택합니다.

• 그래프 생성에 사용될 LLM을 드롭다운 메뉴에서 (필요한 경우) 변경합니다.

• 선택 사항으로, 엔티티 그래프 추출 (entity graph extraction) 설정에서 스키마 (노드 및 관계 레이블)를 정의합니다.

• 여러 파일을 선택하여 '그래프 생성 (Generate Graph)'을 수행하거나, 'New' 상태인 모든 파일을 그래프 생성 대상으로 처리할 수 있습니다.

• 그리드에서 '보기 (View)'를 사용하여 개별 파일에 대한 그래프를 확인하거나, 하나 이상의 파일을 선택하고 '그래프 미리보기 (Preview Graph)'를 선택합니다.

• 처리/완료된 소스와 관련된 질문을 챗봇에게 물어보세요. 또한, LLM에 의해 생성된 답변에 대한 상세 정보를 확인할 수 있습니다.

환경 변수 이름	필수/선택	기본값	설명
BACKEND ENV
OPENAI_API_KEY	선택 사항	OpenAI LLM 모델을 사용하여 인증하고 요청을 추적하려면 OpenAI 키가 필요합니다
DIFFBOT_API_KEY	필수	비정형 데이터에서 엔티티와 관계를 추출하기 위해 Diffbot의 NLP 서비스를 사용하려면 API 키가 필요합니다
...	FRONTEND ENV
VITE_BLOOM_URL	필수	Bloom URL	Bloom 시각화를 위한 URL
VITE_REACT_APP_SOURCES	필수	local,youtube,wiki,s3	사용 가능한 입력 소스 목록
...

추가 변수 및 구성은 예시 환경 파일 (environment files)을 참조하십시오:

Cloud Build를 사용하여 백엔드와 프론트엔드를 Google Cloud Run에 수동으로 또는 자동 트리거를 통해 배포할 수 있습니다.

• 저장소를 Google Cloud Build에 연결하기:

  • Google Cloud Console에서 Cloud Build > Triggers로 이동합니다.
  • 새 트리거(trigger)를 생성하고 저장소를 선택합니다.
  • 원하는 브랜치(main, staging 또는 dev)에 푸시(push)할 때 트리거가 실행되도록 설정합니다.
  • Cloud Build는 저장소 루트에 있는 cloudbuild.yaml 파일을 자동으로 사용합니다.

• 치환 변수(Substitutions) 및 비밀값(Secrets) 구성하기:

  • 트리거 설정에서 필요한 치환 변수(예: _OPENAI_API_KEY, _DIFFBOT_API_KEY 등)를 환경 변수로 추가하거나, 민감한 데이터의 경우 Secret Manager를 사용합니다.

• 코드 푸시하기:

  • 구성된 브랜치에 푸시하면, Cloud Build는 cloudbuild.yaml에 정의된 단계에 따라 백엔드(및 선택적으로 프론트엔드)를 빌드하여 Cloud Run에 배포합니다.

• Google Cloud SDK 설정 및 인증하기:
  gcloud auth login
gcloud config set project <YOUR_PROJECT_ID>

• Cloud Build 수동 실행 (Run Cloud Build manually): gcloud builds submit --config cloudbuild.yaml --substitutions=_REGION=us-central1,_REPO=cloud-run-repo,_OPENAI_API_KEY=<your-openai-key>,_DIFFBOT_API_KEY=<your-diffbot-key>,_BUCKET_UPLOAD_FILE=<your-bucket>,_BUCKET_FAILED_FILE=<your-bucket>,_PROJECT_ID=<your-project-id>,_GCS_FILE_CACHE=False,_TRACK_USER_USAGE=False,_TOKEN_TRACKER_DB_URI=...,_TOKEN_TRACKER_DB_USERNAME=...,_TOKEN_TRACKER_DB_PASSWORD=...,_TOKEN_TRACKER_DB_DATABASE=...,_DEFAULT_DIFFBOT_CHAT_MODEL=...,_YOUTUBE_TRANSCRIPT_PROXY=...,_EMBEDDING_MODEL=..., _EMBEDDING_PROVIDER=...,_BEDROCK_EMBEDDING_MODEL_KEY=...,_LLM_MODEL_CONFIG_OPENAI_GPT_5_2=...,_LLM_MODEL_CONFIG_OPENAI_GPT_5_MINI=...,_LLM_MODEL_CONFIG_GEMINI_2_5_FLASH=...,_LLM_MODEL_CONFIG_GEMINI_2_5_PRO=...,_LLM_MODEL_CONFIG_DIFFBOT=...,_LLM_MODEL_CONFIG_GROQ_LLAMA3_1_8B=...,_LLM_MODEL_CONFIG_ANTHROPIC_CLAUDE_4_5_SONNET=...,_LLM_MODEL_CONFIG_ANTHROPIC_CLAUDE_4_5_HAIKU=...,_LLM_MODEL_CONFIG_LLAMA4_MAVERICK=...,_LLM_MODEL_CONFIG_FIREWORKS_QWEN3_6=...,_LLM_MODEL_CONFIG_FIREWORKS_GPT_OSS=...,_LLM_MODEL_CONFIG_FIREWORKS_DEEPSEEK_V3=...,_LLM_MODEL_CONFIG_BEDROCK_NOVA_MICRO_V1=...,_LLM_MODEL_CONFIG_BEDROCK_NOVA_LITE_V1=...,_LLM_MODEL_CONFIG_BEDROCK_NOVA_PRO_V1=...,_LLM_MODEL_CONFIG_OLLAMA_LLAMA3=...

• 각 꺾쇠괄호(<>) 안의 값은 실제 구성 및 비밀값으로 대체하세요.
  LLM_MODEL_CONFIG_FIREWORKS_QWEN3_6

은 fireworks_qwen3_6 모델 옵션에 대한 앱 노출(app-facing) 구성 키이며, Fireworks 서버리스 슬러그인 accounts/fireworks/models/qwen3p6-plus와 매핑되어야 합니다.

.- 배포에 필요한 경우 적절히 대체 변수(substitutions)를 생략하거나 추가할 수 있습니다.

• 빌드 모니터링 (Monitor the build): - 빌드 및 배포 프로세스는 Cloud Build 콘솔에서 확인할 수 있습니다.

• 배포된 서비스 접근 (Access your deployed service): - 배포가 완료되면, 백엔드는 Cloud Console에 표시되는 Cloud Run 서비스 URL에서 사용할 수 있습니다.

참고:

• cloudbuild.yaml 파일은 여러 환경(main, staging, dev)을 지원합니다.

) 브랜치 이름에 따라 결정됩니다. - 프론트엔드 빌드 및 배포 단계는 기본적으로 주석 처리되어 있습니다. 프론트엔드도 함께 배포하려면 cloudbuild.yaml에서 해당 부분의 주석을 해제하세요.

자세한 내용은 cloudbuild.yaml 내의 주석을 참조하십시오.