# Mavent — 포트폴리오

> 웹에 흩어진 지역 이벤트를 LLM 파이프라인으로 수집·정리하고 지도 위에서 자연어로 찾게 하는 서비스를, AI 코딩 에이전트와 함께 1인으로 설계·구현·운영한 기록.

이 파일은 https://mavent-portfolio.pages.dev/ 의 요약과 장 목록이다. 본문 전문(접힌 세부와 용어 사전 포함)은 https://mavent-portfolio.pages.dev/llms-full.txt 에 있다. 페이지 갱신 2026-10-25 · 기준 커밋 0d7f797b.

규모 · 2026-10-25 운영 DB 실측: 141,355 공개 이벤트 · 94,740 그중 지금 열리고 있거나 앞으로 열릴 이벤트 · 784 이벤트 보유 도시 (156개국) · 7 언어 (제목·요약 저장) · 6,810 활성 수집 소스 · 651 정기 수집 대상 도시
공개 이벤트는 수집 단계의 자동 검사(날짜·중복·이벤트 여부 등)를 통과해 지도와 검색에 나오는 이벤트입니다. 데이터베이스의 22만 행 중 끝나서 보관한 행사, 취소된 행사, 이벤트가 아니라서 걸러 낸 행은 뺐습니다. 다만 끝난 지 30일이 안 돼 아직 보관하지 않은 행사 46,615건이 들어 있어서, 이를 뺀 94,740건을 따로 적었습니다. 7개 언어는 제목과 요약을 일곱 언어로 저장한다는 뜻입니다(공개 이벤트의 86%가 일곱 언어를 모두 갖췄고, 나머지는 매일 도는 번역 배치가 채웁니다). 이벤트 보유 도시는 공개 이벤트가 1건 이상 있는 도시입니다(정기 수집 대상인 활성 도시 651곳 외의 도시도 포함).
결과: LLM 0회 링크가 이벤트 페이지인지 거르는 판정을 소형 모델로 옮겨, 링크 후보 5만 개를 42분 만에 모음 (5장) · 2.45배 미뤄 둔 애매한 링크를 Haiku가 다시 골라 읽었을 때, 읽은 링크당 새 이벤트(무작위 대조 시험) (5장) · 2,858쌍 중 0 LLM에 보낸 반복 공연 쌍 중 LLM이 합친 쌍. 이를 보고 LLM 대신 날짜 규칙으로 가름 (6장) · 10% 이벤트가 아닌 상품·메뉴가 섞여 있던 비율(무작위 500건). 찾아낸 뒤 세 겹 거름망을 둠 (6장) · 9 → 0 '도쿄 마츠리' 상위 10건 중 다른 도시 행사. 실제 검색창 경로를 재현한 평가로 찾아 고침 (7장) · 8 인젝션을 다 잡으려 하기보다, 공격이 통해도 할 수 있는 일을 코드로 좁힌 원칙. 원칙마다 지키는 코드 위치와 고정 테스트를 둠 (8장)

장 목록:

