OpenKB 설치 및 활용 가이드 — 지식베이스를 위한 최선의 선택

5월 07, 2026

OpenKB 설치 및 활용 가이드 — 지식베이스를 위한 최선의 선택

이번 포스팅에서는 제가 직접 설치하고 테스트한 OpenKB에 대해 자세히 알려드리려고 합니다.

1. OpenKB란 무엇인가?

OpenKB는 LLM과 PageIndex를 활용해 원본 문서를 구조화되고 상호 연결된 위키 스타일의 지식베이스로 자동 컴파일하는 오픈소스 CLI 시스템입니다.

핵심 철학: "매 쿼리마다 지식을 재생성하는 대신, 지식을 축적하고 지속적으로 관리하라."

Andrej Karpathy의 아이디어에서 영감을 받아, 기존 RAG(Vector DB) 방식의 한계를 극복했습니다.

전통적 RAG 대비 장점

구분	伝統적 RAG	OpenKB
지식 축적	매 쿼리마다 초기화	한번 생성된 위키 영구 유지
검색 방식	벡터 DB 기반	PageIndex 트리 인덱싱 (벡터리스)
모달리티	텍스트 중심	텍스트 + 표 + 그림 + 차트
지식 통합	문서별 격리	교차 참조 + 개념 통합

2. 핵심 기능

(1) 광범위한 형식 지원

PDF, Word, PPT, Excel, HTML, Markdown, 텍스트 등
markitdown을 통한 자동 변환

(2) 장문 문서 대응

20페이지 이상 PDF → PageIndex가 계층적 트리 생성
LLM이 전체 텍스트 대신 트리 경로 읽음

(3) 지식 컴파일 자동화

문서를 추가할 때 LLM이 다음을 자동 수행:

문서별 요약 페이지 생성 (summaries/)
기존 개념 페이지 탐색 (concepts/)
교차 문서 주제 간 연결 고리 형성
index.md 및 log.md 동기화

한번의 문서 추가 = 10~15개의 위키 페이지 갱신!

(4) Obsidian 호환성

[]wikilinks[] 기반 그래프 탐색
Obsidian에서 직접 열람 가능

(5) 다양한 운영 모드

openkb watch: raw/ 폴더 감지, 자동 컴파일
openkb lint: 구조/지식 건강 상태 체크
openkb chat: 대화식 세션 지원

3. 설치 및 초기 설정

3.1 설치

pip install openkb

3.2 초기화

mkdir my-kb && cd my-kb
openkb init

대화형 설정:

KB 이름 설정
모델 선택 (provider/model 형식)
언어 설정
API 키 입력

Ollama 사용자: API 키 없이 바로 진행 가능!

3.3 설정 파일

# .openkb/config.yaml
model: ollama/qwen3.6:latest
language: ko
pageindex_threshold: 20
base_url: http://localhost:11434/v1

4. 아키텍처

raw/                              ← 당신이 문서를 넣는 곳
 │
 ├─ 짧음 문서 ──→ markitdown ──→ LLM이 전체 텍스트 읽기
 │                                     │
 ├─ 긴 PDF(≥20페이지) ──→ PageIndex ──→ LLM이 문서 트리 읽기
 │                                     │
 │                                     ▼
 │                         Wiki 컴파일 (LLM에 의해)
 │                                     │
 ▼                                     ▼
wiki/
 ├── index.md            ← 지식베이스 요약
 ├── log.md              ← 운영 타임라인
 ├── AGENTS.md           ← 위키 스키마
 ├── sources/            ← 원본 문서 변환본
 ├── summaries/          ← 문서별 요약
 ├── concepts/           ← 교차 문서 개념 (가장 중요!)
 ├── explorations/       ← 저장된 쿼리 결과
 └── reports/            ← 린트 리포트

5. 기본 사용법

5.1 문서 추가

# 단일 파일 또는 폴더
openkb add paper.pdf
openkb add ~/papers/

