llmwiki

01_LLM_Wiki_설계서

Properties2
tags지식, 지식위키설계
aliases04-지식/지식위키설계/01_LLM_Wiki_설계서, 04-지식/AI·자동화/01_LLM_Wiki_설계서, 04-지식/개발/AI·자동화/01_LLM_Wiki_설계서

19 min read

📚 개인 지식 위키 (LLM Wiki) 설계서 v2

한 줄 요약: 웹에서 스크랩한 자료를 로컬 LLM이 자동으로 정리·연결해주는 셀프호스트 개인 지식 위키. 새로 만들지 않고 기존 blog.example.com(Obsidian + Git + Quartz) 파이프라인을 그대로 재사용하여 1일 내 구축을 목표로 한다.

1. 프로젝트 개요 (Overview)

오픈소스만 조합하여, 웹에서 본 자료를 ① 스크랩 → ② 내 문서로 재작성 → ③ LLM이 위키로 정리 → ④ Git 형상관리 → ⑤ 웹/모바일에서 학습하는 개인 지식 순환 시스템을 만든다.

핵심 철학은 “수집은 쉽게, 정리는 자동으로, 학습은 어디서나”. 자료를 모으는 순간의 마찰을 최소화하고, 정리의 반복 노동은 LLM에게 위임하며, 결과물은 반응형 웹으로 언제 어디서나 다시 꺼내본다.

참고: 요청하신 안드레카파시 llm wiki.md 원문은 현재 vault에 없어, 본 설계서는 “LLM이 스크랩 원문을 요약·태깅·위키링크로 재구성해주는 컴포넌트”를 llm_wiki로 정의하여 진행한다. 원문 확보 시 §5.2에 세부 프롬프트/규칙을 보강한다.

2. 요구사항 정리 (Requirements)

구분요구사항설계 반영
F1. 웹 스크랩웹페이지를 스크랩하여 저장Obsidian Web Clipper (§5.1)
F2. 내 문서화스크랩 기반 나만의 문서 작성, 그 문서도 스크랩 가능Quartz 공개 페이지 = 재스크랩 가능 (§5.4)
F3. 크로스플랫폼모바일 + 웹 모두 지원Obsidian Mobile(입력) + Quartz 반응형(열람) (§6)
F4. LLM 정리스크랩 내용을 LLM으로 자동 정리Ollama 로컬 LLM + AI 플러그인 (§5.2)
F5. 형상관리Git으로 버전 관리기존 Git 파이프라인 재사용 (§5.3)
F6. 카테고리영어 / IT / 성경 / 독서 등폴더 기반 분류 (§5.5)
NF1. 셀프호스트집 미니PC 구동기존 myserver 재사용
NF2. 개인 도메인보유 도메인 활용wiki.example.com 서브도메인
NF3. 최소 개발1일 이내 완료기존 인프라 100% 재사용 (§3)

3. 설계 원칙: “만들지 말고 조립하라” (Design Principles)

1일 내 완료의 유일한 방법은 코드를 짜지 않는 것이다. 이미 검증된 4가지 자산을 그대로 재사용한다.

이미 있는 것 (재사용)새로 필요한 것 (최소)
✅ 미니PC 서버(myserver)⬜ Web Clipper 설치·템플릿 (30분)
✅ Git + GitHub 파이프라인⬜ Ollama + AI 플러그인 세팅 (2~3h)
✅ Quartz 빌드 + Webhook 자동배포⬜ 위키용 레포/서브도메인 연결 (1~2h)
✅ Cloudflare + Nginx (443 프록시)⬜ 카테고리 폴더·템플릿 구성 (30분)
✅ Obsidian vault (마크다운 = 단일 원천)⬜ 총 ≈ 반나절 실작업

새 백엔드·DB·프론트엔드를 일절 만들지 않는다. 마크다운 파일이 곧 DB이고, Quartz가 곧 프론트엔드다.

4. 시스템 아키텍처 (Architecture)

4.1. 데이터 흐름 (Data Flow)

                        ┌────────────── CAPTURE (수집) ──────────────┐
   [웹페이지]  ──클립──▶ │ Obsidian Web Clipper (PC/모바일 브라우저)   │
   [모바일 공유] ──────▶ │ Obsidian Mobile 공유시트                    │
                        └──────────────────┬──────────────────────────┘
                                           ▼  raw 마크다운(원문+출처)
                                    00_Inbox/ (미분류 수신함)
                                           │
                        ┌────────────── PROCESS (정리) ──────────────┐
                        │ Ollama (미니PC 로컬 LLM) + Obsidian AI 플러그인│
                        │  · 요약  · 태그  · [[위키링크]]  · 카테고리 분류 │
                        └──────────────────┬──────────────────────────┘
                                           ▼
                   카테고리 폴더 ( 영어 / IT / 성경 / 독서 … )
                                           │
                                   git commit & push
                                           │
                        ┌────────────── PUBLISH (학습 웹) ────────────┐
                        │ GitHub Webhook → 미니PC → `quartz build`     │
                        │ 그래프뷰 · 백링크 · 전문검색 (반응형: 웹+모바일)│
                        └──────────────────┬──────────────────────────┘
                                           ▼
                              https://wiki.example.com

