교재PDF에서 LLM-Wiki까지 — Docling 품질 선별 승격 파이프라인
스쿨셰프
2026.07.29
# [사례글] 교재 PDF에서 LLM-Wiki까지 — Docling 품질 선별 승격 파이프라인 구축기
> **작성일:** 2026-07-29
> **작성자:** SkoolChef LLM-Wiki 운영
> **관련 정본:** `CLAUDE.Governance.llm-wiki.md` · `DOCLING/050-scripts/` · `070-schema/ingest-policy.md`
---
### QA와 품질 점수
|**QA** (품질 보증)|**품질 점수**(`quality-scorer`)|
|---|---|---|
|**질문**|「깨진 링크·개수 오류 없나?」 | 「내용이 좋은 노트인가?」 |
|**결과**|OK/FAIL/NEEDS_REVIEW / CHECKLIST_PENDING | 0~100점, BEST·FULL·REVIEW |
|**비유**|공장 **출하 검사**|상품 **등급 분류** (A급만 골라 포장)|
**QA는 Quality Assurance의 약어입니다. 품질 보증 또는 품질 관리라고 부릅니다.**
---
## 소개
### 시도하고자 했던 것
경제학 교재 PDF를 Docling(문서 가공 도구)으로 가공한 뒤, 그 결과물을 SkoolChef LLM-Wiki(Obsidian vault·지식 창고)에 안전하게 넣는 지식관리(KM, Knowledge Management) 파이프라인을 만들고 싶었습니다.
구체적으로는 다음을 목표로 했습니다.
1. Docling `outbox`(가공 결과 대기함)에 쌓인 수백~수천 개의 마크다운(.md) 을 체계적으로 분류하고 품질을 점검한다.
2. 위키에 넣을 때 전부 복사하지 않고, 품질이 좋은 문서만 선별한다.
3. 매일 아침 Mac이 자동으로 QA(품질 보증)·재정제·품질 점수를 계산하고, 사람은 승인·검토만 한다.
4. 나중에도 헷갈리지 않도록 운영 규칙을 문서 하나(`CLAUDE.Governance.llm-wiki.md`)에 모은다 — 이 문서가 KM 운영 SSOT(단일 정본)이다.
### 그 이유
처음에는 `promote-manager.py`가 phase-23 **vault**의 806개 파일을 통째로 `010-raw/inbox/`(위키 수신함)에 복사했습니다.
이 방식은 빠르지만 문제가 많았습니다.
| 문제 | 왜 심각한가 |
|---|---|
| 저품질·파편 문서까지 inbox에 쌓임 | Obsidian 검토 부담 폭증 |
|`ingest-policy.md`§F위반|「outbox 일괄 wiki 복사 금지·선별·승인 후inbox만」 |
| FAIL / NEEDS_REVIEW corpus|아침 알림만 오고 수동으로 .md고치기반복 |
| 폴더·용어 혼란 | `misi`/`gesi`/`ie200` vs `micro-economics` 등 corpus(과목 묶음) 이름 불일치 |
「공장(Docling) → 검사(QA) → 선별 포장 → 창고(LLM-Wiki)」흐름이 필요했고, 그 경계를 코드와 문서로 고정하려 했습니다.
---
## 진행 방법
### 사용한 도구
| 도구 | 역할 |
|---|---|
| Cursor (Agent) | AI 코딩 도우미. 파이프라인 설계·Python/Bash 스크립트 구현·Governance 문서 작성 |
| Docling | 교재 PDF → phase 1~24 단계별 가공 (프로젝트: `CLAUDE/PROJECTS/DOCLING/`) |
| SKOOLCHEF-LLM-WIKI|Obsidian vault·`010-raw/inbox`·`030-wiki` |
| macOS launchd | Mac 스케줄러.매일 09:00자동실행 (`setup-schedule.sh`)|
| Python 3| QA·품질점수·승격 스크립트 (별도 라이브러리 없이 stdlib only) |
| Obsidian | 최종 내용·링크를 사람이 눈으로 검토하는 앱 |
### 전체 구조 (한눈에)
```text
[Docling 공장] [자동 검사] [사람 선택] [위키]
교재 PDF → phase-23 vault → QA + 재정제 → promote-select → Obsidian 검토
(수백~수천 md) 품질 점수표 BEST/FULL 선택 030-wiki 이동
```
- vault: Docling이 만든 개념 노트 묶음 폴더
- QA: Quality Assurance — 구조·링크·개수 검사
- promote-select: 「어떤 등급까지 위키 inbox에 복사할지」 사람이 고르는 도구
- 030-wiki: 최종 공개·MoK 동기화 대상 폴더
### Cursor에 요청한 핵심 프롬프트 (요약)
아래는 실제 작업 흐름을 반영한 **대표 프롬프트**입니다.한 번에 다 넣기보다,단계별로 나눠 요청했습니다.
1) 문제 인식 · 계획 수립
promote-manager.py가 phase-23 vault 전체 806개 md를 010-raw/inbox에 그대로 복사한다.
ingest-policy §F 「outbox 일괄 wiki 복사 금지」를 위반한다.
품질 점수 기반 자동 선별 + 관리자 라디오 체크리스트로 재설계하자. plan 활용해.
2) 품질 점수 · 승격 구현
Implement the plan: quality-scorer.py, promote-select.py,
promote-manager.py auto 수정, qa-auto-pipeline.sh Step 4 수정, PIPELINE-MAP 업데이트.
BEST = Tier A + score≥80, FULL = score≥60.
3) 자동 재정제
FAIL/NEEDS_REVIEW corpus는 자동으로 정제 1회 추가 진행 후
OK 또는 CHECKLIST_PENDING으로 올리자. 1회 후에도 안 되면 그대로 두고 다음 단계 진행.
아침 알림 → 수동 .md 수정 경로는 기본이 아니게 하자.
4) Governance 정본
CLAUDE.Governance.llm-wiki.md 파일을 SKOOLCHEF-LLM-WIKI에 두고,
앞으로 지식관리 운영상 중요 결정을 명시하는 SSOT로 만들고 참조 연결하자.
### 구현한 스크립트 (역할 요약)
| 파일 | 하는 일 |
|---|---|
|`qa-batch-report.py`|phase-24 전 corpus QA리포트 생성. 판정: OK / CHECKLIST_PENDING /FAIL/NEEDS_REVIEW|
|`qa-auto-repair.py`|FAIL·NEEDS_REVIEW corpus 문서 재정제 1회 (파편 문장 제거 + phase-24 메타 재생성)|
|`qa-auto-pipeline.sh`|QA + 재정제 + 품질 점수를 매일 아침 한 번에 실행하는 쉘 스크립트 |
|`quality-scorer.py`|concept(개념) 문서마다 0~100점· BEST/FULL/REVIEW 등급부여 |
|`promote-select.py`|터미널 라디오 UI(1=BEST, 2=FULL,3=CUSTOM) →inbox에만 복사|
|`setup-schedule.sh`|launchd 등록 (기본 매일 09:00) |
**경로:** `CLAUDE/PROJECTS/DOCLING/050-scripts/`
#### QA 리포트가 저장되는 곳
DOCLING/020-outbox/_qa-batch-report/
YYYY-MM-DD_HH-MM-SS_qa-batch-report.md ← 사람이 읽는 요약
{corpus}_quality-report.json ← 품질 점수 상세
QA= Quality Assurance(품질 보증). 「이 corpus, 위키에 넣어도 될 구조인가?」를 점검한 일일 검사표입니다.
### QA 판정 한 줄 설명
| 판정 | 의미 (초보자용) |
|---|---|
| OK| 자동 검사 통과 + Obsidian 체크리스트도 완료 |
| CHECKLIST_PENDING | 자동 검사는 대체로 OK. 사람이 Obsidian에서 13항목만 확인하면 됨 |
| NEEDS_REVIEW| 개수 불일치 등 구조 문제 → `qa-auto-repair` 자동 재정제 대상 |
| FAIL| 더 심각한 실패 |
### 품질 점수 기준 (0~100점)
`quality-scorer.py`가 **「내용이 좋은 노트인가」** 를 점수로 매깁니다. (QA와는 별개)
| 항목 | 배점 | 의미 (초보자용) |
|---|---:|---|
| 교재 내 등장 빈도·챕터 수 | 40 | 자주 나오는 핵심 concept(개념)일수록 높음 |
| Tier A/B | 20 | phase-10에서 매긴 중요도 등급 (A가 더 핵심) |
| 굵은 글씨 정의(`...`) | 15 | 「이게 뭔지」 한 줄 정의가 있는지 |
| 개념 간 링크 (crosslink) | 10 | 다른 concept과 wikilink로 연결됐는지 |
| 교재 섹션 링크 5개 이상 | 10 | 근거가 풍부한지 |
| definitions 파일 존재 | 5 | 정의 초안 파일이 있는지 |
승격 등급 (2026-07-29 확정) — `promote-select.py`에서 고르는 옵션
| 옵션 | 조건 | 예상 규모 (micro-economics 기준) |
|---|---|---|
| (1) BEST[추천] | Tier A + 점수 ≥80 | 약 2~7개/corpus |
| (2) FULL| 점수 ≥60 (BEST 포함) | 약 16~26개/corpus |
| (3) CUSTOM| 터미널에서 파일마다 y/n 직접 선택 | 원하는 만큼 |
| REVIEW| 60점 미만 | 기본 승격 대상 아님 (CUSTOM으로만 선택 가능) |
### 실제로 실행한 명령어
매일 자동 (등록 1회)
cd ~/Desktop/WORKSPACE_CLEAN/CLAUDE/PROJECTS/DOCLING
bash 050-scripts/setup-schedule.sh
**수동 전체 파이프라인 (승격 제외)**
```bash
cd ~/Desktop/WORKSPACE_CLEAN/CLAUDE/PROJECTS/DOCLING
bash 050-scripts/qa-auto-pipeline.sh
```
**단계별**
```bash
# 1) QA 리포트 (Quality Assurance — 품질 보증 검사)
python3 050-scripts/qa-batch-report.py
# 2) 문제 corpus 자동 재정제 (필요 시)
python3 050-scripts/qa-auto-repair.py
# 3) 품질 점수표 (0~100점, BEST/FULL/REVIEW)
python3 050-scripts/quality-scorer.py --show
# 4) 관리자 승격 — BEST 권장 (실제 복사 전 --dry-run 권장)
python3 050-scripts/promote-select.py micro-economics
python3 050-scripts/promote-select.py micro-economics --dry-run
```
**스케줄 즉시 테스트 (launchd)**
```bash
launchctl start com.docling.qa-auto-pipeline
```
### LLM-Wiki 폴더 구조 (숫자 접두)
숫자가 작을수록 **처리 전·가까운** 단계, 클수록 **완성·최종** 단계입니다.
| 폴더 | 역할 |
|---|---|
| `010-raw/inbox/{corpus}/` | Docling에서 선별 복사된 후보 문서 (검토 정본 경로) |
| `010-raw/sources/` | 처리 완료 원본 불변 보관 |
| `020-review/`| wiki 편입 전 대기소 (보조)|
| `030-wiki/` | 최종 지식 (Obsidian·MoK 동기화 대상)|
| `070-schema/ingest-policy.md`|vault 「헌법」 —무엇을 어디에 넣을 수 있는지 규칙|
### 캡처·이미지 안내 (직접 첨부 권장)
사례글을 커뮤니티에 올릴 때 아래 화면을 캡처하면 독자가 이해하기 쉽습니다.
| # | 캡처 대상 | 파일/위치 |
|---|---|---|
| 1 |QA 배치 리포트 요약표|`DOCLING/020-outbox/_qa-batch-report/*_qa-batch-report.md`|
| 2 |품질 점수 테이블|`python3 050-scripts/quality-scorer.py micro-economics --show` 터미널|
| 3 |promote-select 라디오UI|`python3 050-scripts/promote-select.py`실행화면|
| 4 | Obsidian inbox 폴더 트리|`010-raw/inbox/{corpus}/concepts/`(승격 실행후)|
| 5 | Governance 문서 목차 | `CLAUDE.Governance.llm-wiki.md` §1~§5 |
---
## 결과와 배운 점
### 무엇이 달라졌나
| Before | After |
|---|---|
| 806개 전량 inbox 복사 | BEST 기준 수 개~수십 개만 선별 복사 |
| FAIL 시 「.md 열어서 수동 수정」 | qa-auto-repair 자동 재정제 → 재검증 |
| 운영 규칙이 대화·코드에 흩어짐 | `CLAUDE.Governance.llm-wiki.md` 한곳에 SSOT |
| 아침 알림 = 곧 수동 작업 | 알림 = 재정제 후에도 미해결일 때만 |
검증 예시: `macro-economics-700` corpus에서 파편 bullet 36건 → 재정제 후 0건, QA 판정 NEEDS_REVIEW → CHECKLIST_PENDING으로 개선.
### 나만의 꿀팁
1. 자동화 경계를 명확히— Mac은 「QA·점수표」까지, 사람은 「승격·Obsidian·030-wiki 이동」만.
2. BEST부터 시작— 처음에는 (1) BEST만 넣고 품질 확인 후 FULL을 고려.
3. `--dry-run` 활용 — `promote-select.py --dry-run --all-best` 로 실제 복사 없이개수만 확인.
4. 리포트 폴더 북마크 — `020-outbox/_qa-batch-report/` 만 보면 하루 QA 상태 파악 가능.
5. Governance §9에 결정 로그 — 「왜 80점으로 올렸지?」를 미래의 나를 위해 남김.
### 시행착오
| 시행착오 | 원인 | 해결 |
|---|---|---|
| `qa-auto-repair` 후에도 NEEDS_REVIEW | `definitions/` 폴더 없는 corpus에서 정의 수 0으로 집계 | vault 구조에 맞게 definitions = concepts 수로 보정 |
| 재정제가 두 번째부터 안 됨 | corpus당 영구 1회 제한 | pipeline 실행마다 1회 (`--pipeline-id`) 로 변경 |
| corpus-first 심볼릭 링크후 QA 5개만 잡힘 | `qa-batch-report`가 symlink 중복 집계 | 실제 디렉터리만 스캔하도록 수정 |
| `phase-` 접두 폴더명 너무 김 | 28,650+ 하드코딩 경로 | corpus-first 심볼릭 링크 뷰 추가 (이름 변경 대신) |
### 아직 도움이 필요한 부분
- Obsidian → `030-wiki/` 이동 은 여전히 수동. (의도적 — wiki 품질 최종 관문)
- broken link(깨진 링크)가 있는 corpus는 자동 재정제만으로는 안 될 수 있음 → 수동 phase 재실행 검토.
- 캡처·스크린샷 은 운영 문서에 아직 미비 — 커뮤니티 게시용으로 보강 예정.
### 앞으로의 계획
1. `promote-select` 실행 후 `020-review/` 심볼릭 링크 자동 생성 (선택).
2. Obsidian 체크리스트 완료 시 corpus 상태를 `docling_fin/index.json`에 반영.
3. `030-wiki/` 편입 시 `_ops/promote-document.py approve` 와 연계 검토.
4. 경제학 5개 corpus에 대해 BEST 승격 1회 실전 후 Governance §9에 결과 기록.
---
## 도움 받은 글 (옵션)
| 참고 | 내용 |
|---|---|
|Karpathy LLM Wiki | wiki를 flat 구조 + wikilink로 운영하는 기본 철학 |
|프로젝트 내부 `070-schema/ingest-policy.md`| raw → wiki 헌법, Docling §F 「일괄 복사 금지」 |
|`DOCLING/.cursor/skills/docling-pipeline/PIPELINE-MAP.md`| phase 1~42 타임라인·스크립트 맵 |
|Cursor Agent + Plan 모드| 대규모 파이프라인을 단계별 todo로 쪼개 구현 |
---
## 부록: 하루 타임라인 (최종본)
```text
[전날 밤]
Docling phase 1~24 가공 완료
[매일 09:00 — Mac 자동 (launchd)] qa-auto-pipeline.sh
Step 1 QA 리포트 (Quality Assurance — 품질 보증 검사)
Step 1.5 FAIL/NEEDS_REVIEW → qa-auto-repair 자동 재정제 1회 → 재검증
Step 3 재정제 후에도 미해결 시에만 macOS 알림
Step 4 quality-scorer → 품질 점수 리포트 (BEST/FULL/REVIEW)
[관리자 — 원할 때]
1) (알림 받았을 때만) _qa-batch-report/ 최신 .md 확인
2) python3 050-scripts/promote-select.py → (1) BEST
3) Obsidian: 010-raw/inbox/{corpus}/ 검토
4) 승인 → 030-wiki/ 이동
```
---
## 부록: 관련 파일 경로
```text
SKOOLCHEF-LLM-WIKI/
CLAUDE.Governance.llm-wiki.md ← KM 운영 SSOT (단일 정본)
010-raw/inbox/ ← 승격 후보 (inbox)
030-wiki/ ← 최종 지식
docs/KM-CASE-STUDY-20260729-docling-to-llm-wiki.md ← 이 사례글
DOCLING/
050-scripts/qa-auto-pipeline.sh
050-scripts/qa-batch-report.py ← QA (Quality Assurance) 리포트
050-scripts/quality-scorer.py
050-scripts/promote-select.py
020-outbox/_qa-batch-report/ ← QA·품질 리포트 저장 폴더
```
## 용어·약어 사전 (초보자용)
이 사례글에는 IT·지식관리 용어가 많이 나옵니다. **처음 보는 단어는 여기서 찾아보세요.**
| 약어·용어 | 풀어 쓰면 | 이 글에서의 의미 |
|---|---|---|
| **QA** | **Quality Assurance** (품질 보증·품질 관리) | Docling 산출물이 **깨지지 않았는지·구조가 맞는지** 자동 검사하는 단계. `qa-batch-report.py`가 매일 리포트를 만듦 |
| **KM** | **Knowledge Management** (지식 관리) | 노트·문서를 모으고, 정리하고, 위키에 반영하는 전체운영|
| ChatGPT·Claude 같은 AI. 여기서는 **LLM이 읽기 좋은 위키**를 만든다는 뜻으로 씀 |
| **LLM-Wiki** |LLM용 위키| SkoolChef 프로젝트의 Obsidian 지식 창고 (`SKOOLCHEF-LLM-WIKI/`) |
| **vault** |금고·보관함|Obsidian에서 **한 프로젝트 폴더 전체**를 부르는 말. LLM-Wiki vault = 위키 폴더 통째|
|**outbox**|발송 대기함|Docling **공장 밖**에 쌓인 가공 결과물.아직 위키에 넣기 전 단계 |
|**inbox**|수신함|위키 **안**의 `010-raw/inbox/`—검토·승인 대기중인 문서가 들어가는 곳 |
| **corpus** | 말뭉치·묶음 | 교재 한 권(또는 한 과목) 단위 묶음. 예: `micro-economics` (미시경제학) |
| **phase** | 단계 | Docling 파이프라인의 작업 순서. phase-23 = 개념 노트 vault, phase-24 = QA 단계 |
| **SSOT** | **Single Source of Truth** (단일 정본) | 「이건 여기 문서가 맞다」고 정해 둔 **공식 기준 문서** 하나 |
| **Governance** | 거버넌스·운영 규칙 | 누가 무엇을 어떻게 할지 정한 **운영 헌법** 문서 |
| **Obsidian** | 옵시디언 | 마크다운 노트를 링크로 연결해 보는 **데스크톱 메모 앱** |
| **MoK** | **Map of Knowledge** (지식 지도) | LLM-Wiki를 브라우저에서 탐색하는 UI (Mother of Knowledge 계열) |
| **Docling** |독링|PDF등을 구조화된 마크다운으로 바꾸는 **문서 가공 파이프라인**프로젝트 |
| **BEST/FULL/REVIEW**|승격 등급 이름|BEST=핵심만, FULL=넓게,REVIEW=점수 낮아 보류·직접 선택|
| **Tier A/B**|등급|개념의 **중요도** (A가 더 핵심). Docling phase-10에서 부여
| **FAIL**|실패|QA에서 **자동 검사 통과 못 함**|
| **NEEDS_REVIEW**| 검토 필요 | 구조·카운트 등 **문제가 있어 사람·재정제가 필요** |
| **CHECKLIST_PENDING** | 체크리스트 대기 | 자동 검사는 대체로 OK, **Obsidian에서 사람이 13항목 체크**만 남음 |
| **launchd** | 런치디 | macOS **예약 실행** (매일 09:00에 스크립트 자동 실행) |
| **CLI** | **Command Line Interface** | 터미널에서 `python3 ...` 처럼 **명령어로 실행**하는 방식 |
| **dry-run** | 모의 실행 | **실제 복사·저장 없이** 결과만 미리 보기 (`--dry-run`) |
| **wikilink** | 위키 링크 | `[[수요]]` 처럼 다른 노트로 연결하는 Obsidian 링크 |
---
*이 문서는 2026-07-29 Docling 품질 선별 승격 파이프라인 구축 작업을 바탕으로 작성되었습니다. 운영 규칙의 최신 정본은 항상 `CLAUDE.Governance.llm-wiki.md`를 따릅니다.*
로그인하고 댓글을 남겨 주세요
DECK2026.08.07
806개 파일을 한꺼번에 옮긴 방식은 결국 사람의 수정 부담을 크게 남겼습니다. 그래서 한 묶음씩 검사하고 사람이 골라 올리도록 바꾼 뒤, 파편 항목 36건이 사라진 결과가 더 반갑고요. 매일 쌓이는 후보를 고르는 실제 화면이 곁들여지면 선택 기준도 더 와닿겠네요.


