스크랩

rg만으로 부족했던 이유: Qwen 팀이 공개한 로컬 검색 도구 zg 완전 정리

#zvec-grep#ripgrep#벡터검색#MCP#로컬임베딩#AI에이전트

rg만으로 부족했던 이유: Qwen 팀이 공개한 로컬 검색 도구 zg 완전 정리

한눈에 보는 핵심

Qwen 팀이 zg(zvec-grep) 를 Apache 2.0 라이선스로 오픈소스 공개했습니다. 한 줄로 요약하면 이렇습니다.

ripgrep의 정확한 텍스트 검색 + 벡터 검색 + BM25 + 하이브리드 검색을, 하나의 CLI/MCP 인터페이스에서, 전부 내 컴퓨터 안에서.

핵심 포인트만 먼저 짚고 갈게요.

  • 사람과 에이전트 모두를 위한 로컬 우선(local-first) 검색 인프라입니다
  • 자연어 의도로 탐색을 시작해서 정확한 코드 위치까지 좁혀갈 수 있습니다
  • 파일 스캔·추출·임베딩·인덱싱·검색이 기본적으로 온디바이스에서 실행됩니다
  • 기본 임베딩 모델은 16M 파라미터의 경량 모델로, GPU 없이 동작합니다
  • Codex, Claude Code, Cursor, OpenCode를 자동 감지해 같은 로컬 인덱스를 공유합니다

왜 rg만으로는 부족했을까?

ripgrep(rg)은 훌륭한 도구입니다. 함수명, 설정명, 오류 메시지, 문서의 정확한 구절처럼 검색 대상을 명시할 수 있을 때 빠르고 정확하며, 전체 일치 항목을 빠짐없이 찾아줍니다.

문제는 검색의 성격이 바뀌고 있다는 점입니다. AI 에이전트가 코드 이해, 장애 진단, 지식 질의응답, 연구 분석까지 맡게 되면서, 검색 입력이 명시적 문자열에서 시스템 동작이나 구현 의도에 대한 자연어 표현으로 이동하고 있습니다.

원문에서 든 예시가 아주 직관적입니다.

  • "restore theme preferences"를 찾고 싶은데, 실제 구현 함수명은 hydratePreferences일 수 있습니다
  • "access request process"를 검색하지만, 문서에는 "account authorization and approval"이라고 적혀 있을 수 있습니다

이럴 때 벌어지는 일은 개발자라면 다들 겪어보셨을 겁니다. 정확한 키워드를 모르니 텍스트 일치 검색이 관련 내용을 놓치고, 그렇다고 검색 범위를 넓히면 관련도 순위가 없는 대량의 결과가 쏟아집니다. 에이전트는 질의를 여러 개 만들어 반복 검색하고, 파일들을 하나씩 읽어 흩어진 문맥을 조립해야 하죠. 도구 호출 횟수, 응답 시간, 컨텍스트 소비량이 모두 늘어나는데도 여전히 불완전한 근거로 답을 만들게 됩니다.

zg는 rg의 속도와 정확한 검증 능력은 그대로 유지하면서, 여기에 의미 기반 발견·관련도 순위화·컨텍스트 조직화를 더하기 위해 만들어졌습니다.

zg의 검색 구조

zg는 Zvec의 벡터 검색/BM25 기능과 rg를 결합해, 하나의 인터페이스에서 네 가지 검색 방식을 제공합니다.

  1. 의미(semantic) 검색
  2. BM25
  3. 하이브리드 검색
  4. rg를 이용한 정확한 문자열 검색

여기서 중요한 건 고정 파이프라인이 아니라는 점입니다. 정해진 순서로 모든 단계를 거치지 않습니다.

  • 단서가 충분하면 → 곧바로 정확한 검색 단계로 직행
  • 정보가 부족하면 → 자연어 의도에서 시작해 관련 방향과 키워드를 발견하며 범위를 좁힘

네 가지 설계 원칙

① 종단간(end-to-end) 검색 열린 탐색부터 관련도 기반 축소, 정확한 검증까지 각 단계에 적합한 방식을 골라 쓸 수 있습니다. 키워드 추측과 반복 검색, 그리고 누락을 줄이는 것이 목표입니다.

② 다양한 파일 형식 확장 가능한 추출 프레임워크로 코드, 문서, 구조화 데이터를 처리합니다. 가능한 경우 심볼·제목·계층 구조·메타데이터를 보존해서, 각 정보 단위를 정확히 주소 지정할 수 있게 합니다.

③ 컨텍스트 효율 여러 검색 경로의 결과를 통합·순위화하고, 미리보기는 필요할 때만 제공합니다. 원본 파일과 위치 정보를 보존해 불필요한 읽기·도구 호출·토큰 소비를 줄입니다.

