Open Notebook 딥다이브
— 내 서버에서 굴리는 오픈소스 '구글 NotebookLM 대체재'

1프로젝트 한줄 요약

한 문장으로 이 프로젝트가 뭘 하는지부터.

Open Notebook = "흩어진 자료 → 검색·대화·요약·팟캐스트가 되는 개인 연구 노트북". 논문 PDF, 유튜브 영상, 녹음 파일, 웹페이지를 노트북 하나에 던져 넣으면, AI가 그 자료들을 읽고·쪼개고·색인해 둔다. 이후 "이 자료들 핵심만 정리해줘", "A와 B 주장이 어떻게 다른지 표로 만들어줘"처럼 물으면, 내가 넣은 자료에 근거해 답하고 출처(인용)를 붙여 준다.

핵심 철학은 "내 데이터는 내 통제 아래(Privacy-First)"다. 자료도, 대화도, 임베딩(검색용 색인)도 전부 내가 띄운 SurrealDB와 디스크에 남는다. AI 공급자에게 보내는 내용조차 문맥(Context) 제어 기능으로 "어디까지 보낼지"를 항목별로 고를 수 있다.

2왜 주목받는가

TrendShift 일간 10위까지 올라온 이유 — 트렌딩의 배경.

2024년 구글 NotebookLM이 "내 자료로 대화 + 자동 팟캐스트"로 화제가 된 뒤, "같은 걸 내 서버에서, 내 모델로"를 원하는 수요가 컸다. Open Notebook은 그 빈자리를 정확히 노린다. 트렌딩 이유를 다섯으로 정리한다.

① 프라이버시 — 자료가 클라우드로 안 나간다

변호사·의료·연구·사내 보안 자료처럼 "외부 업로드 자체가 금지"인 경우가 많다. Open Notebook은 Docker로 내 서버에 띄우면 자료·임베딩·대화가 전부 로컬에 머문다. 여기에 Ollama·LM Studio로 LLM까지 로컬에 두면 인터넷 없이 100% 오프라인으로도 굴러간다.

② 18개+ AI 공급자 선택권 = 비용·성능 통제

NotebookLM은 구글 모델만 쓴다. Open Notebook은 esperanto 라이브러리 덕분에 OpenAI·Anthropic·Google·Groq·Mistral·DeepSeek·xAI·OpenRouter·Ollama 등 18종을 골라 끼운다. "요약은 싼 모델, 추론은 좋은 모델, 임베딩은 로컬"처럼 작업별로 모델을 섞어 비용을 깎을 수 있다.

③ 팟캐스트 — 화자 1~4명, NotebookLM은 2명 고정

NotebookLM의 대표 기능인 "두 진행자가 자료를 떠드는 팟캐스트"를, Open Notebook은 화자 1~4명 + 커스텀 프로필 + Episode Profile(에피소드 설계도)로 확장했다. 대본을 직접 손볼 수도 있어 "딥다이브 2인 대담" 한 가지에 갇히지 않는다.

④ API 우선 설계 — 전부 자동화할 수 있다

NotebookLM은 공개 API가 없다. Open Notebook은 모든 기능을 FastAPI REST API로 노출한다(:5055/docs). 그래서 "매일 아침 새 논문을 자동으로 노트북에 넣고 요약 팟캐스트를 만들어 메일로 보내기" 같은 파이프라인을 스크립트로 짤 수 있다.

⑤ MCP 통합 — Claude Desktop·VS Code에서 바로 접근

MCP(Model Context Protocol) 서버를 내장해, Claude Desktop이나 VS Code 같은 MCP 클라이언트에서 내 노트북·소스를 검색·활용할 수 있다. "연구 자료 창고"를 다른 AI 도구의 백엔드로도 쓰는 셈이다.

3기술 스택 전체 지도

pyproject.toml · package.json · docker-compose · 소스 트리에서 뽑아낸 실제 구성.

Open Notebook은 ⓐ 백엔드(연구 두뇌) ⓑ 데이터 계층 ⓒ 프론트엔드 ⓓ 인프라 네 층으로 나뉜다. 특히 FastAPI 백엔드와 Next.js 프론트가 완전히 분리(디커플드)되어 REST로만 대화하는 게 설계의 큰 특징이다.

ⓐ 백엔드 — 연구 두뇌 (Python)

ⓑ 데이터 계층 — SurrealDB 한 덩어리

ⓒ 프론트엔드 — 모던 React (TypeScript)

ⓓ 인프라 & 배포

4아키텍처 심화 분석