교재 PDF를 inbox에서 LLM-Wiki로 승격시키는 과정을 QA(품질 보증)와 품질 점수라는 두 축으로 나눠 설계하신 부분이 명확합니다. '깨진 링크·개수 오류 없나'와 '내용이 좋은 노트인가'를 서로 다른 질문으로 분리해 각각 스크립트를 배정하신 구조가 체계적입니다.
0~100점으로 채점해 BEST/FULL/REVIEW로 등급을 나누고, FAIL·NEEDS_REVIEW corpus는 자동 재정제를 1회만 시도한 뒤 그래도 안 되면 그대로 두고 다음 단계로 넘어가게 하신 규칙이 실용적입니다. 아침 알림을 받고 수동으로 .md를 고치는 반복 작업을 기본 경로에서 빼기로 한 결정도 자동화의 방향을 잘 잡은 것 같습니다.
CLAUDE.Governance.llm-wiki.md를 단일 정본(SSOT)으로 두고 운영상 중요 결정을 여기에 명시적으로 연결해두신 부분이 나중에 규칙이 흩어지는 걸 막아줄 것 같습니다. quality-scorer.py, promote-select.py, promote-manager.py로 역할을 나눠 구현하신 스크립트 구성도 재사용하기 좋은 구조입니다.
IT·지식관리 용어가 많이 나올 수 있는 글인데 초보자를 위한 용어·약어 사전까지 따로 만들어두신 배려도 좋습니다. launchd로 스케줄까지 연결해 파이프라인이 계속 돌아가게 하신 다음 단계도 응원합니다!