이 튜토리얼은 Néstor Daza에 의해 작성되었습니다.

저는 매일 Claude를 사용합니다. Claude는 조사와 텍스트 처리부터 무엇보다도 코드 작성(놀라운 일은 아닙니다)에 이르기까지 일상적인 업무의 모든 것을 도와주는 훌륭한 도구입니다. 하지만 오늘, 제 머릿속의 작은 코더의 목소리가 제게 물었습니다. 내가 이해하고 제어할 수 있는 인프라 위에서 실행되는 나만의 버전을 만들려면 무엇이 필요할까? 만약 나만의 AI 봇을 가질 수 있다면 어떨까? 그래서 저는 그것을 하고 있으며, 이것은 그 과정을 기록하는 시리즈의 첫 번째 게시물입니다.

이 앱의 이름은 Claudius입니다. 이것은 제가 스스로를 위해 구축하고 있는 개인적인 Claude 스타일의 채팅 워크스페이스로, MongoDB를 전체 백본 (backbone)으로 사용하며 Claude 모델은 AWS Bedrock을 통해 제공됩니다. 시리즈의 모든 기사에는 공개 코드가 포함될 것입니다. 이 앱은 MongoDB Atlas의 무료 티어에서 실행되므로, 여기서 다루는 패턴은 읽기만 하고 도달할 수 없는 것이 아닙니다. 여러분은 이를 클론(clone)하여 실행하고, 원하는 부분을 자신의 작업에 가져다 쓸 수 있습니다.

Claude가 이미 존재하는데 왜 직접 만드나요?

네, 맞습니다. Claude는 이미 존재하며 매우 훌륭합니다. 그런데 왜 더 작고 기능이 적은 버전을 직접 만드는 걸까요? 가장 좋은 스승은 바로 자신의 손으로 직접 만드는 자기 자신이기 때문입니다! 상태(state)와 검색(retrieval)을 포함하여 코드를 직접 작성하며 에이전트 루프(agent loop)를 구축함으로써, 저는 실제로 그것을 어떻게 작동하게 만들지 파악해야 합니다. 또한 이를 실행하는 데 필요한 전체 인프라는 완성된 제품이 숨기고 있는 많은 것들을 보여줄 뿐만 아니라, 정말 재미있는 프로젝트가 될 것입니다!

개인적인 보상도 있습니다. 저는 제가 데이터를 소유하고, 제가 운영하는 데이터베이스에 저장되어 대화 전반에 걸쳐 제가 말한 것들을 기억하는 채팅 앱을 원합니다. 이것은 우선적으로 저를 위해 만들어졌으며, 개인적인 목적을 유지하는 것은 프로젝트의 범위(scope)를 정직하게 유지해 줍니다.

이 빌드 과정 또한 훌륭한 콘텐츠가 됩니다. 글쓰기는 제가 하는 일의 일부이기에, 어차피 만들 프로젝트가 다른 개발자들이 따라올 수 있는 시리즈로 변하게 됩니다. 여러분이 이 글을 읽고 있는 이유이기도 합니다.

MongoDB가 전체 백본(backbone)입니다

프로젝트의 유일한 데이터 저장소(datastore)로 MongoDB를 사용하는 결정은 다른 모든 것을 결정짓는 핵심입니다. 데이터베이스에 캐시(cache), 벡터 스토어(vector store), 큐(queue)를 더하는 것이 아니라, 오직 MongoDB만 사용합니다.