4.2. 계층 구조 (Layers)

계층역할도구
Capture웹/모바일에서 자료를 마찰 없이 수집Obsidian Web Clipper, Obsidian Mobile
Process원문을 위키 형태로 자동 정리(llm_wiki)Ollama + AI 플러그인
Store단일 원천·버전 관리Markdown Vault + Git
Publish반응형 학습 웹으로 발행Quartz (기존 Webhook 배포)

5. 기술 스택 및 컴포넌트 상세 (Tech Stack & Components)

5.0. 오픈소스 선정 근거

후보장점채택 여부
Obsidian + Quartz(기존)이미 파이프라인 완성, 마크다운=Git 친화, 무료✅ 채택 (핵심)
Obsidian Web Clipper공식·무료, 마크다운 클립, 데스크톱/모바일✅ 채택 (수집)
Ollama로컬 LLM, API키 불필요, 미니PC 구동 가능✅ 채택 (정리)
Karakeep(구 Hoarder)AI 태깅+모바일앱 올인원🔸 대안 (§7) — 별도 스택이라 1일 초과 우려
Wallabag / Readeck읽기전용 스크랩❌ 위키 재작성/그래프 부재

결정: 신규 시스템(Karakeep 등)을 추가하면 별도 DB·배포가 생겨 1일을 넘긴다. 기존 vault+Quartz에 “수집”과 “정리”만 얹는다.

5.1. Capture — Obsidian Web Clipper

  • 설치: 브라우저 확장 프로그램(Chrome/Safari/Firefox) 설치 → vault 연결.
  • 동작: 웹페이지에서 클릭 → 본문을 마크다운으로 추출 → 00_Inbox/에 저장.
  • 템플릿: 프론트매터에 출처·수집일·상태를 자동 기입해 후속 처리를 준비한다.
---
title: "{{title}}"
source: "{{url}}"
clipped: "{{date}}"
category: inbox        # LLM이 이후 영어/IT/성경/독서로 교체
tags: [clipped]
status: raw            # raw → summarized → mynote
---
 
{{content}}

5.2. Process — llm_wiki (Ollama 로컬 LLM)

미니PC에 Ollama를 띄우고, Obsidian AI 플러그인이 00_Inbox/의 원문을 위키로 재구성한다.

  • 모델 예시: qwen2.5:7b 또는 llama3.1:8b (미니PC RAM에 맞춰 선택, 한국어 품질 우선).
  • AI 플러그인 후보: Copilot for Obsidian / Text Generator / Note Companion — Ollama 로컬 엔드포인트 연결 지원.
  • llm_wiki 처리 규칙(프롬프트 골자):
    1. 요약(TL;DR) 3~5줄 생성
    2. 핵심 개념 불릿 추출
    3. 관련 노트로 [[위키링크]] 자동 연결 (그래프 형성)
    4. #태그 부여 + category 프론트매터를 실제 카테고리로 교체
    5. 하단에 “✍️ 내 생각/정리” 빈 섹션을 남겨 F2(내 문서화)를 유도
