아프니까 개발자다 아프니까 개발자다

LLM이 틀린 답을 내놓는 이유는 크게 두 가지다. 첫째, 학습 데이터에 없는 내용(특정 도메인 지식, 사내 문서, 개인 기록). 둘째, 학습한 내용과 현실 사이의 시간 차. 두 경우 모두 "모델이 모르는 내용"이라는 공통점이 있다. 이때 쓰는 패턴이 RAG(Retrieval-Augmented Generation) — 검색해서 가져온 문서를 LLM 프롬프트에 끼워 넣어 답변 품질을 높이는 방식이다.이 글에서는 영화 정보 파일을 벡터 데이터베이스에 저장하고, 그 검색기를 에이전트 도구로 등록하는 전체 파이프라인을 순서대로 살펴본다.RAG 파이프라인 전체 흐름문서가 에이전트 도구로 동작하기까지 여섯 단계를 거친다.RAG 파이프라인 전체 구조. 파이프라인은 "준비 단계"와 "실행 단계"로 나뉜다. 준비 단계(..

deep-wiki의 한 페이지가 세 개의 저장소에 동시에 들어간다. 그래프 DB(SQLite + NetworkX), 벡터 DB(Qdrant), 파일 시스템(wiki-output + git). "왜 셋일까? 하나로는 안될까?"이 질문에 대한 답이 사실 가장 근본적이다. 뒤따라오는 정합성 문제도, 신뢰 계층 분리도 모두 "저장소가 여러 개"라는 사실에서 파생되기 때문이다. 결론을 먼저 말하면 이렇다 — 한 페이지의 같은 정보를 가지고 사람이 물어보는 질문이 세 종류로 본질이 다르고, 그 세 질문을 하나의 저장 엔진으로 잘 답할 수는 없다. 이 글은 그 세 질문이 무엇이고, 각 저장소가 왜 존재할 수밖에 없으며, 각자 어떤 방식으로 어떤 역할을 맡는지의 기록이다.1. 배경 — 한 페이지가 답해야 하는 세 종류..

코드 위키를 한 달 운영해 보면 같은 장면이 두세 번 반복된다. 누군가가 위키를 열어 "이 함수의 동작이 이렇다"라는 문장을 읽고, 안내된 위치로 가 보면 그 함수가 거기에 없다. 같은 이름의 다른 함수가 있거나, 함수가 다른 파일로 옮겨졌거나, 아예 삭제되었거나. 위키 본문은 자신만만하게 적혀 있고, 코드는 그 자신감을 배신한다.이 장면이 사람 독자에게는 짜증나는 정도지만, AI 에이전트에게는 다르다. 에이전트는 RAG(Retrieval-Augmented Generation) — 질문이 들어오면 외부 지식 베이스에서 관련 문서를 먼저 검색해 가져온 뒤 그걸 prompt에 끼워 답을 만드는 패턴 — 으로 동작한다. 위키가 가져다 준 문장을 ground truth(검증된 사실)로 받아 그 위에서 추론한다...

들어가며 — 도구 하나 더 추가했더니 RAG 호출이 줄었다로컬 챗봇에 도구를 하나씩 추가해 11개가 됐다. 지식금고 RAG, 공유 메모리, 첨부 검색, 이미지 분석, 웹 검색, 메모리 저장/회상, 캘린더, Claude CLI 자문, 외부 LLM 자문, 이미지 생성으로 구성된다. 모두 LangChain Tool 객체로 통일됐고 LangGraph ReAct에 묶여있다. 깔끔한 설계다.그런데 운영하다가 묘한 패턴을 봤다. 도구가 늘어날수록 작은 모델의 RAG 호출 빈도가 떨어진다. "어떤 도구를 써야 할지" 망설이다 그냥 답해버리는 경우가 늘어난 것이다. 도구가 풍부할수록 좋다는 직관과 반대다. 이번 글은 이 현상의 원인과, 두 가지 안전판 — _safe_tool wrapper와 allowed_tools 화이..

들어가며 — "이 PDF에서 5장 요약해줘"의 진짜 어려움PDF·DOCX·코드 파일을 챗봇에 던져서 그것에 관해 묻고 싶다는 욕구는 평범하지만, 구현은 의외로 까다롭다. 본문을 통째로 시스템 프롬프트에 박으면 컨텍스트가 폭발한다 — 300페이지 PDF면 50만 토큰. 그렇다고 모델이 PDF에 접근할 수단이 없으면 답을 못 한다.해법 자체는 RAG 풀의 표준이다 — "본문은 디스크에 두고, 모델이 필요할 때 도구로 검색하게 한다". search_attachment LangChain Tool 하나만 있으면 끝. 그런데 정작 그 도구를 만들면서 가장 흥미로운 문제가 따로 튀어나왔다 — "도구가 '지금 누구의 첨부를 검색해야 하는지' 어떻게 알지?". 이번 글은 이 한 문제와 ContextVar라는 표준 라이브..

들어가며 — "응답 본문이 비어 있다"RAG 인덱싱 코드가 청크 한 덩어리에 50토큰짜리 맥락 설명을 붙이는 호출을 했다. 응답을 받았는데, 본문이 비어 있다. 토큰 예산은 다 소진됐고, finish_reason은 length다.로그를 보니 모델이 블록 안에서만 1500토큰을 쓰다가 max_tokens 한도에 걸려 종료됐다. 본문은 시작도 안 했다.해결은 한 줄이다.chat_template_kwargs: { enable_thinking: false }이 옵션이 필요한 이유, 어떤 호출 패턴에서 켜고 끄는 게 옳은지를 풀어쓴다. thinking 모델을 운영해본 사람이라면 한 번쯤 마주치는 함정이다.1. thinking 모델은 토큰 예산을 어떻게 쓰는가thinking 모델은 답을 내기 전에 "먼저 생각하고..

코드 위키 시리즈, 실전으로 넘어가다지금까지 코드 위키의 구성 요소를 하나씩 다뤘다 — architecture.md, data-pipeline.md, ADR, 모듈 문서. 이론은 충분하다. 이번에는 실제 프로젝트에 코드 위키를 만들어 본 결과를 공유한다.대상 프로젝트는 개인 지식 금고(2,269개 마크다운 파일)를 벡터 DB로 인덱싱하고 검색하는 로컬 RAG 시스템이다. 12개 Python 모듈, 10개 운영 스크립트, 3가지 AI 모델이 협업하는 시스템에 7개 문서를 작성했다. 각 문서의 하이라이트를 보여주면서, 왜 그 내용이 중요한지를 설명한다.1. index.md — 네비게이션 허브코드 위키의 진입점이다. 실제 문서에서 발췌한 페이지 목록이다:## 페이지 목록- 시스템 아키텍처 (architectu..

왜 벡터 DB를 상시 띄워둘 필요가 없는가로컬 RAG 시스템을 운영하다 보면 Qdrant 같은 벡터 DB를 Docker 컨테이너로 띄워두게 된다. 검색할 때, 인덱싱할 때, 야간 배치 작업에서 모두 Qdrant가 필요하니 "그냥 항상 켜두자"가 자연스러운 선택이다.그런데 실제 사용 패턴을 보면, Qdrant에 요청이 들어오는 건 하루에 몇 번 정도다. 검색 한 번, 야간 인덱싱 한 번. 나머지 23시간 동안 컨테이너는 메모리만 차지한 채 아무것도 하지 않는다.통합 메모리 아키텍처(DGX Spark처럼 CPU와 GPU가 메모리를 공유하는 환경)에서는 이 문제가 더 부각된다. Qdrant가 잡고 있는 메모리가 GPU 작업에 쓸 수 있는 메모리를 줄이기 때문이다. 25,000개 벡터(4096차원) 정도의 컬렉..