이는 설명이 필요할 정도로 흔치 않은 방식입니다. 이와 같은 채팅 앱은 사용자(users)와 대화(conversations)를 어딘가에 보관해야 합니다. 페이지를 새로고침해도 대화가 유지되도록 에이전트(agent)의 작업 상태(working state)를 지속(persist)시켜야 합니다. 문서(documents)와 장기 기억(long-term memories)에 대한 검색(retrieval)을 위해서는 벡터 스토어(vector store)가 필요합니다. 백그라운드 작업(background work)이 나타나면 이를 큐(queue)에 넣을 공간이 필요합니다. 일반적인 답변은 각 기능마다 별도의 제품을 사용하는 것이며, 결국 동기화(sync)를 유지해야 하는 네 개의 시스템을 운영하게 됩니다. 저는 프로젝트 전반에 걸쳐 MongoDB를 사용하고 있는데, 이는 문서 모델(document model)과 Atlas Vector Search가 이 모든 영역을 커버하며, 하나의 데이터베이스를 사용하는 것이 운영하고 추론(reason)하기에 훨씬 수월하기 때문입니다.

임베딩(Embeddings)은 현재 MongoDB의 일부가 된 Voyage AI에서 가져옵니다. 이는 처음 들었을 때보다 더 중요한 의미를 갖습니다. 데이터와 그 위에 놓인 검색 계층(retrieval layer)이 동일한 곳에서 나오기 때문에, 검색을 처리하는 앱의 부분에 대해 관리해야 할 두 번째 벤더(vendor)가 없습니다. 또한 Voyage의 모델은 다국어(multilingual) 능력이 매우 뛰어난데, 이는 제가 영어와 스페인어를 사용하여 AMER(미주) 및 LATAM(라틴 아메리카) 지역을 아우르며 작업하기 때문에 매우 중요합니다. 스페인어 임베딩의 품질은 제대로 작동하는 검색과, 겉으로만 작동하는 척하며 조용히 핵심을 놓치는 검색 사이의 차이를 만듭니다.

만약 여러분이 관계형(relational) 배경을 가지고 있다면, 진행 과정에서 유사점과 차이점을 번역하여 언급하겠습니다. 조인 테이블(join table)이나 추가 서비스로 구축했을 것을 문서 모델(document-model) 선택이 대체할 때, 저는 그 점을 언급하고 설명하며, 트레이드오프(tradeoff)를 명확히 하기 위해 관계형 방식의 대응물을 보여드릴 것입니다.

왜 Claude를 Bedrock을 통해 실행하나요?

MongoDB가 아닌 단 하나의 큰 요소는 모델 계층 (model layer)이며, 앱이 사용하는 모든 Claude 모델은 AWS Bedrock을 통해 제공됩니다. 이러한 선택은 편의성과 사용 용이성 때문입니다. 빠르고 저렴한 모델에서 더 느리지만 더 유능한 모델로 전환하는 것이 요청 내의 단일 문자열(string)만으로 가능하며, 이는 UI의 모델 선택기 (model picker)를 거의 공짜로 만들 수 있게 해줍니다. 또한 모델 액세스를 단일 클라우드 관계 내로 유지함으로써 자격 증명 (credentials)과 결제를 한곳에서 관리할 수 있으며, 이는 사용량 청구서를 모니터링해야 하는 시점에 매우 중요합니다.

기능 및 한계

그렇다면 Claudius는 실제로 무엇을 할까요? 딱 네 가지만 합니다. 저는 이 프로젝트의 범위를 여기서 제한하겠습니다.

첫째, 스트리밍 대화 (streamed conversation)를 유지하며 스레드 중간에 Claude 모델을 전환할 수 있게 합니다. 둘째, 대화 기록 (transcripts)을 쌓아두는 대신, 대화 내부 및 대화 간에 지속적인 사실 (persistent facts)을 기억합니다. 셋째, 파일을 업로드하고 그 내용에 기반한 질문에 답을 얻을 수 있게 합니다. 넷째, 접근 방식을 계획하고 웹 소스를 통해 조사하여 인용된 답변을 반환하는 더 긴 연구 작업 (research task)을 수행할 수 있습니다.

