[OpenKB] OpenKB란?

최근 프로젝트에서 RAG 파이프라인을 구축하시거나 AI 연동 시스템 최적화를 진행하시면서, 기존 검색 방식의 한계를 체감하신 분들이 꽤 많으실 겁니다. 저 역시 프로젝트들에서 Weaviate나 Qdrant를 엮어 RAG를 설계할 때마다 항상 아쉬운 점이 있었습니다. 바로 '청킹된 문서'를 어떻게 유기적으로 연결할 것인가 하는 문제였죠.

최근 GraphRAG나 LightRAG처럼 지식 간의 관계를 엮어보려는 시도들을 흥미롭게 뜯어보고 있었는데요. 그러다 Andrej Karpathy가 제안했던 "LLM이 지식을 일종의 위키(Wiki) 형태로 지속적으로 컴파일하는 방식"을 매우 깔끔하게 오픈소스로 구현한 OpenKB를 접하게 되었습니다.

공부 겸 정보 공유를 위해 로컬에 세팅하고 적용해 보실 수 있도록 코드와 함께 상세히 정리해 보겠습니다.

1. 단순 검색 RAG의 한계와 OpenKB의 접근법

기존 RAG 시스템은 질문이 들어올 때마다 벡터 DB(Vector DB)에서 조각난 텍스트 청크(Chunk)를 찾아옵니다. 운이 좋으면 정답을 가져오지만, A 문서에 있는 개념과 B 문서에 있는 업데이트된 내용을 스스로 교차 검증하거나 누적해서 기억하지는 못하죠. 매 쿼리마다 새롭게 문서를 '발견'해야 하니, 모순된 내용이 있어도 감지하기 어렵습니다.

이를 해결하기 위해 Rerank와 지식그래프를 도입하여 해결하는 방법도 있지만, OpenKB라는 색다른 방법을 접하게 되어 글을 작성하게 되었습니다.

💡 지식그래프(GraphRAG)와의 차이점은?
'그럼 최근 유행하는 GraphRAG나 지식그래프랑 비슷한 거 아니야?'라고 생각하시는 분들도 계실 텐데요. 지식 간의 연결성을 찾는다는 목적은 같지만, 접근 방식과 결과물의 형태가 완전히 다릅니다.

지식그래프(Knowledge Graph): 문서에서 개체(Entity)와 관계(Relation)를 추출해 '노드(Node)'와 '엣지(Edge)'라는 수학적 데이터 구조로 연결합니다. 기계가 탐색하고 연산하기에는 최적화되어 있지만, 사람이 직관적으로 줄글처럼 읽고 전체 맥락을 파악하기에는 다소 복잡한 형태입니다.

OpenKB: 철저히 '사람이 읽고 이해할 수 있는 위키(Markdown)' 형태를 지향합니다. 기계적인 노드 연결을 넘어, LLM이 두 지식이 어떻게 연관되어 있는지 맥락을 줄글로 풀어내어 새로운 '개념(Concept) 페이지'를 작성합니다.

즉, 기계만을 위한 복잡한 데이터베이스 지도를 그리는 것이 지식그래프라면, OpenKB는 사람과 AI가 모두 읽을 수 있는 '공동 백과사전'을 집필하는 것에 가깝습니다. 덕분에 개발자뿐만 아니라 기획자나 비전공자도 생성된 지식 베이스를 그대로 읽고 업무에 활용할 수 있죠.

이러한 특성 때문에 OpenKB는 문서를 넣는 순간부터 기존의 파싱과 청킹과는 다르게 동작합니다. 문서를 넣으면 LLM이 백그라운드에서 이를 읽고 요약하며, 기존 지식 베이스와 연결해 하나의 마크다운(Markdown) 위키 백과사전을 만들어 줍니다. 새로운 문서가 들어오면 기존 위키 페이지를 업데이트하거나 새로운 개념(Concept) 페이지를 파생시킵니다.

