How dotdotgod Query Finds Relevant Documents from a Natural-Language Question

개요

dotdotgod query는 자연어 질문과 의미론적으로 유사한 문서 구절을 로컬에서 검색하여 에이전트가 읽어야 할 유지 관리되는 소스로 안내하는 도구입니다.

주요 내용

* 의미 기반 검색: 파일 이름 검색만으로는 사용자 질문과 문서의 용어가 일치하지 않는 경우(예: "old plans" vs "archive")를 해결하기 위해 자연어 질문과 의미적으로 관련된 Markdown 구절을 찾습니다.
* 검색 범위 제한: docs/ 디렉토리 내의 Markdown 문서만 검색하며, docs/plan/ 및 docs/archive/와 같이 현재 공유 문서와 로컬 작업 기록의 역할을 구분하기 위해 특정 디렉토리를 제외합니다. 비밀 정보가 포함될 가능성이 있거나 구성된 건너뛰기 디렉토리도 임베딩에서 제외됩니다.
* 헤더 계층 구조 기반 분할: Markdown 문서를 헤더 계층 구조를 따라 분할하고, 각 구절을 1,600자로 제한하며, 해당 경로 및 헤더 정보를 첨부하여 검색 단위에 의미와 맥락을 모두 제공합니다.
* 로컬 다국어 E5 모델 사용: Xenova/multilingual-e5-small 모델을 로컬에서 실행하며, @huggingface/transformers를 통해 문서 본문이 원격 임베딩 API로 전송되지 않도록 합니다. 질문은 query: 접두사를, 문서는 passage: 접두사를 사용하여 384차원 벡터로 변환됩니다.
* 의미적 거리 비교 및 렉시컬 부스트: 질문과 모든 문서 구절 간의 의미적 유사성(코사인 유사도)을 직접 비교합니다. 질문의 단어가 결과 경로 또는 제목에 직접 나타나면 작은 보너스(렉시컬 부스트)가 추가됩니다.
* 중복 결과 제거: 검색 결과에서 Markdown 경로별로 하나의 최고 점수 구절만 포함하여, 단일 문서가 결과 집합을 채우는 것을 방지하고 에이전트에게 더 넓은 문서 집합을 검토할 기회를 제공합니다.
* 임베딩 재사용을 위한 로컬 벡터 캐시: 변경되지 않은 구절의 경우, .dotdotgod/vectors/ 디렉토리에 저장된 로컬 벡터 캐시를 사용하여 임베딩을 재사용합니다. 캐시는 변경된 구절만 다시 임베딩하고 삭제된 구절을 제거하여 재구축됩니다.
* 결과 출력: 기본적으로 간결한 사람이 읽을 수 있는 출력을 제공하며, --json 옵션을 통해 청크 ID, 리포지토리 상대 경로, 헤더 계층 구조 및 본문 발췌를 포함하는 구조화된 데이터를 확인할 수 있습니다.

시사점

dotdotgod query는 자연어 질문의 의미를 파악하여 경로를 알 수 없을 때 관련 문서를 효과적으로 찾아내므로, 코드나 문서 변경 후 에이전트가 검토해야 할 대상을 식별하고 필요한 섹션을 읽는 데 중요한 역할을 합니다.