혼자 사용하려고 만들고 있는 개인 지식그래프 허브에 대한 보고

개인 지식그래프 허브는 어떻게 동작하는가 — 인입부터 화면까지

흩어진 학습 자료를 하나의 지식 그래프로 묶어 "무엇을 만들려면 무엇부터 배워야 하는지"를 보여주는 1인용 지식 허브의 동작 원리입니다. 이 글은 코드 레벨까지 파고들지 않고, 자료 한 건이 들어와서 화면에 보이기까지의 흐름과 설계 의도를 따라갑니다.

1. 무엇을 푸는 프로젝트인가

학습 자료는 늘 흩어집니다. 유튜브 영상 하나, GitHub 레포 하나, 공식문서 한 페이지, 블로그 글 하나. 북마크는 쌓이지만 "이것들이 서로 어떻게 이어지는지", "무엇을 먼저 봐야 하는지"는 알려주지 않습니다.

이 프로젝트는 그 자료들을 하나의 지식 그래프로 묶습니다. 단순히 모으는 게 아니라, 자료끼리의 관계와 각 자료의 난이도·역할을 구조화해서 학습 경로가 저절로 드러나게 합니다.

핵심 질문은 이것입니다.

"이런 결과물을 만들고 싶다. 그러면 무엇을, 어떤 순서로 배워야 하는가?"

그래프를 역방향으로 타고 내려가면 이 질문에 답이 나오도록 설계되어 있습니다. 그게 이 허브의 존재 이유입니다.

또 하나의 전제가 있습니다. 이건 1인용 개인 지식 허브입니다. 그래서 요리·금융·건강·생활 자료처럼 "기술"이 아닌 영역도 배제하지 않고 모두 유효한 지식 영역으로 분류합니다.

2. 뼈대 — "나무" 비유로 지식을 조직한다

모든 지식을 6개 계층으로 나눕니다. 나무에 빗댄 비유라 직관적이고, 계층 사이의 위계가 자연스럽게 잡힙니다.

ALT

다양한 가지가 있는 나무의 이미지

세 가지 규칙이 이 뼈대를 지탱합니다.

• 계층끼리는 모두 다대다입니다. 한 도구가 여러 응용에 쓰이고, 한 자료가 여러 개념을 다룹니다. "한 자료는 한 곳에만 속한다"는 단순 가정을 일부러 버렸습니다.

• 각 계층 안에서 다시 4단계 난이도로 나눕니다 — 기초 / 초급 / 중급 / 고급. 콘텐츠의 절대 난이도입니다.

• 역방향 탐색이 목적입니다. "이 열매(결과물)를 만들고 싶다" → 연결된 꽃(응용) → 가지(도구) → 줄기(공식문서) → 뿌리(기초 개념) 순으로 타고 내려가면, 필요한 학습이 난이도 순으로 펼쳐집니다.

관계도 의미를 갖습니다. 예를 들어 제공사는 자기가 다루는 개념과 이어지고(WORKS_ON), 표준 단체는 표준화한 개념과 이어지며(STANDARDIZES), 도구는 그 도구를 운영하는 제공사와 이어집니다(OPERATED_BY). 응용(꽃)은 실제로 만들어진 결과물(열매)을 "가능하게 한다"는 관계(ENABLES)로 연결됩니다.

이 구조는 사용자가 확정한 본질이라 임의로 바꾸지 않습니다. 시스템의 다른 모든 부분은 이 뼈대를 채우기 위해 존재합니다.

3. 자료가 들어오는 길 — 인입(Ingestion)

가장 앞단은 의외로 단순합니다. 메신저 봇에 URL을 던지면 파이프라인이 시작됩니다.

1. 봇이 URL을 받습니다. 동시에 여러 건을 처리할 수 있도록 처리 슬롯 수를 제한해 둡니다 (예: 슬롯 3개 — 끝나면 대기 중인 다음 작업이 자동으로 슬롯을 차지합니다).

2. 자료 종류에 맞춰 내용을 가져옵니다.

   • 유튜브 → 자막

   • GitHub → README

   • 웹 글 → 본문