# glob 패턴 지원
openkb add ./docs/*.pdf
openkb add ./research/   # 하위 폴더 모두

5.2 쿼리

# 일회성 쿼리
openkb query "핵심 개념은 무엇인가요?"

# 결과 저장
openkb query "핵심 개념은 무엇인가요?" --save
# → wiki/explorations/{date}_{n}.md 에 저장

5.3 대화형 채팅

openkb chat                       # 새 세션
openkb chat --resume              # 마지막 세션 계속
openkb chat --list                # 세션 목록
openkb chat --delete          # 세션 삭제

채팅 내 슬래시 명령어:

/help — 명령어 목록
/exit — 세션 종료
@sources — 소스 문서 확인
@concepts — 관련 개념 확인
/lint — 위키 상태 체크

5.4 자동화

# watch 모드: raw/ 폴더 감지 → 자동 컴파일
openkb watch

# 수동 일괄 컴파일
openkb add raw/

6. 고급 명령어

명령어	설명
`openkb init`	KB 초기화 (대화형)
`openkb add <file>`	문서 추가 및 컴파일
`openkb query "Q"`	지능형 질문 (LLM 기반 답변)
`openkb chat`	대화형 채팅
`openkb watch`	파일 감지 자동 컴파일
`openkb lint`	건강 체크
`openkb list`	인덱싱된 문서/개념 목록
`openkb status`	KB 스탯

7. 실제 설치 및 테스트 기록

설치 과정

# 1. GenericAgent clone
git clone --depth 1 https://github.com/lsdefine/GenericAgent.git genericagent-analysis

# 2. OpenKB 설치
pip install openkb

# 3. KB 초기화
mkdir my-kb && cd my-kb
openkb init
# model: ollama/qwen3.6:latest
# language: ko
# API 키 없음 (Ollama 사용)

# 4. 문서 추가
openkb add GenericAgent_README.md
openkb add OpenKB_README.md

# 5. 쿼리 테스트
openkb query "GenericAgent의 핵심 개념과 자기진화 방식은 무엇인가요?"

결과 파일 구조

my-kb/
├── .openkb/
│   ├── config.yaml            ← 설정 (model, language, base_url)
│   └── hashes.json            ← 파일 변경 감지
├── wiki/
│   ├── index.md               ← 위키 인덱스
│   ├── log.md                 ← 운영 로그
│   ├── sources/               ← 원본 문서 변환본
│   │   ├── GenericAgent_README.md
│   │   └── OpenKB_README.md
│   ├── summaries/             ← 문서별 요약
│   │   ├── GenericAgent_README.md
│   │   └── OpenKB_README.md
│   └── concepts/              ← 자동 생성된 개념들
├── raw/                       ← 원본 문서 추가 경로
└── .env                       ← LLM_API_KEY

8. 핵심 기술 스택

PageIndex: 벡터리스 장문 인덱싱
markitdown: 광범위한 문서 형식 변환
LiteLLM 다중 LLM 지원: OpenAI, Claude, Gemini, Ollama 등
Click: CLI 프레임워크
watchdog: 파일 감지 (watch mode)

9. 사용 시 장점

지식 축적 효과: 시간이 지날수록 지식이 커짐. 한 번 추가한 문서는 영구히 유지되고 통합됨
비용 효율: LLM API 사용량 절감 (한 번 컴파일, 여러 번 재사용)
정확한 탐색: 벡터 대신 트리 인덱싱으로 정확한 콘텐츠 위치 파악
교차 참조: 여러 문서 간 연결 고리 자동 형성
모달리티 네이티브: 표, 그림, 차트 등 비정형 데이터 통합 처리

10. 활용 패턴 (Best Practices)

작업별 Raw 폴더: 각 주제별 raw/ 폴더에 문서 정리
자동 컴파일: openkb add raw/로 일괄 처리 또는 openkb watch로 자동화
정기적 검증: openkb lint로 지식 일관성 확인
지식 검색: openkb query로 개념 간 synthesis 활용
지속성 유지: 정기적 위키 정리 및 개념 병합

결론

OpenKB는 "벡터베이스 없이도 강력한 지식베이스"를 구축할 수 있는 훌륭한 도구입니다. 특히:

장문 문서 처리 (PageIndex 트리 인덱싱)
Wiki 기반 지식 관리 (auto-compilation)
Obsidian 호환성 및 그래프 탐색

측면에서 기존 RAG 대비 명확한 장점이 있습니다.

작업 경험을 지식베이스로 축적하면, 시간이 지날수록 더 강력해지는 지식의 선순환을 경험할 수 있습니다.

관련 링크

이 블로그 검색

AI Agent와 함께하는 하루