쉽게 말하자면, 매번 도서관에서 책을 찾아오는 사서가 아니라, 책이 들어올 때마다 밤새워 핵심을 요약하고 백과사전을 갱신해 놓는 똑똑한 편집자를 두는 셈입니다.

2. 컨텍스트 한계를 넘는 방법: PageIndex 트리 구조

OpenKB 구조를 뜯어보면서 가장 신기했던 부분은 긴 문서를 처리하는 방식입니다. 100페이지짜리 PDF를 LLM에게 통째로 던지면 컨텍스트 윈도우가 터지거나 비용 폭탄을 맞겠죠.

OpenKB는 짧은 문서는 통째로 읽지만, 20페이지 이상의 긴 문서는 PageIndex 기반의 계층적 요약 트리를 만듭니다.

문서를 페이지 단위로 잘라 말단(Leaf) 노드로 요약합니다.
여러 페이지를 묶어 챕터 단위의 부모(Parent) 노드 요약을 만듭니다.
이를 합쳐 전체 문서의 루트(Root) 노드 요약을 완성합니다.

위키를 갱신할 때 LLM은 문서 전체를 다시 읽는 게 아니라 이 트리를 탐색합니다. "아, 이 개념은 2챕터의 세부 내용에 있네?"라며 필요한 부분만 딥다이브하는 구조라, 정확도는 높이고 토큰 낭비는 극적으로 줄입니다.

~~이렇게 보니 세그먼트 트리가 생각나서 PTSD가...~~

OpenKB는 내부적으로 Microsoft의 markitdown을 활용하여 문서를 강력하게 파싱(Parsing)합니다. 우리가 실무에서 다루는 거의 모든 포맷을 지원한다고 보시면 됩니다.

PDF 문서 (.pdf): 논문, 기술 명세서 등 (PageIndex 알고리즘 적용)
Office 문서 (.docx, .pptx, .xlsx): 기획서, 회의록은 물론 엑셀의 통계 자료를 마크다운 표로 변환하여 맥락을 유지합니다.
웹 및 텍스트 (.html, .md, .txt): 크롤링한 웹페이지나 기존의 메모장 파일들.
멀티모달 이미지: 시각 능력이 있는 LLM(GPT-4o 등)을 연결하면, 문서 내 다이어그램이나 표의 내용까지 텍스트로 풀어내어 위키에 반영합니다.

3. OpenKB는 어떤 방식으로 검색(Retrieve)하고 프롬프트를 구성할까?

전통적인 RAG 시스템은 질문이 들어오면 벡터 DB에서 가장 유사도가 높은 텍스트 조각(Chunk) 5~10개를 단순 추출합니다. 그리고 이를 프롬프트에 [조각1] [조각2] [조각3]... 형태로 무작정 이어 붙여서(Context Stuffing) LLM에게 던져주죠. 문맥이 뚝뚝 끊긴 파편화된 정보만 들어가다 보니, LLM이 엉뚱한 대답(환각)을 하거나 중요한 맥락을 놓치는 경우가 빈번합니다.

하지만 OpenKB는 '이미 LLM이 잘 정리해 둔 위키 페이지'를 검색의 대상으로 삼습니다. 검색 및 프롬프트 삽입 과정은 다음과 같이 매끄럽게 진행됩니다.

질문을 던졌을 때 "설마 생성된 수백 개의 위키 문서를 통째로 프롬프트에 다 넣는 건가요?"라고 생각하실 수 있습니다. 결론부터 말씀드리면 절대 아닙니다. 컨텍스트 윈도우 한계와 비용 문제가 발생하기 때문이죠.

여기서 OpenKB의 가장 큰 기술적 특징이 드러납니다. 기존 RAG의 흔한 벡터 유사도 검색(Vector Search)을 과감히 버리고, '에이전트 기반의 추론 탐색(Reasoning-based Retrieval)' 방식을 사용합니다.

1. 기계적 매칭이 아닌 'AI 에이전트의 직접 탐색'