- 01 흩어진 정보를 위치와 시간으로 한 번에 보기 (시작 · 왜 만들었나): 이벤트 정보는 공식 API, 관광청, 축제 홈페이지, 일반 웹페이지, SNS에 흩어져 있어서 "지금, 여기 근처"를 기준으로 훑어볼 방법이 없었습니다.
- 02 수집과 검색을 분리한 구조 (시작 · 한눈에 보기): 백그라운드 워커가 주기적으로 이벤트를 모아 데이터베이스에 정리해 두고, API 서버는 그 데이터로 지도·캘린더·자연어 검색에 답합니다. LLM을 부르는 곳은 페이지 추출과 자연어 검색처럼 몇 군데뿐이고, 나머지는 전부 코드와 규칙입니다.
- 03 수집할 사이트도 시스템이 찾는다 (수집 ① · 어디서 모을 것인가): 651개 활성 도시의 이벤트 사이트를 손으로 등록할 수는 없습니다. 도시마다 "그 도시다운" 검색어를 만들고, 검색 엔진으로 후보를 찾고, LLM이 매긴 확신도 순으로 승격했습니다.
- 04 LLM이 링크를 고르고 코드가 범위를 정하는 탐색(LLM-guided BFS) (수집 ② · 어떻게 훑을 것인가): 처리율 제한과 비용 때문에 사이트를 다 읽을 수는 없습니다. 대신 페이지에서 이벤트를 뽑는 LLM 호출에서 "이벤트가 더 나올 법한 링크"도 함께 골라 받고, 그 제안을 코드가 걸러서 다음 탐색 대상을 정합니다.
- 05 LLM의 판정을 라벨로 모아, 소형 모델에 넘기다 (수집 ③ · 링크 판정을 소형 모델로): 4장의 링크 게이트는 페이지마다 LLM을 불러 링크를 판정했습니다(호출 한 번에 링크 약 21개). 그래서 링크를 모으는 탐색도 LLM 호출을 기다려야 했습니다. LLM이 내린 링크 판정과, 실제로 페이지를 열어 이벤트를 뽑아 본 결과를 학습 데이터로 쌓아 다국어 소형 인코더를 학습시키고 크롤 워커 안에서 직접 돌렸습니다. 지금은 링크마다 LLM을 부르지 않고, 소형 모델이 애매하다고 남긴 링크만 주 1회 묶어서 LLM에 다시 묻습니다.
- 06 중복을 합치고 이벤트가 아닌 것을 거르기 (수집 ④ · 모은 것을 쓸 수 있게): 같은 축제가 공식 API에서 한 번, 관광청 페이지에서 한 번, 일본어·한국어·영어로 각각 들어옵니다. 지도에 마커가 다섯 개 찍히면 곤란합니다. 또 가게 메뉴나 투어 상품처럼 이벤트가 아닌 것이 섞여 들어오기도 합니다.
- 07 LLM 없이 푸는 일반 검색과 품질 측정 (검색 ① · 흔한 질문은 LLM 없이): 검색창에 들어오는 대부분은 "도쿄 마츠리" 같은 짧은 말입니다. 이런 질문까지 LLM에 보내면 비용과 지연만 붙으니, 흔한 질문은 사전과 규칙으로 풀고, 정말 어려운 질문만 8장의 에이전트로 보냅니다.
- 08 문장 질문을 검색 조건으로 바꾸는 에이전트 (검색 ② · 문장으로 묻기): "8월 교토에서 마츠리나 말차 같은 거"는 위치·날짜·취향이 섞인 문장입니다. 에이전트는 이 문장을 데이터베이스 검색 조건으로 바꾸고, 그 조건으로 거를 수 없는 것만 마지막에 LLM이 판정합니다.
- 09 기능별 모델 선택과 월 예산 (운영 ① · 무엇을 어디에 쓸 것인가): 모델과 공급자는 기능마다 따로 골랐습니다. 대화형 검색은 정확도와 지연을, 배치 작업은 비용을 먼저 봤습니다. 지금은 대부분의 LLM 호출을 Claude(Haiku, 중복 판정만 Sonnet)가 맡고, Gemini는 임베딩과 검색어 번역에 남았습니다. 웹페이지 추출은 Claude Haiku와 로컬 GPU의 Qwen을 예산에 따라 바꿔 씁니다. 예산도 기능별 월 상한으로 나눴습니다.
- 10 혼자 운영하기 위한 콘솔과 요청 추적 (운영 ② · 혼자서도 팀처럼): 수집·검색·비용을 코드 배포 없이 다룰 수 있게 운영자 콘솔(한/영 · 20여 화면 — 지출 · 수집 · 소스 검수 · 데이터 품질 · 설정)을 만들었습니다. 지출 상한 · 처리율 · 크론 일정 · 기능별 LLM 공급자 같은 설정은 재시작 없이 바뀌고, 바꾼 기록이 남습니다.
- 11 AI 코딩 세션 여러 개가 한 저장소에서 일하는 환경 (개발 · 만드는 방식): 이 프로젝트 커밋의 98%는 AI 코딩 도구(Claude Code)와 함께 만들었고, 많을 때는 세션 여러 개가 동시에 일했습니다. 이 도구는 대화가 끝나면 앞의 일을 잊고, 문서도 목차대로 찾지 않았습니다. 목차를 거쳐 간 읽기는 약 1%였습니다. 문서를 구역 단위로 찾는 검색 도구를 만들었고, 2주 동안 에이전트가 스스로 부른 것은 72번이었습니다(grep은 약 700번). 지금은 파일을 열 때 관련 문서를 자동으로 붙이는 방식을 주로 씁니다. 이 장은 이런 문제를 측정하고 도구로 메운 기록입니다.
- ＋ 용어 사전 (부록): 본문의 점선 밑줄 용어를 한곳에 모았습니다. 기술 배경이 없어도 이 페이지를 읽는 데 필요한 만큼만 설명합니다.

## 전문

- [본문 전문 텍스트](https://mavent-portfolio.pages.dev/llms-full.txt): 1~11장 · 접힌 세부 · 용어 사전까지 전부(그림 · 데모 영상 제외)
- [본문 1/4 · 도입~5장 · 수집](https://mavent-portfolio.pages.dev/llms-full-1.txt): 같은 본문을 장 묶음으로 나눈 것(파일 앞부분만 읽는 도구용)
- [본문 2/4 · 6~7장 · 정리와 일반 검색](https://mavent-portfolio.pages.dev/llms-full-2.txt): 같은 본문을 장 묶음으로 나눈 것(파일 앞부분만 읽는 도구용)
- [본문 3/4 · 8~10장 · 자연어 검색과 운영](https://mavent-portfolio.pages.dev/llms-full-3.txt): 같은 본문을 장 묶음으로 나눈 것(파일 앞부분만 읽는 도구용)
- [본문 4/4 · 11장 · 용어 사전](https://mavent-portfolio.pages.dev/llms-full-4.txt): 같은 본문을 장 묶음으로 나눈 것(파일 앞부분만 읽는 도구용)
- [웹 페이지](https://mavent-portfolio.pages.dev/): 도식 · 스크린샷 · 데모 영상 포함

## Optional

- [데모 영상: 지도 탐색 · 자연어 검색](https://youtu.be/Pgl_MH826SU)
- [데모 영상: 운영자 콘솔](https://youtu.be/SL8q5cXtC9A)