LightningRAG

English | 简体中文

GitHub: https://github.com/LightningRAG/LightningRAG

1. 기본 소개

1.1 프로젝트 소개

LightningRAG는 RAG: 지식 기반(ingest, parse, chunk, vector retrieval), 플러그인 가능한 LLMs, 임베딩(embeddings), 벡터 스토어(vector stores), 리랭커(rerankers), 그리고 캔버스 상의 에이전트 오케스트레이션(Agent orchestration) (retrieval, LLM, tools, control flow)—와 선택적 웹훅 채널 커넥터(Feishu, DingTalk, Slack 등)를 중심으로 구축되었습니다. JWT, 동적 라우팅/메뉴, Casbin, 폼 빌더 및 코드 생성을 갖춘 Vue + Gin 풀스택 스타터로 제공됩니다.

온라인 데모: https://demo.LightningRAG.com

사용자 이름: admin

비밀번호: 123456

공개 미리보기는 아직 배포되지 않았습니다. 서버가 준비되면 취소선(strikethrough)을 제거하고 데모 링크를 다시 활성화하십시오.

2. 기능

• 지식 기반 및 RAG: 문서를 가져오기(Ingest), 파싱 및 청크 분할, 플러그인 가능한 벡터 스토어에 임베딩합니다; 하이브리드/다중 경로 검색(벡터, 키워드, PageIndex, 그리고 관련 리트리버 유형); 선택적 **references**가 포함된 대화형 및 스트리밍 채팅 API; 플러그인 가능한 LLMs, 임베딩, 리랭커, 그리고 config.yaml의 rag: 기본값 (아래 섹션 3 참조; server/rag/README.md).

• 에이전트 오케스트레이션: Begin, Retrieval, LLM, Message 및 Agent (도구 포함)와 같은 노드를 가진 시각적 캔버스 플로우를 통해 다단계 및 분기 자동화를 구현합니다; RAG 채팅을 위한 확장 가능한 도구 레지스트리(tool registry) (server/rag/tools/README.md).

• 채널 커넥터 (선택 사항): 게시된 에이전트를 Feishu, DingTalk, WeChat, Slack, Teams 및 기타 플랫폼의 웹훅(webhook) 엔드포인트에 연결합니다 (아래 섹션 3.5; docs/THIRD_PARTY_CHANNEL_CONNECTORS.md).

• 권한 관리: jwt와 casbin 기반의 권한 관리를 제공합니다.

• 파일 업로드 및 다운로드: Qiniuyun, Aliyun, 그리고 Tencent Cloud를 기반으로 파일 업로드 기능을 구현합니다 (각 플랫폼에 해당하는 token 또는 key를 사용하여 자체 애플리케이션을 개발해야 합니다).

• 페이지네이션 캡슐화(Pagination Encapsulation): 프론트엔드는 mixins를 사용하여 페이지 매김 기능을 캡슐화하며, 이 페이지 매김 메서드는 mixins를 호출할 수 있습니다.

• 사용자 관리: 시스템 관리자가 사용자 역할과 역할 권한을 할당합니다.

• 역할 관리: 권한 제어의 핵심 객체를 생성하고, 그 후 역할에 다양한 API 권한 및 메뉴 권한을 할당합니다.

• 메뉴 관리: 사용자의 동적 메뉴 구성 구현으로, 서로 다른 역할에 서로 다른 메뉴를 할당할 수 있습니다.

• API 관리: 사용자마다 호출할 수 있는 API 권한이 다릅니다.

• 설정 관리: 설정 파일은 프론트엔드에서 수정할 수 있습니다 (공개 데모 인스턴스를 실행하는 경우 비활성화될 수 있음).

• 조건부 검색(Conditional search): 조건부 검색의 예시를 추가했습니다.

• Restful 예제: 사용자 관리 모듈에서 샘플 API를 확인할 수 있습니다.

  • 프론트엔드 파일 참조: web/src/view/superAdmin/api/api.vue.
  • 서버 스테이지 참조: server/router/sys_api.go.

• 다중 로그인 제한(Multi-login restriction): config.yaml의 system 아래에 use-multipoint를 true로 설정합니다 (그에 따라 Redis를 구성해야 하며, 버그가 발견되면 보고해 주십시오).

• 청크 업로드: 청크 및 대용량 파일 업로드 예시입니다.

• 폼 빌더(Form builder): @Variant Form을 기반으로 합니다.

• 코드 생성기(Code generator): 백엔드에 기본적인 로직과 간단한 CRUD 코드 생성 기능을 제공합니다.

3. RAG, 지식 기반 및 에이전트 오케스트레이션

이 섹션은 지식 기반 → 검색 → 채팅/에이전트 → 채널 웹훅을 매핑합니다. 자세한 내용은 server/rag/README.md, config.yaml의 rag: 블록, 그리고 아래 연결된 문서를 참조하십시오.

3.1 지식 기반 및 문서