④ 로컬 우선 파일 스캔, 인덱싱, 로컬 임베딩 생성이 기본적으로 기기에서 실행됩니다. 외부로 콘텐츠를 보내려면 명시적인 승인이 필요합니다.

설치부터 검색까지, 3단계

macOS/Linux/Windows를 지원하며, 개발자는 CLI를, 에이전트는 MCP를 사용합니다. 별도 검색 서비스를 배포하거나 통합 설정 파일을 작성할 필요가 없습니다.

# 1. zg 설치
npm install -g @zvec/zvec-grep
zg install

# 2. 현재 작업공간의 로컬 인덱스 생성
cd your-repository
zg index

# 3. CLI에서 검색
zg query --human "theme preference persistence on startup"

zg install 명령은 로컬에 설치된 Codex, Claude Code, Cursor, OpenCode를 자동 탐지해 MCP를 구성해 줍니다. 연결된 에이전트들은 MCP를 통해 같은 로컬 인덱스를 직접 사용하므로, 에이전트마다 중복으로 인덱싱하거나 따로 설정할 필요가 없습니다.

코드만을 위한 도구가 아닙니다

zg는 콘텐츠 유형별로 적절한 추출/구조화 방식을 적용하기 때문에, 다음과 같은 대상에 모두 쓸 수 있습니다.

  • 코드 저장소
  • 프로젝트 문서
  • 연구 자료
  • 로컬 지식베이스

경로, glob, 파일 유형, ignore 규칙으로 검색 범위를 제한할 수 있어서, 지원하는 콘텐츠가 늘어나도 불필요한 결과가 섞여 들어오는 걸 막을 수 있습니다.

검색 한 번의 속도가 아니라, 작업 전체의 효율

zg가 최적화하는 대상은 개별 검색 한 번의 지연시간이 아닙니다. 전체 작업을 완료하는 데 필요한 검색 횟수·토큰·시간을 줄이는 데 초점을 둡니다.

이를 위한 장치들이 있습니다.

  • 검색 방식 유도: MCP 도구 설명과 사용 지침을 통해, 에이전트가 "검색 대상에 명시적 키워드/위치/심볼이 존재하는가"를 기준으로 적절한 검색 방식을 고르고, 정보가 충분하면 검색을 중단하도록 유도합니다
  • RRF 결과 통합: BM25와 벡터 검색으로 후보를 만든 뒤, RRF(Reciprocal Rank Fusion)로 결과를 통합하고 중복 제거·순위화를 수행합니다
  • 주소 지정 가능한 단위: 코드 심볼과 문서 섹션 중심으로 독립 검색 가능한 단위를 만들고, 파일 경로와 원본 위치를 유지합니다
  • 압축된 결과: 기본 결과는 제한된 미리보기와 함께 압축된 순위 목록으로 반환하고, 전체 내용은 필요할 때만 읽습니다

벤치마크: 숫자로 본 효과

개별 질의 속도가 아니라 전체 검색 작업의 효율을 보기 위해, 두 벤치마크에서 A/B 평가를 진행했습니다.

| 벤치마크 | 구성 | |---|---| | SWE-QA-Bench | 실제 코드 저장소에서 가져온 20개 질문. 여러 파일의 구현을 찾고 다단계 추론이 필요 | | BrowseComp-Plus | 고정된 대규모 코퍼스에서 여러 문서의 증거를 검색·종합해야 하는 딥리서치 질문 80개 |

평가 조건은 공정하게 맞췄습니다. 동일한 에이전트·모델·프롬프트·실행 환경·작업 제약을 사용하고, 기준 조건은 에이전트 기본 도구만, zg 조건은 여기에 미리 구축한 인덱스와 MCP 도구, 사용 지침만 추가했습니다.

SWE-QA-Bench 결과

  • 도구 호출: 절반 이상 감소
  • 입력 토큰: 절반 가까이 감소
  • Judge 점수: 1.50점 상승

BrowseComp-Plus 결과

  • 정확도: 98.67% → 99.00%
  • 입력 토큰: 37.56% 감소
  • 도구 호출: 43.52% 감소
  • 에이전트 실행시간: 38.58% 감소

📌 비용에 대한 솔직한 주석 인덱스 생성에는 최초 1회의 시간·연산 비용이 들고, 원격 임베딩을 선택하면 API 토큰 비용도 발생합니다. 다만 인덱스는 여러 질의와 에이전트 작업에서 재사용되고 변경된 콘텐츠만 증분 처리되기 때문에, 평가 표에서는 이 비용을 제외했다고 명시하고 있습니다.