3. 가져온 내용을 YAML 머리말(frontmatter) + 본문 형태의 마크다운 노트로 만듭니다. 머리말에는 제목·종류·태그 등 구조화된 메타데이터가 들어갑니다.

4. 그 노트를 버전관리 저장소에 커밋합니다 — 즉 모든 지식이 파일로 남습니다. 그래프 DB가 날아가도 원본 노트는 git 히스토리에 보존됩니다.

인입 경로는 종류별로 나뉘어 있고, 각 자료는 출처의 권위 수준을 함께 기록합니다.

• 공식문서·선별 가이드 → primary(공식)

• 유튜브·GitHub·웹 → community(커뮤니티 파생)

여기서 가장 중요한 설계 원칙이 있습니다. 봇은 "실시간"으로 처리합니다. 사용자가 봇에서 답신을 받는 순간, 노트가 완성되고 뒤에서 설명할 풍부화까지 끝나 있어야 한다는 게 정책입니다. "나중에 배치로 처리"가 아니라 "받는 즉시 완성"이 기본값입니다.

4. 자막이 없으면 — 단계적 폴백과 음성 인식(STT)

유튜브 영상에 자막이 없는 경우는 흔합니다. 이때 곧장 포기하지 않고 단계적으로 시도합니다.

• 1차: 기본 자막 추출 도구로 시도합니다.

• 2차: 다른 추출 경로(별도 endpoint)로 재시도합니다. 한쪽이 일시적으로 속도 제한에 걸려도 다른 쪽이 살려냅니다 — 두 경로를 분리해 둔 이유입니다.

• 최후: 그래도 자막이 없으면 영상의 음성을 직접 받아씁니다(STT).

STT는 무겁습니다(영상 한 편에 수십 분 CPU). 그래서 "기본 폴백"이 아니라 "진짜 마지막 수단"으로만 돕니다. 무작정 STT로 떨어뜨리지 않도록 추출 → 검증 → 진단 → 결정의 4단계를 거칩니다.

• 검증: 자막을 받았다고 끝이 아닙니다. 파일 크기·언어 비율·빈 껍데기(placeholder) 여부까지 확인합니다. "파일이 있다 ≠ 내용이 정상이다"이기 때문입니다.

• 진단: 실패했을 때 그 이유를 분류합니다 — 일시적 속도 제한인가, 진짜 자막이 없는가, 비공개 영상인가, 로그인이 필요한가.

• 결정: "영구적으로 자막 없음"이 확정됐을 때만 STT로 넘깁니다.

멤버십/로그인이 필요한 영상도 다룰 수 있도록, 추출 도구가 인증 쿠키를 자동으로 사용합니다. 쿠키는 만료되므로 만료가 임박하면 알림을 보내는 작업도 따로 돌립니다.

이 검증·진단 모듈은 한 번 만들어 두면 봇·복구 작업·재분석 어디서나 재사용됩니다. 새로운 실패 패턴이 생기면 분류 항목만 추가하면 됩니다.

5. 그래프에 적재 — Neo4j

마크다운 노트의 머리말을 파싱해서 그래프 데이터베이스(Neo4j)에 노드와 관계로 적재합니다.

• 자료는 Source 노드가 되고,

• 그 자료가 다루는 개념·기술과 COVERS 관계로 이어지고,

• 커뮤니티 자료는 공식 문서(GROWS_FROM)나 뿌리 개념으로 연결되며,

• 영상을 올린 채널 같은 부가 엔티티도 별도 노드로 함께 적재됩니다.

이 단계에는 프로젝트가 비싸게 배운 교훈이 하나 박혀 있습니다.

"코드에 적힌 스키마"와 "실제 DB의 스키마"는 다를 수 있습니다.

과거에 코드가 선언한 관계 이름과 실제 DB의 관계 이름이 어긋나서, 추천 기능이 몇 달간 빈 결과만 내던 사고가 있었습니다. 그 뒤로 그래프 쿼리를 새로 짜기 전에 실제 DB 구조를 덤프해서 확인하는 절차를 의무화했습니다. "코드가 진실"이 아니라 "실측이 진실"이라는 원칙입니다.