기존 RAG는 질문을 수학적 벡터로 변환해 가장 거리가 가까운 텍스트 조각을 기계적으로 가져옵니다. 반면 OpenKB에서는 LLM 자체가 능동적인 사서(Agent)로 동작합니다. 내부적으로 PageIndex라는 계층적 트리 구조를 사용하기 때문에, 질문이 들어오면 LLM은 가장 먼저 위키의 전체 목차(Index)와 최상위 요약본을 훑어봅니다.

2. 꼬리에 꼬리를 무는 논리적 검색 과정 예를 들어 *"V2 아키텍처의 데이터베이스 이중화 구조를 설명해 줘"*라는 쿼리가 들어왔다고 가정해 봅시다.

1단계 (방향 설정):
- 사용자가 질문을 던지면, 잘게 쪼개진 원본 텍스트가 아니라 wiki/concepts/나 wiki/summaries/에 저장된 마크다운 파일 단위로 관련성을 찾습니다.
- 이미 개념별로 정리되어 있기 때문에 검색의 정확도 자체가 훨씬 높습니다.
- 즉, LLM이 요약 트리를 보고 "음, 데이터베이스 관련 질문이네. concepts/database_replication.md 문서가 핵심이겠군" 하고 스스로 판단합니다.
2단계 (문서 열람): 해당 마크다운 파일을 열어 읽습니다. 그런데 파일 안에 [[architecture_v2_요약.md]]라는 하이퍼링크(교차 참조)가 있는 것을 발견합니다.
3단계 (딥다이브): *"질문자가 V2 아키텍처의 디테일을 물었으니 저 링크를 따라가서 요약본도 마저 읽어야겠다"*라며 필요한 하위 문서를 추가로 열람합니다.

3. 통문맥 삽입 (Context Injection)

전체 위키를 프롬프트에 때려 넣는 것이 아닙니다. 위 탐색 과정을 통해 LLM이 스스로 가장 중요하다고 판단한 핵심 마크다운 파일(보통 1~3개)만 선별합니다. 그리고 이렇게 선별된 완성형 문서의 내용을 프롬프트에 백그라운드 지식으로 삽입합니다.

4단계 (구조화된 컨텍스트 통째로 삽입) : 연관성이 높다고 판단된 위키 페이지(예: database_replication.md)의 내용을 통째로 가져와 프롬프트에 삽입합니다. 이때 파일 내에 있는 [[다른_문서_링크]] 등의 메타데이터도 함께 들어가기 때문에 지식의 확장성도 유지됩니다.

OpenKB는 기계적인 수치 계산(벡터)으로 조각난 텍스트를 무작정 가져오는 것이 아니라, "AI가 사람처럼 직접 목차를 보고 필요한 백과사전 페이지를 찾아 읽은 뒤 답변하는 구조"입니다.
파편화가 일어나지 않으니 환각(Hallucination)이 극도로 적어지고, 일관성 있는 고품질의 답변이 가능해집니다.

4. 프롬프트 구성 예시 : 실제로 LLM에게 전달되는 백그라운드 프롬프트는 대략 이런 논리적 구조를 띕니다.

[System Message]
당신은 시스템에 구축된 지식 베이스(위키)를 바탕으로 정확하게 답변하는 AI 어시스턴트입니다. 
아래는 사용자의 질문과 관련하여 '이미 컴파일된' 위키 문서의 내용입니다. 
파편화된 정보가 아니므로 문서의 맥락을 그대로 유지하여 답변하세요.

[Context]
# Database Replication (데이터베이스 이중화)
## 개념 개요
시스템의 고가용성을 유지하기 위해... (중략)
## 문서별 교차 참조
* 초기 설정: 단일 구조...
... (선별된 마크다운 위키 파일의 내용 전체 삽입) ...

[User Message]
"새로운 아키텍처 V2에서 데이터베이스 이중화는 어떻게 처리했어?"

🔥 요약하자면: OpenKB가 프롬프트에 삽입하는 데이터는 찢어진 종이 조각들의 모음이 아닙니다. 이미 목차, 개념 정리, 충돌 사항(Lint)까지 완벽하게 정리된 '완성된 기술 블로그 포스트' 자체를 컨텍스트로 제공합니다. 덕분에 LLM은 헤매지 않고 전체 맥락을 완벽하게 꿰뚫은 상태에서 전문가처럼 일관성 있는 답변을 생성할 수 있습니다.

