Cloudflare와 Gemini 3 Flash로 나만의 LLM Wiki를 키워가는 중
MkDocs로 시작한 개인 지식관리 위키를 Cloudflare Pages, Workers AI, Vectorize, D1, RAG 구조로 확장하며 느낀 점을 정리했다.
요즘 나는 지식관리용 LLM Wiki를 계속 만들고 있다.
처음에는 단순했다. 흩어진 문서를 MkDocs로 정리하고, GitHub와 연동해서 변경 이력을 남기는 정도면 충분하다고 생각했다. 문서를 마크다운으로 쓰고, 정적 사이트로 배포하고, 필요할 때 검색해서 보는 구조다. 이 정도만 해도 개인 지식관리 도구로는 꽤 쓸 만했다.
그런데 문서가 쌓이기 시작하니 욕심이 생겼다.
내가 문서를 찾아 읽는 위키가 아니라, 위키가 내 문서를 이해하고 다시 설명해주는 구조를 만들 수 있지 않을까?
오늘은 그 방향으로 꽤 큰 진전을 만들었다. Google Antigravity의 Gemini 3 Flash 모델과 함께 구조를 잡고 구현을 이어가면서, 정적인 MkDocs 위키를 Cloudflare 기반의 서버리스 AI 위키로 확장해봤다.
정적인 문서 묶음이 아니라, 질문하고 학습시키는 개인 지식 베이스를 만들고 싶었다.
처음 출발은 MkDocs였다
MkDocs는 문서형 위키를 만들기에 부담이 적다. 마크다운으로 문서를 작성하고, 폴더 구조만 잘 잡으면 그대로 읽기 좋은 사이트가 된다.
처음에는 이 장점에 집중했다.
- 문서를 마크다운으로 정리한다.
- GitHub에 올려 변경 이력을 남긴다.
- MkDocs로 정적 사이트를 만든다.
- 필요할 때 검색하고 찾아본다.
여기까지는 흔히 말하는 문서화 작업이다. 하지만 내가 만들고 싶었던 것은 단순한 문서 저장소에서 한 걸음 더 나간 형태였다.
문서가 늘어나면 사람은 두 가지 문제를 만난다. 첫째, 어디에 무엇이 있는지 기억하기 어렵다. 둘째, 검색으로 문서를 찾더라도 다시 읽고 해석하는 시간이 든다.
그래서 위키 안에 AI 기능을 넣어보기로 했다.
Cloudflare Pages에서 가능성을 봤다
처음 Cloudflare Pages를 볼 때는 정적 사이트 배포 서비스라는 인상이 강했다. MkDocs 결과물을 올리기에는 딱 좋지만, 그 이상을 하려면 별도 서버가 필요하지 않을까 싶었다.
그런데 살펴보니 Cloudflare 생태계 안에서 생각보다 많은 것을 할 수 있었다.
- Pages로 정적 위키를 배포한다.
- Pages Functions 또는 Workers로 서버리스 API를 붙인다.
- Workers AI로 LLM 추론을 호출한다.
- Vectorize로 문서 임베딩을 저장하고 검색한다.
- D1으로 학습 상태, 피드백, 메타데이터를 저장한다.
- AI Gateway로 요청을 관찰하고 캐싱한다.
즉, 별도의 서버를 직접 띄우지 않아도 정적 문서 사이트 위에 AI 기능을 얹을 수 있었다. 특히 무료 한도 안에서 실험을 시작할 수 있다는 점이 좋았다. 개인 위키처럼 작게 시작하는 프로젝트에는 이 진입 장벽이 꽤 중요하다.
단순 챗봇이 아니라 위키에 붙은 LLM
이번 작업에서 좋았던 점은 AI를 별도의 챗봇으로만 보지 않았다는 것이다.
보통 LLM 기능을 붙인다고 하면 오른쪽 아래에 채팅창을 하나 만드는 장면을 먼저 떠올린다. 물론 그것도 유용하다. 하지만 위키에 붙은 LLM은 조금 다르게 설계할 수 있다.
예를 들면 이런 기능이다.
- 문서 상단에서 AI가 핵심 내용을 3줄로 요약한다.
- 사용자가 특정 문서를 “학습 완료” 상태로 만들 수 있다.
- 학습된 문서는 벡터 검색 대상이 된다.
- 질문이 들어오면 관련 문서를 먼저 찾고, 그 문맥을 바탕으로 답한다.
- 도전과제처럼 문서 정리 진행률을 보여줘서 계속 정리하고 싶게 만든다.
이렇게 만들면 AI는 그냥 대화 상대가 아니라, 위키 안에서 문서의 맥락을 이어주는 기능이 된다. 내가 쌓아둔 문서를 더 잘 쓰게 해주는 인터페이스가 되는 셈이다.
MkDocs 위키에 Cloudflare의 서버리스 기능을 붙이면 RAG 기반 지식관리 도구로 확장할 수 있다.
RAG까지 구현해보니 감이 왔다
오늘 특히 인상적이었던 부분은 RAG 처리였다.
문서를 그대로 LLM에 모두 넣는 방식은 오래 가지 못한다. 문서가 늘어나면 비용도 커지고, 응답도 느려지고, 모델이 어느 문서를 참고해야 하는지도 흐려진다.
그래서 문서를 임베딩하고, 질문이 들어오면 관련 문서 조각을 먼저 찾고, 그 결과를 LLM에 넘기는 구조가 필요하다.
이번에는 Cloudflare Vectorize를 벡터 저장소로 두고, Workers AI의 Llama 3.1 8B 모델을 활용해 답변을 생성하는 흐름을 만들었다. Gemini 3 Flash는 구현을 함께 설계하고 코드를 다듬는 조력자 역할을 했다. 예상보다 충분히 빠르게 구조를 잡을 수 있었다.
내가 체감한 핵심 흐름은 이렇다.
- MkDocs 문서를 읽는다.
- 문서 내용을 적절한 단위로 나눈다.
- 임베딩 모델로 벡터를 만든다.
- Vectorize에 저장한다.
- 질문이 들어오면 관련 벡터를 검색한다.
- 검색된 문맥을 LLM에 넘겨 답변을 만든다.
이 흐름이 붙는 순간 위키는 단순 검색 페이지가 아니라 “내 문서를 근거로 답하는 시스템”에 가까워진다.
도전과제를 넣은 이유
이번 위키에는 도전과제도 넣어두었다.
문서 10개, 30개, 50개처럼 정리 목표를 보이게 하고, 특정 주제 문서를 채우면 달성 상태가 표시되도록 했다. 겉으로 보면 장난스러운 기능처럼 보일 수도 있지만, 지식관리에서는 이런 장치가 꽤 중요하다.
문서 정리는 늘 해야 한다는 것을 알지만, 막상 하려면 재미가 없다. 그래서 진행률이 보이고, 달성 상태가 남고, “조금 더 채워볼까?”라는 마음이 생기게 만드는 것이 필요하다.
LLM Wiki는 결국 기술만의 문제가 아니다. 사람이 계속 쓰게 만드는 구조가 있어야 한다.
오늘의 가장 큰 발견
오늘의 가장 큰 발견은 Cloudflare가 단순한 정적 사이트 배포 플랫폼으로만 보이지 않기 시작했다는 점이다.
Pages로 배포하고, Functions로 API를 만들고, Workers AI로 모델을 호출하고, Vectorize와 D1을 붙이면 작은 규모의 AI 애플리케이션을 꽤 빠르게 만들 수 있다. 특히 개인 프로젝트나 내부 지식관리 실험처럼 시작 규모가 작은 작업에는 이 구성이 잘 맞는다.
예전 같으면 이런 기능을 만들기 위해 서버를 띄우고, 데이터베이스를 만들고, 벡터 DB를 따로 붙이고, 모델 API를 연결하고, 배포 파이프라인을 챙겨야 했다. 지금은 그 많은 요소를 하나의 플랫폼 안에서 실험해볼 수 있다.
물론 아직 갈 길은 있다. PDF나 이미지까지 학습시키는 문제, 답변 품질을 평가하는 피드백 시스템, 문서 변경 시 자동 재학습하는 구조도 더 다듬어야 한다.
그래도 오늘 만든 결과만으로도 방향은 분명해졌다.
앞으로 계속 만들고 싶은 것
나는 앞으로도 이 개인 위키를 계속 키워가려고 한다.
목표는 거창한 범용 챗봇이 아니다. 내가 정리한 문서를 더 잘 찾고, 더 빨리 이해하고, 필요한 순간에 다시 꺼내 쓸 수 있는 지식관리 도구를 만드는 것이다.
LLM은 꼭 채팅창 안에만 있을 필요가 없다. 문서 위키 안에 들어가면, 요약자가 되고, 검색 도우미가 되고, 학습 상태를 관리하는 조력자가 되고, 내가 쌓아둔 지식의 연결선을 다시 그려주는 도구가 될 수 있다.
오늘 작업을 해보니 이런 생각이 들었다.
LLM Wiki는 생각보다 해볼 만하다. 그리고 작게 시작해도 충분히 재미있다.
정적 문서 사이트로 시작해서, AI 요약과 RAG 답변까지 붙여보는 과정은 꽤 좋은 실험이었다. 앞으로 이 위키가 단순한 문서 모음이 아니라, 내가 계속 함께 키워가는 개인 지식 베이스가 되었으면 한다.
참고한 공식 문서
이 포스팅이 가치 있었나요?
여러분의 평가는 콘텐츠의 품질을 결정하는
가장 핵심적인 데이터가 됩니다.
실시간 익명 데이터로 수집되어 블로그 운영에 반영됩니다.