엔티티 노드는 항상 단일 키로 병합(MERGE)합니다. 같은 채널을 두 번 만드는 식의 중복을 막기 위해서입니다. 한 번 중복이 쌓이면 검색 결과가 두 번 나오는 등 조용히 데이터가 오염되기 때문에, DB 차원의 유일성 제약까지 걸어 코드 결함의 백스톱으로 둡니다.

6. LLM으로 살을 붙인다 — 풍부화(Enrichment)

적재만으로는 "제목과 링크"뿐입니다. 여기에 LLM을 써서 자료를 이해 가능한 강의 단위로 가공합니다. 이 풍부화가 이 프로젝트에서 가장 무겁고 가장 가치 있는 부분입니다.

가공되는 것들은 다음과 같습니다.

• 분류 — 난이도(기초~고급), 역할(설명 / 시연 / 설명+시연), 그리고 본질 분류와 직교하는 검색용 다중 태그(사용 단계·사용 사례·도메인).

• 콘텐츠 섹션화 — 긴 영상을 주제별 섹션 + 타임스탬프로 쪼갭니다. 덕분에 화면에서 원하는 지점으로 점프할 수 있습니다.

• 단계 분해 — 따라 할 수 있는 튜토리얼이면 "Step"으로 재구성합니다. 각 단계에 명령어·예상 결과·참고 링크가 붙습니다.

• GitHub 평가 카드 — README를 받아 "이걸 도입할 때의 문제 정의·장단점·대안·결정 체크리스트"까지 LLM이 구조화한 평가로 만듭니다. 도입 판단을 돕는 카드입니다.

비용을 0으로 만드는 트릭

여기 흥미로운 장치가 있습니다. LLM 호출을 외부 유료 API가 아니라, 컨테이너 안에서 도는 코딩 도구를 경유해서 처리합니다. 그래서 풍부화에 드는 API 비용이 사실상 0입니다. 개인 프로젝트에서 LLM을 마음껏 쓰면서도 비용 폭탄을 피하는 핵심입니다. 무거운 LLM 작업은 대체로 서버 CPU가 한가할 때 순차로 돌립니다.

보수적으로 지키는 규칙들

• 풍부화 "버전"을 함부로 올리지 않습니다. 버전을 올리면 전체 자료가 재분해되어 시간·비용이 폭발합니다. 프롬프트는 고치되, 전면 재처리는 명시적 트리거에서만 합니다.

• 다양한 도메인에서 검증합니다. 프롬프트를 바꿀 때 소프트웨어 영상만 보지 않습니다. 예전에 요리 영상의 "9시간 발효" 단계가 "단계 시간은 최대 2시간"이라는 가정에 걸려 거부당한 적이 있습니다. 제약은 현실 도메인 범위만큼 넓게 잡습니다.

• 샘플 먼저입니다. 새 분류 로직은 전수 처리 전에 5~10건으로 먼저 검증합니다.

7. 보여주기 — 웹앱

가공된 그래프는 웹앱으로 노출됩니다. 핵심 화면은 두 가지입니다.

탐색(Explore)

파이프라인(유튜브 / 공식문서 / GitHub / 웹)별로, 그리고 태그 칩으로 좁혀가며 자료를 찾습니다. 기본 정렬은 "최신순"이라 탭에 들어가면 새로 들어온 자료부터 보입니다.

작지만 중요한 결정이 하나 있습니다. 자료 카드는 원본 제목을 그대로 보여줍니다. LLM이 가공한 깔끔한 제목으로 바꿨더니 정작 "내가 찾던 그 영상"을 못 알아보는 문제가 있었습니다. 가공 제목은 작은 보조 글씨로만 곁들입니다.

가이드(Guide)

한 토픽(예: 특정 CLI 도구)에 대해, 입문 → 고급 순서로 짜인 "읽는 강의"를 보여줍니다. 자료 모음이 아니라 읽고 이해하는 강의가 본질이고, 자료는 서술을 보조하는 학습 링크입니다.