정확도가 살짝 올라간 것도 의미 있지만, 실무자 입장에서 눈에 띄는 건 토큰과 도구 호출이 40% 안팎으로 줄었다는 부분입니다. 컨텍스트 윈도우와 API 비용에 직접 연결되는 숫자니까요.

로컬 임베딩과 온디바이스 인덱스

소스 코드와 내부 문서에는 민감하거나 미공개인 정보가 포함되기 마련입니다. 그래서 zg는 파일 스캔·추출·임베딩 생성·인덱싱·검색을 모두 로컬에서 수행하는 경로를 기본값으로 삼았습니다.

총 11개의 온디바이스 임베딩 모델을 포함하고 있으며, 코드·문서·다국어 콘텐츠·긴 입력·경량 실행 등 용도별로 고를 수 있습니다.

기본 모델 local/potion-code-16m-v2

  • 16M 파라미터 정적(static) 모델
  • 로컬 캐시 약 32 MiB
  • GPU 불필요
  • SWE-QA-Bench에서 qwen/qwen3.7-text-embedding과 근접한 작업 성능을 보이면서 임베딩 지연시간과 원격 API 비용을 절감
  • Apple M4 Pro에서 Django 저장소 3,457개 파일 전체를 30초 이내에 인덱싱

Django 규모의 저장소를 30초 안에, 그것도 GPU 없이 처리한다는 건 상당히 실용적인 수치입니다.

또한 Zvec는 벡터/BM25 인덱스를 임베디드 라이브러리 형태로 기기에 저장합니다. 별도 데이터베이스 서비스를 배포하거나 운영할 필요가 없고, CLI와 MCP가 동일한 로컬 인덱스를 공유합니다.

원격 임베딩은 반드시 명시적 선택

로컬 모델이 검색 품질, 다국어 지원, 기기 자원 조건을 만족하지 못할 때는 원격 임베딩을 선택할 수 있습니다. 다만 원격 기능은 자동으로 켜지지 않으며, 사용자가 명시적으로 승인한 경우에만 텍스트나 질의가 기기를 벗어납니다.

앞으로의 계획

원문에서는 현재 제공되는 기능과 향후 계획을 명확히 구분하고 있습니다. 아래는 아직 지원되지 않는 제품 방향입니다.

  • 검색 기능 확장: BM25/벡터/rg에 그래프 검색과 구조화 신호 추가, 질의 계획·결과 통합·재순위화·설명 가능성 개선
  • 콘텐츠 지원 확대: PDF/Word/PowerPoint 지원, 이미지 OCR·레이아웃 추출·크로스모달 이해
  • 컨텍스트 효율 개선: 결과 중복 제거, 구조화, 미리보기, 컨텍스트 선택 최적화
  • 로컬 기능 강화: 로컬 모델과 인덱싱 효율 개선, macOS/Windows/Linux 경험 개선, iOS/Android 등 자원 제한 환경 탐색

이 외에 설치/업그레이드/삭제, 증분 인덱싱, 동시 접근, 서비스 자체 복구, 런타임 진단, 인덱스 호환성도 계속 개선할 계획이라고 합니다.

오픈소스 기여 안내

zg는 Apache 2.0 라이선스로 공개된 초기 단계 프로젝트입니다. 다음 영역의 피드백과 기여를 받고 있습니다.

  • 대규모 코드베이스/지식베이스/에이전트 워크플로우의 실제 사용 사례
  • 검색 품질·성능·에이전트 컨텍스트 효율을 측정하는 재현 가능한 평가
  • 새 파일 형식 추출기, 모델 지원, 에이전트 통합, 버그 수정, 튜토리얼
  • 어려운 검색 작업, 유용한 결과 형태, 자연스럽지 않은 기본 동작에 대한 제품 피드백

마무리하며

zg가 흥미로운 지점은 rg를 대체하려 하지 않는다는 데 있습니다. 정확한 문자열을 아는 순간에는 여전히 rg가 최선이고, zg는 그 rg를 자기 안에 품고 있습니다. 대신 "무엇을 검색해야 할지 모르는 구간"을 의미 검색으로 메우고, 결과를 순위화해서 에이전트가 파일을 무작정 읽어대는 패턴을 줄입니다.

특히 모든 처리가 기본적으로 로컬에서 일어난다는 설계는, 사내 코드와 내부 문서를 다뤄야 하는 팀에게 현실적인 선택지가 됩니다. 별도 벡터 DB를 띄우지 않고 npm install 한 번으로 시작할 수 있다는 점도 진입 장벽을 크게 낮춰줍니다.

에이전트 기반 개발 워크플로우에서 토큰 비용과 컨텍스트 낭비가 고민이라면, 한 번쯤 인덱싱해 볼 만한 도구입니다.

원문: https://news.hada.io/topic?id=33183