## Step 1: LightRAG란?
### 1-1. LightRAG 개요
- LightRAG는 Graph-based RAG (Retrieval-Augmented Generation) 시스템으로, 기존 벡터 검색에 지식 그래프를 결합하여 더 풍부한 컨텍스트의 검색 결과를 제공합니다.
### 1-2. LightRAG 장점
- 지식 그래프 기반 - 검색엔티티와 관계를 자동 추출하여 연결된 정보 검색
- 다양한 검색 모드 - naive, local, global, hybrid
- 가볍고 빠름 - JSON/파일 기반으로도 동작, 필요시 PostgreSQL, Neo4j 등 확장 가능
- WebUI 시각화 - 지식 그래프를 시각적으로 탐색 가능
## Step 2: 사전 요구사항 설치
### 2-1 UV 설치 (Python 패키지 매니저)
```powershell
# PowerShell에서 실행
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
# 설치 확인
# 출력: uv 0.9.24
uv --version
```
### 2-2 Bun 설치 (WebUI 빌드용)
```powershell
# PowerShell에서 실행
powershell -c "irm bun.sh/install.ps1 | iex"
# PATH 업데이트 (현재 세션)
$env:Path = "C:\Users\daniel\.bun\bin;" + $env:Path
# 설치 확인
# 출력: 1.3.6
bun --version
```
## Step 3: LightRAG 저장소 클론 및 설치
### 3-1. 저장소 클론
```powershell
# 프로젝트 전용 폴더 생성
mkdir GraphRAG
cd GraphRAG
# Git 설치 확인
# 설치 안 되어 있으면 아래 링크에서 다운로드
# https://git-scm.com/download/win
git --version
# Git 저장소 클론 명령어
git clone https://github.com/HKUDS/LightRAG.git
cd LightRAG
#Git 저장소 클론 화면 예시
com/HKUDS/LightRAG.git
Cloning into 'LightRAG'...
remote: Enumerating objects: 34978, done.
remote: Counting objects: 100% (8/8), done.
remote: Compressing objects: 100% (5/5), done.
Receiving objects: 51% (17998/34978), 50.17 MiB | 10.27 MiB/
Receiving objects: 52% (18189/34978), 50.17 MiB | 10.27 MiB/Receiving objects: 53% (18539/34978)
```
### 3-2. Python 의존성 설치
```powershell
# uv 의존성 설치 명령어
uv sync --extra api
# uv 의존성 설치 화면 예시
<truncated 338 lines>
python-docx ------------------------------ 190.88 KiB/247.06 KiB
tzdata ------------------------------ 94.88 KiB/339.69 KiB
pydantic ------------------------------ 408.56 KiB/451.59 KiB
python-pptx ------------------------------ 224.00 KiB/461.71 KiB
pypinyin ------------------------------ 798.67 KiB/820.51 KiB
openai ------------------------------ 156.95 KiB/984.74 KiB
pycryptodome ------------------------------ 288.00 KiB/1.72 MiB
pydantic-core ------------------------------ 990.21 KiB/1.94 MiB
Building lightrag-hku @ file:///C:/Users/daniel/Desktop/GraphRAG/LightRAG
⠦ Preparing packages... (38/53)
openpyxl ------------------------------ 108.47 KiB/245.03 KiB
python-docx ------------------------------ 190.88 KiB/247.06 KiB
tzdata ------------------------------ 94.88 KiB/339.69 KiB
pydantic ------------------------------ 408.56 KiB/451.59 KiB
python-pptx ------------------------------ 224.00 KiB/461.71 KiB
pypinyin ------------------------------ 798.67 KiB/820.51 KiB
openai ------------------------------ 156.95 KiB/984.74 KiB
pycryptodome ------------------------------ 288.00 KiB/1.72 MiB
pydantic-core ------------------------------ 1017.56 KiB/1.94 MiB
Building lightrag-hku @ file:///C:/Users/daniel/Desktop/GraphRAG/LightRAG
⠦ Preparing packages... (38/53)
```
### 3-3. WebUI 프론트엔드 빌드
```powershell
# Bun 의존성 설치 명령어
cd lightrag_webui
bun install --frozen-lockfile
# Bun 의존성 설치 화면 예시
-Location lightrag_webui; bun install --frozen-lockfile
bun install v1.3.6 (d530ed99)
+ @eslint/
[email protected]
+ @stylistic/
[email protected]
+ @tailwindcss/
[email protected]
+ @tailwindcss/
[email protected]
+ @types/
[email protected]
+ @types/
[email protected]
+ @types/
[email protected]
+ @types/
[email protected]
+ @types/
[email protected]
+ @types/
[email protected]
+ @types/
[email protected]
+ @types/
[email protected]
+ @vitejs/
[email protected]
+
[email protected]
+
[email protected]
+
[email protected]
+
[email protected]
+
[email protected]
+
[email protected]
+
[email protected]
+
[email protected]
+
[email protected]
+
[email protected]
+
[email protected]
+
[email protected]
+
[email protected]
+
[email protected]
# Bun 실행 빌드
bun run build
cd ..
```
## Step 4: 환경 설정 (.env)
### 4-1. 환경 파일 생성
```powershell
# 환경 설정 파일 복사
Copy-Item env.example .env
```
### 4-2. 주요 설정 항목
- `.env` 파일에서 다음 항목들을 설정
```env
# 기본 설정
HOST=0.0.0.0
PORT=9621
WEBUI_TITLE='My Graph KB'
WEBUI_DESCRIPTION="Simple and Fast Graph Based RAG System"
# 인증 및 언어 설정
AUTH_ACCOUNTS='<ID:PASSWORD'>
TOKEN_SECRET=<YOUR_CUSTOM_TOKEN_SECRET>
LIGHTRAG_API_KEY=<YOUR_CUSTOM_API_KEY>
ENABLE_LLM_CACHE=true
RERANK_BINDING=null
ENABLE_LLM_CACHE_FOR_EXTRACT=true
SUMMARY_LANGUAGE=Korean
# 동시성 설정
MAX_ASYNC=12
MAX_PARALLEL_INSERT=3
EMBEDDING_FUNC_MAX_ASYNC=24
EMBEDDING_BATCH_NUM=100
# LLM 설정
LLM_BINDING=openai
LLM_MODEL=gpt-4.1-nano
LLM_BINDING_HOST=https://api.openai.com/v1
LLM_BINDING_API_KEY=<YOUR_OPENAI_API_KEY>
OPENAI_LLM_MAX_COMPLETION_TOKENS=9000
# 임베딩 설정
EMBEDDING_BINDING=openai
EMBEDDING_MODEL=text-embedding-3-small
EMBEDDING_DIM=1536
EMBEDDING_SEND_DIM=false
EMBEDDING_TOKEN_LIMIT=8192
EMBEDDING_BINDING_HOST=https://api.openai.com/v1
EMBEDDING_BINDING_API_KEY=<YOUR_OPENAI_API_KEY>
```
## Step 5: 로컬 서버 실행
### 5-1. 서버 시작
```powershell
# 서버 실행
cd LightRAG
.\.venv\Scripts\Activate.ps1
lightrag-server
```
### 5-2. 접속 정보
- WebUI - http://localhost:9621
- API 문서 - http://localhost:9621/docs
```powershell
# API 호출 예시
curl -H "X-API-Key: <YOUR_LIGHTRAG_API_KEY>" http://localhost:9621/query
```
## Step 6: Railway 클라우드 배포
### 6-1. GitHub Fork (Dockerfile 수정 필요)
- [LightRAG GitHub](https://github.com/HKUDS/LightRAG) → Fork
- Fork Repo → Dockerfile → Edit → 아래 코드로 수정
```dockerfile
# syntax=docker/dockerfile:1
# Frontend build stage
FROM oven/bun:1 AS frontend-builder
WORKDIR /app
# Copy frontend source code
COPY lightrag_webui/ ./lightrag_webui/
# Build frontend assets for inclusion in the API package
RUN --mount=type=cache,target=/root/.bun/install/cache \
cd lightrag_webui \
&& bun install --frozen-lockfile \
&& bun run build
# Python build stage - using uv for faster package installation
FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim AS builder
ENV DEBIAN_FRONTEND=noninteractive
ENV UV_SYSTEM_PYTHON=1
ENV UV_COMPILE_BYTECODE=1
WORKDIR /app
# Install system deps (Rust is required by some wheels)
RUN apt-get update \
&& apt-get install -y --no-install-recommends \
curl \
build-essential \
pkg-config \
&& rm -rf /var/lib/apt/lists/* \
&& curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
ENV PATH="/root/.cargo/bin:/root/.local/bin:${PATH}"
# Ensure shared data directory exists for uv caches
RUN mkdir -p /root/.local/share/uv
# Copy project metadata and sources
COPY pyproject.toml .
COPY setup.py .
COPY uv.lock .
# Install base, API, and offline extras without the project to improve caching
RUN --mount=type=cache,target=/root/.local/share/uv \
uv sync --frozen --no-dev --extra api --extra offline --no-install-project --no-editable
# Copy project sources after dependency layer
COPY lightrag/ ./lightrag/
# Include pre-built frontend assets from the previous stage
COPY --from=frontend-builder /app/lightrag/api/webui ./lightrag/api/webui
# Sync project in non-editable mode and ensure pip is available for runtime installs
RUN --mount=type=cache,target=/root/.local/share/uv \
uv sync --frozen --no-dev --extra api --extra offline --no-editable \
&& /app/.venv/bin/python -m ensurepip --upgrade
# Prepare offline cache directory and pre-populate tiktoken data
# Use uv run to execute commands from the virtual environment
RUN mkdir -p /app/data/tiktoken \
&& uv run lightrag-download-cache --cache-dir /app/data/tiktoken || status=$?; \
if [ -n "${status:-}" ] && [ "$status" -ne 0 ] && [ "$status" -ne 2 ]; then exit "$status"; fi
# Final stage
FROM python:3.12-slim
WORKDIR /app
# Install uv for package management
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
ENV UV_SYSTEM_PYTHON=1
# Copy installed packages and application code
COPY --from=builder /root/.local /root/.local
COPY --from=builder /app/.venv /app/.venv
COPY --from=builder /app/lightrag ./lightrag
COPY pyproject.toml .
COPY setup.py .
COPY uv.lock .
# Ensure the installed scripts are on PATH
ENV PATH=/app/.venv/bin:/root/.local/bin:$PATH
# Install dependencies with uv sync (uses locked versions from uv.lock)
# And ensure pip is available for runtime installs
RUN --mount=type=cache,target=/root/.local/share/uv \
uv sync --frozen --no-dev --extra api --extra offline --no-editable \
&& /app/.venv/bin/python -m ensurepip --upgrade
# Create persistent data directories AFTER package installation
RUN mkdir -p /app/data/rag_storage /app/data/inputs /app/data/tiktoken
# Copy offline cache into the newly created directory
COPY --from=builder /app/data/tiktoken /app/data/tiktoken
# Point to the prepared cache
ENV TIKTOKEN_CACHE_DIR=/app/data/tiktoken
ENV WORKING_DIR=/app/data/rag_storage
ENV INPUT_DIR=/app/data/inputs
# Expose API port
EXPOSE 9621
ENTRYPOINT ["python", "-m", "lightrag.api.lightrag_server"]
```
### 6-2. Railway 배포
- [Railway](https://railway.com) 대시보드 → New Service → GitHub Repo
- Fork Repo 선택 → Deploy
### 6-3. Railway 환경변수 설정
- [Railway](https://railway.com) 대시보드 → Variables → Raw Editor
- Env → 아래 환경 변수 붙여넣기 → Deploy
```env
AUTH_ACCOUNTS='<ID:PASSWORD'>
TOKEN_SECRET=<YOUR_CUSTOM_TOKEN_SECRET>
LIGHTRAG_API_KEY=<YOUR_CUSTOM_API_KEY>
ENABLE_LLM_CACHE=true
ENABLE_LLM_CACHE_FOR_EXTRACT=true
SUMMARY_LANGUAGE=Korean
MAX_ASYNC=12
MAX_PARALLEL_INSERT=3
EMBEDDING_FUNC_MAX_ASYNC=24
EMBEDDING_BATCH_NUM=100
LLM_BINDING=openai
LLM_MODEL=gpt-4.1-nano
LLM_BINDING_HOST=https://api.openai.com/v1
LLM_BINDING_API_KEY=<YOUR_OPENAI_API_KEY>
OPENAI_LLM_MAX_COMPLETION_TOKENS=9000
EMBEDDING_BINDING=openai
EMBEDDING_MODEL=text-embedding-3-small
EMBEDDING_DIM=1536
EMBEDDING_SEND_DIM=false
EMBEDDING_TOKEN_LIMIT=8192
EMBEDDING_BINDING_HOST=https://api.openai.com/v1
EMBEDDING_BINDING_API_KEY=<YOUR_OPENAI_API_KEY>
```
## Step 7: 트러블슈팅
### 7-1. UV 명령어를 찾을 수 없음
```powershell
# PATH에 UV 추가
$env:Path = "$env:USERPROFILE\.local\bin;" + $env:Path
```
### 7-2. Bun 명령어를 찾을 수 없음
```powershell
# PATH에 Bun 추가
$env:Path = "C:\Users\daniel\.bun\bin;" + $env:Path
```
### 7-3. Railway Docker 빌드 에러 (cache mount)
- 원본 Dockerfile에 `--mount=type=cache` 사용
- Fork 후 cache mount 제거한 Dockerfile로 교체 필요
### 7-4. Git Bash에서 가상환경 활성화
```bash
source .venv/Scripts/activate
```
### 관련 노트
[[Claude Code 실전 가이드]] - [[n8n 레일웨이 호스팅 설치 방법]] - [[n8n 셀프 호스팅 Docker 설치 방법]] - [[로컬 슈퍼베이스 구축 및 n8n 연동]] - [[데이터 클래스 Chapter 1]] - [[데이터 클래스 Chapter 12]]
## 🧠 Connected Insights
> 📅 Last analyzed: 2026. 4. 24. 오후 3:36:29
> 💰 Analysis cost: $0.0182
### 🔗 Related Notes
- 🔼 [[데이터 클래스/데이터 클래스 Chapter 12.md]]
- extends: LightRAG 설치 및 설정 가이드는 Chapter 12에서 다루는 지식 베이스, RAG, GraphRAG, LightRAG 등과 직접적으로 연결되며, Chapter 12의 내용을 구체적인 설치 및 실습 단계로 확장합니다.
- Confidence: ████░ (85%)
- 🔼 [[데이터 클래스/데이터 클래스 Chapter 11.md]]
- extends: Chapter 11은 지식 베이스와 RAG의 전반적인 구조 및 개념을 다루고, LightRAG 설치 및 설정 가이드는 이를 실질적으로 구현하는 방법을 안내하여 논리적으로 확장 관계에 있습니다.
- Confidence: ████░ (80%)
- ✅ [[에이전트 클래스/에이전트 클래스 Chapter 5.md]]
- supports: 에이전트 클래스 Chapter 5는 n8n 기반 AI 에이전트 제작을 다루며, LightRAG 설치 및 설정 가이드는 해당 에이전트가 활용할 수 있는 RAG 시스템의 구체적 구현 방법을 지원합니다.
- Confidence: ████░ (75%)
- 🔗 [[데이터베이스 클래스/로컬 슈퍼베이스 구축 및 n8n 연동.md]]
- related: LightRAG는 외부 데이터베이스(PostgreSQL, Neo4j 등)와의 연동 및 확장을 지원하며, 슈퍼베이스 및 n8n 연동 노트는 데이터 파이프라인 구축과 자동화에 관한 실무적 연관성이 있습니다.
- Confidence: ████░ (70%)
- 🔗 [[에이전트 클래스/에이전트 클래스 Chapter 1.md]]
- related: Chapter 1은 RAG, LangChain 등 에이전트 개념의 오리엔테이션을 제공하며, LightRAG 설치 및 설정 가이드는 그 중 하나의 구체적 구현 사례로 연관성이 있습니다.
- Confidence: ████░ (70%)
### 📚 Knowledge Gaps
- 🔴 **LightRAG의 실제 활용 예시 및 워크플로우**
- 설치와 설정에 대한 안내는 있으나, 실제로 LightRAG를 활용한 구체적인 워크플로우(예: 문서 분석, 질의응답 등)와 적용 사례가 부족합니다. 실무 적용을 위해서는 end-to-end 예시가 중요합니다.
- Suggested resources: LightRAG 공식 GitHub의 예제 폴더, LearnOpenCV LightRAG 활용 사례 블로그
- 🟡 **LightRAG와 기존 RAG/GraphRAG 시스템의 차이점 및 선택 기준**
- LightRAG의 차별점, 기존 RAG/GraphRAG 대비 장단점, 어떤 상황에서 어떤 시스템을 선택해야 하는지에 대한 비교 분석이 부족합니다. 도입 의사결정에 중요한 정보입니다.
- Suggested resources: LightRAG 논문 및 공식 문서, RAG/GraphRAG 비교 분석 아티클
- 🔴 **보안 및 인증 설정**
- 설치 및 기본 설정은 안내되어 있으나, 실무 환경에서 필수적인 보안(접근제어, 인증, 데이터 보호 등) 설정 방법이 누락되어 있습니다.
- Suggested resources: LightRAG 공식 문서의 Security 섹션, PostgreSQL/Neo4j 인증 및 보안 가이드
- 🟡 **성능 평가 및 모니터링 방법**
- LightRAG 시스템의 성능(검색 속도, 정확도, 리소스 사용량 등) 평가 및 모니터링 방법에 대한 안내가 없습니다. 운영 및 최적화에 필수적인 정보입니다.
- Suggested resources: LightRAG Benchmarks 문서, RAG 시스템 성능 측정 관련 논문
- 🟡 **확장(Neo4j/PostgreSQL 등) 및 대규모 데이터셋 적용 가이드**
- LightRAG가 다양한 DB 및 대규모 데이터셋을 지원한다고 언급하지만, 실제 확장 및 대용량 데이터셋 적용 방법(설정, 한계, 트러블슈팅 등)이 구체적으로 다뤄지지 않았습니다.
- Suggested resources: LightRAG 공식 문서의 DB 연동 가이드, Neo4j/PostgreSQL 대용량 운영 Best Practice
### 💡 AI Insights
이 노트는 LightRAG의 설치와 기본 설정에 매우 실용적인 안내를 제공하며, 지식 그래프 기반 RAG 시스템의 도입을 위한 첫걸음에 적합합니다. 그러나 실제 적용 사례, 시스템 선택 기준, 보안 및 성능 관리 등 실무적/운영적 측면의 내용이 부족합니다. 관련 노트들과의 연결을 통해 이론(지식 베이스, RAG 개념)과 실습(에이전트, 데이터베이스 연동 등)이 유기적으로 이어지나, 실전 적용을 위한 심화 내용이 추가될 필요가 있습니다.
## 🧠 Connected Insights
> 📅 Last analyzed: 2026. 4. 18. 오전 9:12:14
> 💰 Analysis cost: $0.0183
### 🔗 Related Notes
- 🔗 [[데이터베이스 클래스/로컬 슈퍼베이스 구축 및 n8n 연동.md]]
- related: 두 노트 모두 데이터베이스, 자동화, n8n 등 데이터 파이프라인 구축과 관련된 실무적 내용을 다룸. LightRAG의 설치와 데이터베이스 연동이 실제로 필요할 수 있어 개념적 연관성이 높음.
- Confidence: ████░ (70%)
- 🔼 [[데이터 클래스/데이터 클래스 Chapter 11.md]]
- extends: Chapter 11은 RAG, Supabase, Embeddings 등 지식 베이스 구축의 기초를 다루고, LightRAG 설치 가이드는 이를 실제로 구현하는 구체적 방법을 제공함. 논리적으로 Chapter 11의 내용을 실습으로 확장하는 관계.
- Confidence: ████░ (80%)
- 🔼 [[데이터 클래스/데이터 클래스 Chapter 12.md]]
- extends: Chapter 12는 GraphRAG, LightRAG 등 지식 그래프 기반 RAG의 심화 내용을 다루며, LightRAG 설치 가이드는 그 구체적 실습을 안내함. 이론→실습의 확장 관계.
- Confidence: ████░ (85%)
- ✅ [[에이전트 클래스/에이전트 클래스 Chapter 5.md]]
- supports: Chapter 5는 n8n 기반 AI 에이전트 제작을 다루며, LightRAG 설치 및 설정은 이러한 에이전트의 데이터 소스/지식 베이스로 활용될 수 있음. 실무적 지원 관계.
- Confidence: ████░ (75%)
- 🔗 [[노코드 자료/명지대 캡스톤 디자인 수업.md]]
- related: 노코드/자동화/AI 프로젝트 실습과 관련된 수업 자료로, LightRAG와 같은 신기술 도입 사례와 연관될 수 있음. 개념적 연관성은 있으나 직접적 확장/지지 관계는 약함.
- Confidence: ███░░ (60%)
### 📚 Knowledge Gaps
- 🔴 **LightRAG의 실제 활용 예시 및 워크플로우**
- 설치 및 설정 가이드만 있고, 실제로 LightRAG를 활용한 구체적 예시(예: 법률 문서 분석, FAQ 검색 등)와 단계별 워크플로우가 없음. 실무 적용과 이해를 위해 필수.
- Suggested resources: LightRAG 공식 GitHub 예제 폴더, LearnOpenCV LightRAG Tutorial
- 🟡 **LightRAG와 기존 RAG/GraphRAG 시스템의 차이점 및 선택 기준**
- LightRAG의 특징은 언급되지만, 기존 RAG/GraphRAG와의 비교, 각각의 장단점, 선택 기준이 체계적으로 정리되어 있지 않음. 도입 의사결정에 중요.
- Suggested resources: Retrieval-Augmented Generation (RAG) 논문, LightRAG vs GraphRAG 비교 블로그
- 🔴 **보안 및 인증 설정**
- 설치 및 기본 설정만 안내되어 있고, 운영 환경에서 필수적인 인증/접근제어/보안 설정(예: API Key, 사용자 인증, 데이터 암호화 등)이 다뤄지지 않음.
- Suggested resources: LightRAG 공식 문서의 Security 섹션, OWASP Python Security Guide
- 🟡 **성능 평가 및 모니터링 방법**
- LightRAG의 성능(검색 정확도, 속도 등) 평가 방법, 모니터링, 로깅, 지표 수집 등에 대한 안내가 없음. 실서비스 적용 및 운영에 필수.
- Suggested resources: MLflow Tracking, Prometheus + Grafana for Python
- 🟡 **확장(Neo4j/PostgreSQL 등) 및 대규모 데이터셋 적용 가이드**
- LightRAG가 Neo4j, PostgreSQL 등으로 확장 가능하다고 언급되나, 실제 확장 방법, 대규모 데이터셋 적용 시 고려사항, 성능 이슈 등은 구체적으로 다루지 않음.
- Suggested resources: Neo4j 공식 Python Driver 문서, PostgreSQL 대용량 데이터 운영 가이드
### 💡 AI Insights
이 노트는 LightRAG의 설치와 설정에 중점을 둔 실무 가이드로, 지식 그래프 기반 RAG 시스템의 실제 구현에 초점을 맞추고 있습니다. 관련 노트들과의 연결을 통해 이론(데이터 클래스), 실습(에이전트/자동화), 인프라(데이터베이스)까지 연계된 지식 체계를 형성하고 있습니다. 그러나 실무 적용을 위한 실제 워크플로우, 보안/운영/확장성 등 실전적 주제는 미흡하게 다루어져 있어, 향후 사례 중심의 심화 노트와 운영 가이드가 보완되어야 전체 지식 체계가 완성될 것입니다.