가이드의 설계 포인트는 다음과 같습니다.

• 목차는 토픽 자료에서 자동 생성합니다. 모든 토픽에 똑같은 고정 틀을 강제하지 않습니다.

• 자료를 의무적으로 다 끼워 넣지 않습니다. 각 소단원 주제에 실제로 맞는 2~4개만 선별하고, 곁가지로만 언급된 자료나 마케팅성 노이즈는 제외합니다.

• 완성된 가이드 문서를 통째로 그래프 노드에 저장해 두고, 화면은 그냥 렌더만 합니다. 매 요청마다 그래프를 다시 순회해 조립하지 않습니다.

이 구조는 시행착오의 산물입니다. 한때 가이드가 "고정된 6칸 틀에 수백 개 자료를 의무적으로 끼워 넣어" 노이즈가 섞이고 매번 느리게 재조립됐는데, 이를 토픽별 목차 자동 생성 + 선별 + 사전 빌드(통째 저장)로 바꿨습니다.

새 자료가 들어오면 전체를 다시 빌드하지 않고, 맞는 소단원에 학습 자료 항목만 덧붙입니다.

8. 안전망 — 주기 작업(cron)이 실패를 줍는다

봇이 실시간으로 모두 처리하는 게 이상이지만, 현실에선 일부가 실패합니다. 일시적 차단, 프로세스 재시작 중 중단, 옛 데이터의 형식 결함 등입니다. 그래서 주기 작업이 "그물" 역할을 합니다.

• 자막을 못 받은 자료를 밤에 다시 시도하고,

• 풍부화가 누락된 자료를 재처리하고,

• STT가 실패했던 영상을 야간에 천천히 줍습니다.

대원칙은 분명합니다.

봇 = 주 처리(실시간), cron = 안전망(복구).

cron을 주 처리로 쓰면 결과가 몇 시간~며칠 지연됩니다. 그래서 신규 처리가 필요하면 언제나 봇 쪽을 먼저 고치고, cron은 "봇이 실패한 케이스만" 뒤늦게 복구하도록 둡니다.

이 안전망 자체도 조심스럽게 다룹니다. 과거에 한 복구 작업이 매일 같은 영상 수백 건을 무의미하게 재처리하는 무한 루프에 빠진 적이 있습니다("처리량은 일정한데 처리 대상이 매일 겹친다"는 신호로 발견했습니다). 그 뒤로 주기 작업은 "조건 X인 모든 것을 다시 처리" 같은 무차별 동작을 피하고, 정말 새로 들어온 것만 건드리도록 다듬었습니다.

9. 어떻게 여기까지 왔는가 — 진화의 기록

사실 이 시스템은 처음부터 이런 모습이 아니었습니다. 시작은 훨씬 단순했고, 쓰면서 부딪힌 문제들이 지금의 구조를 하나씩 만들었습니다.

처음엔 이랬습니다.

• 유튜브 영상 한 종류만 다뤘습니다. "강의 영상을 받아 노트로 만들고 그래프에 넣는다"가 전부였습니다.

• 중간에 별도의 워크플로 자동화 도구가 오케스트레이터로 앉아, 봇과 처리 단계를 이어 주는 구조였습니다.

• 규모도 작았습니다. 영상 수십 건, 개념·기술 노드 수백 개, 관계 수천 개 수준이었습니다.

• 지식 구조도 평평했습니다. "개념 노드 / 기술 노드 + 그 사이의 관계" 정도였습니다.

시간이 지나며 이렇게 바뀌었습니다.

• 오케스트레이션을 단순화했습니다. 중간의 워크플로 도구를 걷어내고, 봇이 인입 즉시 추출·노트·풍부화까지 직접 끝내도록 바꿨습니다. 주기 작업(cron)은 "실패한 것만 줍는 안전망"으로 역할을 좁혔습니다. 단계가 줄면서 지연도, 고장 날 지점도 함께 줄었습니다.