[원문(raw)] ──Ollama──▶ [ TL;DR + 개념 + [[링크]] + #태그 + category 확정 + 내생각 섹션 ]
                                         │
                                  status: raw → summarized

핵심: LLM은 초안 정리까지만 한다. F2(“나만의 문서”)는 사용자가 “✍️ 내 생각” 섹션을 채우며 완성 → status: mynote. 이 페이지는 Quartz로 공개되므로 그 자체가 다시 스크랩 가능하다.

5.3. Store — Git 형상관리

  • vault 전체가 Git 레포. 카테고리별로 분리하거나 단일 레포로 운영.
  • 커밋 = 지식의 스냅샷. git log로 “언제 무엇을 배웠는지” 추적.
  • 기존 블로그와 동일한 push → Webhook → build 흐름을 그대로 사용 (80_blog/02 가이드 재활용).

5.4. Publish — Quartz 학습 웹

  • 별도 코드 없이 마크다운을 정적 사이트로 발행.
  • 학습에 최적: 그래프뷰(지식 연결 시각화) · 백링크 · 전문 검색 · 위키링크 내비게이션.
  • F2 충족: 발행된 페이지는 공개 웹 문서 → 타인/본인이 다시 클립(스크랩) 가능.

5.5. 카테고리 / 폴더 구조

knowledge-wiki/           # (신규 레포 or 기존 vault 하위)
├── 00_Inbox/             # Web Clipper 수신함 (미분류)
├── 10_English/           # 영어
├── 20_IT/                # IT
├── 30_Bible/             # 성경
├── 40_Reading/           # 독서
├── 90_Templates/         # 클립/노트 템플릿
└── quartz.config.ts      # (Quartz 발행 설정)

카테고리 추가는 폴더 하나 생성이 전부. LLM 프롬프트의 분류 목록에 한 줄 추가하면 자동 라우팅 대상이 된다.

6. 크로스플랫폼 전략 (Cross-Platform)

상황입력(수집/작성)출력(열람/학습)
데스크톱Web Clipper 확장 + Obsidian 앱wiki.example.com (또는 Obsidian)
모바일모바일 브라우저 Web Clipper / 공유시트 → Obsidian Mobilewiki.example.com 반응형 웹
  • 열람 통일: Quartz 정적 사이트는 반응형이라 모바일/PC 브라우저 하나로 커버 → 별도 앱 개발 불필요.
  • 동기화: vault를 Git(또는 iCloud/Obsidian Sync)으로 동기화하면 모바일 작성분도 미니PC 처리 파이프라인에 합류.

7. 대안 아키텍처 (Alternative)

1일 제약을 완화할 수 있다면 검토할 올인원 경로.

Karakeep(구 Hoarder) — 셀프호스트 read-it-later + AI 자동 태깅 + 모바일 앱 + 브라우저 확장 + Ollama 연동.

  • 장점: 수집·저장·AI태깅·모바일앱이 이미 통합.
  • 단점: 별도 DB/컨테이너 배포 필요, 마크다운·Git·그래프뷰 기반 “위키/학습” 경험은 Quartz 대비 약함.
  • 권장: 우선 §4 안으로 1일 MVP를 띄운 뒤, 수집 마찰이 크면 Capture 계층만 Karakeep로 교체 검토.

8. 1일 구축 계획 (One-Day Build Plan)

시간작업산출물
09:00–09:30위키용 GitHub 레포 생성 + 카테고리 폴더/템플릿knowledge-wiki 레포
09:30–11:30Quartz 세팅 + wiki.example.com 서브도메인 + Webhook 등록 (80_blog/02 재활용)배포 자동화
11:30–12:00Obsidian Web Clipper 설치 + 클립 템플릿 연결수집 동작
13:00–15:30Ollama 설치 + 모델 pull + AI 플러그인 연결로컬 LLM
15:30–17:00llm_wiki 프롬프트 튜닝 (요약/태그/링크/분류)정리 자동화
17:00–18:00E2E 테스트: 웹 클립 → LLM 정리 → push → 발행 확인MVP 완성

버퍼 포함 반나절~하루. 막히면 §5.2(LLM 정리)를 후순위로 미루고 수집→발행부터 살린다.

9. 향후 확장 로드맵 (Roadmap)

  • 자동 정리 파이프라인: 00_Inbox 감시 → Ollama 배치 정리 → 자동 커밋 (cron/워커).
  • 복습 루프: 태그/난이도 기반 스페이스드 리피티션(예: #review/D+7) 쿼리로 학습 강화.
  • 의미 검색: 임베딩 인덱스로 “비슷한 노트 찾기” (Smart Connections 등).
  • RSS/뉴스레터 자동 수집: 관심 소스 자동 클립 → 주간 요약.

10. v1 → v2 설계 변경 요약

항목v2 결정
개발 범위신규 시스템 구축 → 기존 블로그 파이프라인 재사용으로 전환 (1일 제약 충족)
저장소전용 DB → 마크다운 + Git (단일 원천)
프론트엔드자체 웹앱 → Quartz 정적 사이트(반응형, 앱 개발 제거)
LLM외부 API → Ollama 로컬(셀프호스트·비용 0·프라이버시)
크로스플랫폼네이티브 앱 → 반응형 웹 + Obsidian Mobile

11. 대안 설계 B: Karakeep 하이브리드 (권장) 🔥

기본안(§4)에서 수집 계층만 Karakeep으로 교체한다. 나머지(Git·Quartz 학습 웹)는 그대로 유지하여, 요구사항을 가장 균형 있게 충족한다.

11.1. 왜 하이브리드인가

  • 문제: 기본안의 수집(Obsidian Web Clipper + 모바일 공유)은 모바일에서 마찰이 크고, 영상·이미지·PDF 스크랩이 약하다.
  • 해결: Karakeep은 네이티브 iOS/Android 앱 + 브라우저 확장 + 전체페이지 아카이브(monolith) + OCR + 영상보관(yt-dlp) + Ollama AI 자동태깅/요약을 이미 갖춘 수집 특화 도구다.
  • 유지: 단, Karakeep은 DB 기반이라 Git(F5)과 위키 그래프가 없다. 그래서 수집만 맡기고, 영구 저장·형상관리·학습 웹은 기존 vault+Quartz가 담당한다.

11.2. 아키텍처 (Data Flow)

   [웹/모바일]
        │  브라우저 확장 · iOS/Android 앱 · 공유시트
        ▼
┌──────────────── Karakeep (미니PC, Docker) ────────────────┐
│  · 전체페이지 아카이브 · OCR · 영상보관                       │
│  · Ollama AI 자동 태그 + 요약 + 리스트(카테고리) 분류          │
└───────────────────────┬───────────────────────────────────┘
                         │  Karakeep REST API (tag=to-wiki 필터)
                         ▼
        [Bridge 스크립트] (cron, 미니PC)  ★유일한 신규 개발
          Karakeep 항목 → 마크다운 변환 → 00_Inbox/ 저장
                         │
        (선택) Obsidian AI 재정리 + "✍️ 내 생각" 작성 (F2)
                         │
                 git commit & push
                         │
        GitHub Webhook → `quartz build` → https://wiki.example.com

11.3. 컴포넌트 역할 분담

컴포넌트역할요구사항
Karakeep수집 프론트엔드(모바일앱·아카이브·AI 선처리) = 임시 수집함F1·F3·F4
Bridge 스크립트Karakeep API → 마크다운 → vault. DB를 Git 원천으로 전환F5
Obsidian내 문서 작성(“내 생각” 채우기)F2
Git형상관리 (영구 원천)F5
Quartz학습 웹(그래프·백링크·검색, 재스크랩 가능)F2·F6

저장소 원칙: Karakeep = 휘발 가능한 임시 수집함, vault+Git = 영구 단일 원천. Bridge는 단방향(Karakeep→vault), 임포트 완료 항목은 Karakeep에서 exported 태그 처리해 중복 방지.

11.4. Bridge 스크립트 골자

미니PC에서 cron으로 주기 실행. Karakeep REST API로 to-wiki 태그가 붙은 신규 항목을 가져와 마크다운으로 떨군다.

# bridge.py  (cron: */15 * * * *)
# 1) Karakeep API에서 tag=to-wiki, 미처리 항목 조회
# 2) 각 항목 → 프론트매터(title/source/tags/summary) + 본문(요약+아카이브) 마크다운 생성
# 3) 카테고리(리스트/태그) → 폴더 라우팅: 10_English / 20_IT / 30_Bible / 40_Reading
# 4) 00_Inbox/ 또는 해당 카테고리 폴더에 저장
# 5) git add/commit/push  (→ 기존 Webhook이 Quartz 빌드)
# 6) Karakeep 항목에 'exported' 태그 부여 (재임포트 방지)
  • 인증: Karakeep API 키(헤더). 미니PC 내부 통신이라 노출면 최소.
  • 카테고리 매핑: Karakeep의 리스트/태그를 그대로 폴더로 변환 → §5.5 구조 재사용.

11.5. 기본안(A) vs 하이브리드(B) 비교

항목A. 기본(Obsidian Clipper)B. Karakeep 하이브리드
모바일 수집🔸 공유시트(마찰↑)✅ 네이티브 앱
스크랩 범위텍스트 위주✅ 전체보관·OCR·영상
AI 자동정리🔸 임포트 후 수동 트리거✅ 수집 즉시 자동
Git 형상관리✅✅ (Bridge 경유)
운영 복잡도✅ 단순(1스택)🔸 +Karakeep +Bridge
신규 개발거의 없음Bridge 스크립트(반나절)
1일 완료✅ 여유🔸 빠듯(버퍼↓)

11.6. 구축 계획 델타 (기본안 §8 대비 추가분)

추가 작업소요
Karakeep docker compose 기동 + Ollama 연결1h
브라우저 확장 + 모바일 앱 로그인0.5h
Bridge 스크립트 작성 + cron 등록2~3h
E2E: 모바일 클립 → AI태그 → Bridge → 발행0.5h

기본안 대비 +4시간 안팎. 하루에 가능하나 버퍼가 적으니, 막히면 §5.2(Obsidian AI 재정리)를 후순위로 미루고 Karakeep→Bridge→Quartz 최소 경로부터 살린다.

11.7. 이 구조가 맞는 경우 / 아닌 경우

  • ✅ 맞음: 모바일에서 자주 담고, 스크랩 대상이 무겁다(영상·이미지·PDF·긴 아티클), 수집량이 많다.
  • ❌ 오버킬: 가벼운 텍스트 메모 위주 → 기본안(A)이 더 단순하고 빠르다.

한 줄 평: > “수집은 Karakeep에게, 기록과 학습은 내 Git 위키에게 — 각자 잘하는 걸 맡긴다.”

그래프 뷰

백링크