4. OpenKB 기본 세팅

이제 직접 구축해 볼까요? 로컬 환경이나 Docker 컨테이너 안에서 가볍게 띄워볼 수 있습니다만 저는 파이썬 가상환경을 기준으로 설명 하겠습니다.

Step 1: 설치 및 초기화 터미널을 열고 바로 설치해 줍니다.

pip install openkb

# 우리만의 위키 지식 베이스 폴더를 만듭니다.
mkdir lab-kb && cd lab-kb
openkb init

Step 2: API 키 설정 초기화를 하면 폴더 내에 .env 파일을 만들 수 있습니다. LiteLLM을 기반으로 동작하기 때문에 OpenAI, Claude 등 원하시는 걸 쓰면 됩니다. (가성비가 좋은 GPT-4o-mini나 Claude 3.5 Haiku를 추천합니다.)

# .env 파일 생성 후
OPENAI_API_KEY=sk-proj-본인의API키

Step 3: 문서 투입 및 컴파일 실제 우리가 가진 PDF, Word 문서 등을 집어넣습니다.

openkb add ./docs/architecture_v2.pdf
# 디렉토리 전체를 넣을 수도 있습니다.
openkb add ./manuals/

이때 콘솔을 보시면 LLM이 문서를 분석하고 위키를 컴파일하는 과정이 쫙 올라갑니다.

Step 4: 파이썬 API로 FastAPI 등에 연동하기 사내 챗봇이나 시스템에 붙일 때는 CLI 대신 파이썬 코드를 씁니다. 우리가 늘 짜던 FastAPI 라우터에 쉽게 녹일 수 있습니다.

from openkb import KnowledgeBase

# 아까 만든 폴더 경로를 연결합니다.
kb = KnowledgeBase("./lab-kb")

# 일반적인 일회성 질문 (저장 옵션을 주면 위키에 탐구 기록으로 남습니다)
answer = kb.query("새로운 아키텍처 V2에서 데이터베이스 이중화는 어떻게 처리했어?", save=True)
print(answer)

# 대화형 챗봇 형태가 필요하다면 session을 엽니다.
session = kb.chat()
session.ask("그럼 V1 아키텍처와 비교해서 가장 크게 달라진 점 3가지만 요약해 줘.")

실제 명령어 모음

openkb init	Initialize a new knowledge base (interactive) - 기본 세팅을 알아서 시작합니다.
openkb add <file_or_dir>	Add documents and compile to wiki - 적재를 시작합니다(.env에 API 키 필요)
openkb query "question"	Ask a question over the knowledge base (use --save to save the answer to wiki/explorations/) - 질문 입력 후 답변을 받아옵니다
openkb chat	Start an interactive multi-turn chat (use --resume, --list, --delete to manage sessions) - 멀티턴 채팅 시작
openkb watch	Watch raw/ and auto-compile new files - 기존 위키에 추가할 새로운 파일을 찾아서 적제 시작
openkb lint	Run structural + knowledge health checks - 실행 및 작동 확인
openkb list	List indexed documents and concepts - 원본 문서 / 요약 / concept를 확인
openkb status	Show knowledge base stats - 전체 요약(list는 실제 문서의 이름까지 나왔다면 status는 문서가 총 몇개인지로 요약)

5. 핵심: 실제 위키 파일은 어떻게 구성되고 저장될까?

많은 분들이 "그럼 대체 파일이 어떻게 저장되길래 위키라고 부르는 건가요?"라고 궁금해하실 텐데요. 문서를 추가하고 컴파일이 끝나면 폴더 구조가 아래와 같이 마크다운 파일들로 채워집니다.