• 다루는 자료가 넓어졌습니다. 유튜브 한 종류에서 → 유튜브·GitHub·웹 글·공식문서·선별 가이드 5개 경로로 확장됐습니다.

• 평평한 노드 구조를 6계층 나무로 재편했습니다. 단순한 개념/기술 노드를 넘어, 뿌리→줄기→가지→잎사귀→꽃→열매의 위계와 4단계 난이도를 입혔습니다. "학습 경로가 드러난다"는 목표는 이 재편에서 나왔습니다.

• 보는 화면이 생겼습니다. 그래프를 직접 들여다보던 단계에서, 누구나 읽을 수 있는 웹앱(탐색·읽는 가이드)으로 진화했습니다.

• 규모가 수십 배로 늘었습니다. 지금은 5개 경로에 걸쳐 1,700여 건의 자료가 쌓여 있습니다. 자료가 늘수록 자동 분류·선별의 가치도 함께 커졌습니다.

지금도 추가로 만들고 있습니다.

• 새 자료가 들어올 때 새로운 "뿌리 개념"을 LLM이 스스로 판정해 자동 편입하는 자동 확장,

• 가이드가 신규 자료를 받으면 해당 소단원에 자료만 자동으로 덧붙이는 점진적 갱신,

• 응용 개념에서 전제가 되는 기초 개념을 추출해 관계를 자동으로 잇는 작업 등이 진행·예정 단계에 있습니다.

10. 완성품이 아니라 살아있는 시스템

이 프로젝트의 진짜 성격은 "완성품"이 아니라 계속 진화하는 살아있는 시스템이라는 점입니다.

• 써 보고 어긋날 때마다 정정됩니다. 자동 분류 기준, 자료 선별 규칙, 화면 구성 모두 실제로 쓰면서 "이건 좀 이상한데"라고 느낄 때마다 바뀝니다.

• 모든 사고와 교정이 규칙으로 축적됩니다. 같은 실수를 두 번 하지 않도록, "왜 그랬고 어떻게 고쳤는지"를 한 줄씩 기록으로 남깁니다. 예를 들면 이런 것들입니다.

  • 자막이 분명히 있는데도 "없다"고 오인하던 결함 5개를 끝까지 추적해 한꺼번에 고친 일,

  • 자동 인입이 의도치 않게 무관한 영상 수백 건을 끌어온 사고 뒤에 안전장치를 단 일,

  • 1분짜리 쇼츠가 매일 쏟아져 들어오는 걸 길이 필터로 걸러낸 일.

즉 이 허브는 한 번 만들고 끝나는 게 아니라, 쓰면서 데이터가 쌓이고, 쌓인 데이터가 다시 구조를 다듬게 만드는 피드백 루프 위에 있습니다. 자료가 늘수록, 그리고 시행착오가 규칙으로 굳을수록 조금씩 더 똑똑해집니다.

전체 그림 한 장 요약

URL 제출(메신저 봇)
   → 추출 (자막 / README / 본문, 실패 시 → 단계적 폴백 → 최후엔 음성 인식 STT)
   → 마크다운 노트 작성 + 버전관리 커밋   (모든 지식이 파일로 보존)
   → 그래프 적재 (Neo4j: 자료·개념·도구·관계)
   → LLM 풍부화 (난이도·역할·태그 분류 / 섹션화 / 단계 분해 / 평가 카드, 비용 0)
   → 웹앱 (탐색: 파이프라인·태그로 찾기 / 가이드: 입문→고급 읽는 강의)

   ↑ 주기 작업(cron)이 실패분을 야간에 복구  (봇=실시간, cron=안전망)
   ↑ 사고와 교정이 규칙으로 축적             (같은 실수 반복 금지)
   ↑ 데이터가 구조를 다듬는 피드백 루프      (계속 진화 중)

ALT

지식 그래프 허브

이 글에서는 외부 도메인 주소, 이메일, 서버 호스트명·사양, 메신저 봇 핸들, 계정 식별자, 내부 파일 경로 등 개인을 특정할 수 있는 정보를 모두 일반 명사로 바꿔 제거했습니다.