• 관리 워크플로우 (Admin workflows): 지식 기반 생성, 문서 업로드, 메타데이터 관리; 기반 공유/전송 (예: rag_knowledge_bases, rag_documents, rag_chunks 테이블 — server/rag/README.md 참조).
• 인덱싱 (Indexing): 일반 텍스트로 파싱하고, 청크(chunk)를 만들고, 임베딩하며, 벡터를 작성합니다; 지원되는 형식과 PDF 엔진 옵션은 docs/DOCUMENT_PARSE_RAGFLOW_ALIGNMENT.md에 설명되어 있습니다.
• 저장소 (Storage): 청크 메타데이터는 앱 데이터베이스에 저장되며; **벡터(vectors)**는 구성된 VectorStore(예: PostgreSQL + pgvector, Elasticsearch dense_vector)로 전송됩니다.

3.2 검색 및 대화 (Retrieval and conversation)

• 검색기 종류 (Retriever kinds): server/rag/ 아래의 Retriever 인터페이스를 통해 Vector, PageIndex, keyword 및 관련 유형을 사용할 수 있습니다.

• API: /rag/conversation/chat, chatStream (SSE; 최종 프레임에는 검색 모드, 쿼리, references, 등을 포함할 수 있음); **queryData**는 구조화된 검색 결과만 반환합니다 (LLM 없음, 메시지 지속성 없음; Casbin이 /rag/conversation/queryData를 허용해야 함).

• 요청 조정 (Request tuning): queryMode, chunkTopK, topK, enableRerank, hlKeywords / llKeywords, 히스토리, maxRagContextTokens, cosineThreshold, minRerankScore, includeReferences 등 본문 필드와 더 많은 설정은 server/model/rag/request/conversation.go를 참조하십시오.

• 전역 기본값 (config.yaml → rag:): 대화 및 KB의 top-k / 후보 풀(candidate pool) 키(default-conversation-chunk-top-k, default-knowledge-base-retrieve-top-n, max-retrieve-top-n, max-retrieve-candidate-top-k, …), 하이브리드 융합 (hybrid fusion) 가중치 및 점수 하한선, default-cosine-threshold, 그리고 지식 그래프(knowledge-graph) 조정(kg-*) 항목들이 있습니다. **0 값은 일반적으로

• 관리 DB 설정: rag_llm_providers, rag_embedding_providers, rag_vector_store_configs (및 관리 UI 노출 영역).

• 사용자 모델: 최종 사용자는 사용자 모델(rag_user_llms)을 통해 키를 추가할 수 있습니다.

• 프로바이더: 플러그인 가능한 LLM, 임베딩, 재랭킹(rerank), 음성, TTS, OCR, CV 등. — 전체 목록은 server/rag/README.md에서 확인할 수 있습니다. 재랭킹 프로바이더가 구성된 경우 enableRerank를 사용하여 요청별로 재랭킹을 활성화할 수 있습니다.

3.4 에이전트 오케스트레이션 (Agent orchestration)

• 흐름 편집기: 단일 고정 KB 채팅과 달리, 다단계 및 분기형 흐름을 위한 Begin, Retrieval, LLM, Message, 에이전트(Agent) (도구 포함)와 같은 캔버스 노드.
• 계획(Plans): docs/AGENT_IMPLEMENTATION_PLAN.md, docs/AGENT_COMPONENTS_DEVELOPMENT_PLAN.md.
• 도구(Tools): RAG 채팅을 위한 확장 가능한 도구 레지스트리 — server/rag/tools/README.md.

3.5 채널 커넥터 (Webhook)

• 플랫폼: Feishu, DingTalk, WeChat, WeCom, Discord, Slack, Telegram, Teams, WhatsApp, LINE 등. 공개 웹훅 URL을 통해 게시된 **에이전트(Agents)**에 연결되며, X-Webhook-Secret 또는 벤더 서명; 관리 UI의 채널별 extra JSON을 사용합니다.
• rag: 작업 조정: channel-webhook-ip-limit-per-minute (Redis), channel-webhook-event-retention-days, 아웃바운드 재시도 큐를 위한 channel-outbound-*.
• 전체 가이드: docs/THIRD_PARTY_CHANNEL_CONNECTORS.md (OAuth 로그인과는 다름 — docs/THIRD_PARTY_OAUTH_QUICK_LOGIN.md).

4. 기술 선택(Technology selection)

• 프론트엔드: Vue와 Element Plus-스타일 UI (Element 계열).
• 백엔드: REST 스타일 API를 위한 Gin.
• 데이터베이스: InnoDB가 포함된 MySQL > 5.7을 GORM을 통해 사용.
• 캐시: JWT 세션 추적 및 선택적 다중 로그인 제한을 위한 Redis.
• API 문서: Swagger.
• 설정: YAML 파일 처리를 위해 fsnotify와 Viper 사용.
• 로깅: zap.

5. 프로젝트 아키텍처

5.1 프로젝트 레이아웃

    ├── server
        ├── api             (API 진입점)
        │   └── v1          (v1 버전 인터페이스)
...

6. 시작하기

- node 버전 > v18.16.0
- golang 버전 >= v1.22
- IDE 권장: GoLand

6.1 서버 프로젝트

GoLand 또는 다른 에디터에서 server 디렉토리를 엽니다. 백엔드 작업을 위해 LightningRAG 리포지토리 루트를 열지 마십시오.