wiki/
 ├── index.md           # 지식 베이스의 메인 대시보드
 ├── AGENTS.md          # LLM이 문서를 갱신할 때 참고하는 프롬프트/스키마 지침
 ├── summaries/
 │    └── architecture_v2_요약.md  # 투입한 문서별 단일 요약본
 ├── concepts/          # ⭐ 여기가 OpenKB의 핵심!
 │    ├── database_replication.md
 │    └── system_architecture.md
 └── explorations/      # 우리가 query 명령어로 남긴 심층 질의응답 기록들

가장 중요한 건 concepts/ 폴더입니다. 예를 들어 우리가 서로 다른 시기에 작성된 문서 3개를 넣었다고 가정해 봅시다. LLM은 이를 스스로 종합하여 concepts/database_replication.md라는 파일을 아래와 같이 작성해 냅니다.

[실제 생성되는 마크다운 파일 예시: concepts/database_replication.md]

# Database Replication (데이터베이스 이중화)

## 개념 개요
시스템의 고가용성을 유지하기 위해 메인 DB의 데이터를 예비 DB로 실시간 복제하는 아키텍처입니다.

## 문서별 교차 참조 및 발전 과정
* **초기 설정 (2024년)**: 단일 Primary-Secondary 구조를 사용했습니다. ([[architecture_v1_요약.md]] 참조)
* **V2 마이그레이션 (2025년)**: 트래픽 증가로 인해 Active-Active 이중화 클러스터로 개편되었습니다. 이때 Redis 캐시 계층이 새롭게 도입되었습니다. ([[architecture_v2_요약.md]] 참조)

## 주의 및 충돌 사항 (Lint 결과)
> **모순 감지**: V1 문서에서는 지연 시간이 5ms라고 명시되었으나, 최근 V2 문서에서는 데이터 동기화 지연이 15ms로 늘어났다고 보고되었습니다. 아키텍처 팀의 리뷰가 필요합니다.

## 관련 개념 (Links)
* [[system_architecture]]
* [[redis_caching_strategy]]

보이시나요? 단순히 문서를 찾아오는 게 아니라, 과거 문서와 최신 문서를 엮어서 하나의 잘 정리된 기술 블로그나 사내 위키 페이지를 스스로 만들어냅니다. 순수 마크다운 포맷이기 때문에, 이 폴더를 통째로 Obsidian(옵시디언) 같은 로컬 노트 앱으로 열면 페이지 간의 연결망이 어찌보면 지식그래프와 유사한 형태로 펼쳐집니다.

마치며

단순히 openkb lint 명령어 하나로 "지식 베이스에 끊어진 링크나 충돌하는 정보가 없는지" 검사할 수 있다는 점은, 시스템 유지보수를 밥 먹듯이 하는 개발자들에게 엄청난 편리함을 줍니다.

매번 GPT에게 같은 배경지식을 설명하느라 시간을 낭비하셨거나, 여러 프로젝트의 파편화된 정보를 체계적으로 모아두고 싶으시다면 OpenKB는 매우 훌륭한 무기가 되지 않을까 싶습니다.

또한, 지식그래프 도입이 부담스럽거나 관계 파악이 어려운 경우에 사용하면 완벽히 대체되진 않아도 쓸만한 방법이 아닐까 해요. 한가지 아쉬웠던점은 위키 생성 시 영어로 만든다는 것? 그래도 LLM이 이해하거나 토큰을 줄이기 위해서는 영어가 더 효율적이니 뭐...

Naive RAG, Knowledge Graph, OpenKB를 비교 분석하는 글은 조만간 추가로 적어보도록 하겠습니다. 감사합니다.

GitHub - VectifyAI/OpenKB: OpenKB: Open LLM Knowledge Base

OpenKB: Open LLM Knowledge Base. Contribute to VectifyAI/OpenKB development by creating an account on GitHub.

github.com

간략한 확인은 아래의 제 깃허브에서 가능합니다.

https://github.com/joo9906/RAG/tree/main/04_OpenKB

RAG/04_OpenKB at main · joo9906/RAG

RAG를 좀 더 파고들기 위해. Contribute to joo9906/RAG development by creating an account on GitHub.