자료 한 개가 "대화 가능한 지식"이 되기까지 — 데이터의 여정.

Open Notebook의 흐름은 크게 두 갈래다. ① 자료를 넣어 색인하는 적재 파이프라인(왼쪽), ② 질문을 받아 답을 짓는 질의 파이프라인(오른쪽). 가운데에 SurrealDB가 모든 걸 보관하고, 무거운 작업은 surreal-commands 백그라운드 워커가 떠맡는다.

핵심 설계 패턴 ① — Esperanto 공급자 추상화 (어댑터 패턴)

가장 중요한 결정. 18개 공급자를 직접 if/else로 분기하면 코드가 지옥이 된다. 대신 esperanto가 LLM·임베딩·STT·TTS 네 종류의 공통 인터페이스를 정의하고, 각 공급자를 그 규격에 맞춰 끼운다. 위쪽 비즈니스 로직은 "어느 회사 모델인지" 전혀 모른 채 같은 메서드만 호출한다. 새 공급자가 나와도 어댑터 한 개만 추가하면 끝.

핵심 설계 패턴 ② — SurrealDB 멀티모델 = 벡터DB를 안 두는 결단

전형적인 RAG 스택은 "본문은 Postgres, 의미 벡터는 Pinecone, 검색은 Elasticsearch"처럼 DB를 3~4개 쓴다. Open Notebook은 SurrealDB 하나로 통합했다. 같은 DB 안에서 노트북 → 소스 → 노트 같은 관계(그래프)도 잇고, 벡터 유사도 검색도 하고, 전문검색(FTS)도 한다. 운영할 인프라가 줄고, "키워드 매칭(FTS) + 의미 매칭(벡터)"을 합친 하이브리드 검색을 한 쿼리로 짜기 쉬워진다.

핵심 설계 패턴 ③ — LangGraph 상태 그래프

채팅·질문응답·변환을 한 번의 LLM 호출로 끝내지 않고, "검색 → 컨텍스트 구성 → 생성 → 인용 부착" 같은 단계를 노드로 쪼갠 그래프로 만든다(graphs/chat.py, ask.py, transformation.py). 각 단계가 분리돼 있어 디버깅·교체·재시도가 쉽고, 대화 상태는 checkpoint로 저장돼 멀티턴이 자연스럽게 이어진다.

핵심 설계 패턴 ④ — surreal-commands 비동기 잡 큐

임베딩(자료가 크면 수천 조각)·팟캐스트(TTS 합성은 몇 분)는 사용자를 기다리게 하면 안 된다. Open Notebook은 commands/의 워커가 이런 작업을 백그라운드로 처리하고, 큐 저장소로 SurrealDB를 그대로 쓴다. 별도 Redis/Celery 없이 "DB가 큐"인 단순한 구조다.

핵심 설계 패턴 ⑤ — API-우선 디커플드 아키텍처

프론트(Next.js)와 백엔드(FastAPI)가 완전히 분리돼 REST로만 만난다. 덕분에 웹 UI 없이도 API만으로 모든 걸 자동화할 수 있고(②번 트렌딩 이유), 나중에 모바일 앱·CLI를 붙여도 백엔드는 그대로다. docker-compose는 이 둘을 한 이미지로 묶되 supervisord가 내부에서 여러 프로세스로 띄운다.

5디렉토리 구조 해부

실제 저장소 트리에서 "어디에 뭐가 있는지" 핵심만.

핵심 읽는 순서를 추천하면: api/routers/(입구가 뭐가 있나) → api/*_service.py(그게 뭘 부르나) → open_notebook/graphs/(AI가 어떻게 추론하나) → open_notebook/database/repository.py(SurrealDB를 어떻게 다루나) 순이다. 라우터는 얇고, 진짜 일은 service와 graphs에서 일어나는 계층 분리(layered) 구조가 또렷하게 보인다.

6학습 포인트 (기술별)

이 레포에서 "무엇을 배울 수 있는가" — 기술별 배울 것 + 실습 아이디어.

7시스템 요구사항

"내 노트북으로 돌아갈까?" — 구성에 따라 천차만별이다.

8직접 해볼 수 있는 실습 과제

읽기만 하면 안 남는다 — 손으로 해보는 난이도별 과제 6선.

9관련 기술 심화 학습 로드맵

이 레포를 발판으로 "RAG 풀스택"을 익히는 6주 코스.

10핵심 키워드 사전

이 프로젝트를 읽다 만나는 용어들 — 짧게 정리.

11참고 링크

더 깊이 파고들 때의 출발점.