# 프로젝트 클론
git clone https://github.com/LightningRAG/LightningRAG.git

...

6.2 웹 프로젝트

# web 디렉토리로 이동
cd web

...

6.3 임베디드 웹 UI (선택 사항, go:embed)

빌드된 Vue 앱을 임베딩하여 하나의 바이너리로 배포하려면:

1. 리포지토리 루트에서:

   복사

   make build-server-embed-local
   

   1

   2

   또는 bash scripts/build-server-with-embed.sh (이는 yarn build, scripts/sync-web-dist.sh를 실행한 후, server/에서 go build를 수행합니다).

2. config.yaml에서 system.embed-web-ui: true로 설정합니다 (기본값은 일반적인 Nginx + API 분리 구조의 경우 false).

3. router-prefix가 비어 있고 임베딩이 활성화된 경우, /api/...는 Gin 라우팅 전에 (/...)으로 재작성됩니다 (HTTP 핸들러 래퍼). 이는 이 리포지토리의 VITE_BASE_API=/api 및 Nginx의 rewrite 규칙과 일치합니다. 일반적인 Engine.Use 미들웨어는 Gin이 전역 미들웨어가 실행되기 전에 라우트를 매칭하기 때문에 이를 수정할 수 없습니다. 만약 router-prefix가 설정되면, 자동 /api 제거 기능은 적용되지 않습니다.

참고: scripts/sync-web-dist.sh 및 server/webui/도 참조하십시오.

GoReleaser (GitHub Releases의 다중 플랫폼 바이너리)

공식 릴리스 빌드는 리포지토리 루트에 있는 .goreleaser.yaml을 사용하여 GoReleaser로 생성합니다.

• 컴파일 전: web/에서 npm install + npm run build를 실행한 후, scripts/sync-web-dist.sh를 실행합니다. 이때 임베딩 경로는 위와 동일하게 유지됩니다 (server/webui/webdist → go:embed).
• Go 모듈: go.mod는 server/에 위치하며, 설정은 gomod.dir: server로 되어 있어 모노레포 루트에서 모듈 감지가 작동합니다.
• 타겟: Linux / Windows / macOS / FreeBSD용 CGO_ENABLED=0 크로스 빌드가 지원됩니다 (amd64, arm64, 사용 가능한 경우 386, 그리고 Linux armv7 및 Windows arm64). 정확한 매트릭스는 .goreleaser.yaml을 참조하십시오.
• 아티팩트: 각 아카이브에는 lightningrag 바이너리, config.yaml (server/config.docker.yaml에서 복사됨), 그리고 server/resource의 resource/ 트리가 포함됩니다.
• CI: v* 태그를 푸시하면 .github/workflows/goreleaser.yml이 실행되고 GitHub Releases에 게시됩니다 (GITHUB_TOKEN을 통해 contents: write 권한 필요).

로컬 드라이 런 (업로드 없음):

goreleaser release --snapshot --clean --skip=publish

게시: semver 태그를 생성하고 푸시합니다. 예: git tag v2.9.1 && git push origin v2.9.1.

6.4 Swagger API 문서

6.4.1 swag 설치

go install github.com/swaggo/swag/cmd/swag@latest

6.4.2 API 문서 생성

cd server
swag init

위 명령을 실행한 후, server/docs 아래에 docs.go, swagger.json, 그리고 swagger.yaml이 업데이트됩니다. Go 서버를 시작하고 http://localhost:8888/swagger/index.html에 접속하여 Swagger UI를 확인하십시오.

6.5 VS Code 작업 공간

6.5.1 개발

VS Code에서 리포지토리 루트의 LightningRAG.code-workspace 파일을 여십시오. 사이드바에는 세 개의 가상 폴더(backend, frontend, root)가 표시됩니다.

6.5.2 실행 / 디버그

Backend, Frontend, 또는 Both (Backend & Frontend) 태스크를 사용하십시오. 마지막 태스크는 백엔드와 프론트엔드를 함께 시작합니다.

6.5.3 설정

작업 공간 파일에서 VS Code의 Go 도구용 go.toolsEnvVars를 정의할 수 있습니다. 여러 버전의 Go가 설치된 머신에서는 필요한 대로 go.gopath와 go.goroot을 설정하세요.

    "go.gopath": null,
    "go.goroot": null,

6.6 추가 문서 (Additional documentation)

• RAG 백엔드 모듈 (providers, 벡터 스토어, API 개요)
• RAG 도구 호출 프레임워크
• 타사 채팅 채널 커넥터 (Webhook)
• 타사 OAuth 빠른 로그인
• 지식 기반 문서 파싱 대 Ragflow 비교
• 에이전트 오케스트레이션 계획 · 에이전트 컴포넌트 로드맵
• 간체 중국어: 채널 커넥터 · OAuth 빠른 로그인

7. 기여 가이드 (Contributing Guide)

안녕하세요! LightningRAG를 선택해 주셔서 감사합니다.

LightningRAG는 개발자, 디자이너 및 제품 관리자를 위한 풀스택(프론트엔드와 백엔드 분리) 프레임워크입니다.