하지만 이것은 제품이 아닙니다! 이 뒤에는 상업적 계획도 없고, 달성해야 할 성장 목표도 없습니다. 더 중요한 것은, 본격적인 버전의 Claude Agent는 Anthropic의 훌륭한 분들에게 맡기겠다는 점입니다. 제 계획은 Claudius를 매우 슬림하게 유지하는 것입니다. 로그인은 Google만 가능하며 그 외에는 없습니다. 사용자의 역할 (role)은 서버에서 결정되므로, 공개적인 경로를 통해 스스로 무언가를 배포하지 않습니다. 이것은 저를 위해 만들어졌으며, 이 시리즈의 후반부에 독자들이 완성된 결과물을 시도해 볼 수 있도록 작은 공개 티어 (public tier)를 개방할 예정입니다. 해당 티어는 엄격하게 제한되어 있지만 최종 결과물이 어떤 모습인지 보여줄 수 있을 만큼은 열려 있으니, 이 시리즈의 마지막 기사 중 하나를 기대해 주세요!

이것은 클론이 아닙니다!

한 가지 매우 중요한 점을 분명히 해두겠습니다. Claudius는 개인적인 오마주이자 학습 프로젝트입니다. Anthropic과 제휴하거나 그들로부터 승인받은 것이 아니며, 실제 서비스인 Claude를 대체하기 위한 것도 아닙니다. 이것은 제가 사용하고 존경하는 도구의 형태를 재구축함으로써 그 구조가 어떻게 작동하는지 이해하는 동시에, 완전한 에이전트형 AI (agentic AI) 애플리케이션의 유일한 데이터 기반으로서 MongoDB의 강력함을 보여주기 위한 것입니다.

구축 방법

구축 과정은 6단계로 진행되며, 이 기사 시리즈를 통해 각 단계를 면밀히 추적할 것입니다.

0단계(Phase 0)는 다른 모든 단계의 전제가 되는 기초, 데이터 모델 (data model), 그리고 인증/역할 (auth/role) 시스템을 구축합니다. 1단계(Phase 1)는 스트리밍 채팅 백본 (streaming chat backbone), 프론트엔드에 연결된 Bedrock 기반의 Claude, 그리고 첫 번째 실제 대화를 구현합니다. 2단계(Phase 2)는 파일 업로드 기능과 업로드된 파일에 대한 검색 (retrieval) 기능을 추가합니다. 3단계(Phase 3)는 제가 가장 기대하고 있는 단계로, 대화가 바뀌어도 유지되는 장기 기억 (long-term memory)을 구현합니다. 4단계(Phase 4)는 리서치 에이전트 (research agent)를 포함한 더 무거운 작업들을 백그라운드 워커 (background worker)로 이동시킵니다. 5단계(Phase 5)는 사용량 측정 (usage metering) 및 비용 제어 (cost controls)를 통해 루프를 완성하고, 소규모 공개 티어 (public tier)를 오픈합니다.

모든 단계는 Github에 호스팅된 공개 코드로 제공됩니다. 저장소에는 구축에 필요한 모든 자격 증명 (credential)과 해당 단계가 무엇인지 나열된 주석이 달린 .env.example 파일이 포함되어 있어, 단순히 읽는 것에 그치지 않고 각 단계를 직접 재현할 수 있습니다.

시리즈 끝 무렵에 공개 티어가 활성화되면 askclaudius.dev에서 운영될 예정이며, 여러분은 완성된 앱을 직접 열어서 사용해 볼 수 있습니다.

이유에 대한 설명은 이 정도면 충분합니다. 다음 기사에서는 저를 가장 놀라게 했던 결정 사항을 다룰 것입니다. 바로 Claudius에는 메시지 테이블 (message table)이 없다는 점입니다! 대화 데이터가 실제로 어디에 저장되는지, 그리고 왜 문서 모델 (document model)이 단순한 기발한 편법이 아니라 올바른 선택인지 보여드리겠습니다. 만약 여러분이 SQL 기반으로 학습해 오셨다면, 이 기사를 꼭 읽어보셔야 합니다!