로컬검색 30초, 3,457개 파일 인덱싱 — Qwen의 zg가 에이전트 워크플로에 가져온 변화

·

핵심 요약

  • zg(zvec-grep)는 Qwen 팀이 오픈소스로 공개한 로컬 우선 검색 도구로, ripgrep의 정확한 텍스트 검색에 벡터 검색과 BM25, 하이브리드 검색을 결합해 자연어 의도로 코드와 문서를 탐색하고 정확한 위치까지 좁힘
  • 기본 임베딩 모델은 local/potion-code-16m-v2로 16M 파라미터, 로컬 캐시 약 32 MiB, GPU 불필요. 용도별로 선택 가능한 11개 온디바이스 임베딩 모델을 함께 제공
  • Apple M4 Pro에서 Django 저장소의 3,457개 파일 전체를 30초 이내에 인덱싱. Zvec는 벡터/BM25 인덱스를 임베디드 라이브러리 형태로 기기에 저장해 별도 DB 서비스가 불필요

분석

목차

로컬검색의 기준이 달라지고 있다. Django 저장소 3,457개 파일을 Apple M4 Pro에서 30초 만에 인덱싱했다는 수치는 ripgrep에 의존해온 기존 워크플로의 한계를 환기시킨다. Qwen 팀이 오픈소스로 공개한 zg(zvec-grep)는 키워드 매칭에 머무르던 로컬검색에 의미 기반 탐색을 더한 도구다.

로컬검색의 새 기준, zg가 등장한 배경

ripgrep은 빠르지만 “OAuth 콜백을 어디서 처리하지?” 같은 자연어 질문에는 약하다. zg는 이 로컬검색의 공백을 정확히 짚는다. 기본 임베딩 모델로 local/potion-code-16m-v2를 채택했다. 파라미터 16M, 로컬 캐시 약 32 MiB, GPU 없이 CPU만으로 돈다. 용도에 따라 골라 쓸 수 있는 온디바이스 임베딩 모델 11종을 함께 제공한다.

Zvec라는 이름의 벡터·BM25 인덱스는 임베디드 라이브러리 형태로 디바이스에 저장된다. 별도 DB 서비스가 필요 없다. 이 점이 온프레미스 환경이나 에이전트 워크플로에서 운영 방식의 차이를 만든다.

하이브리드 로컬검색의 구조

핵심은 단일 알고리즘이 아니라 융합이다. BM25와 벡터 검색으로 후보를 만들고 ripgrep로 정확 매칭을 더한 뒤 RRF(Reciprocal Rank Fusion)로 통합 순위를 만든다. 기본 반환값은 제한된 미리보기와 압축된 순위 목록이다. 결과 파일을 통째로 다시 읽어들이지 않아도 다음 단계 추론에 충분한 단서가 남는다.

세 가지 로컬검색 방식 비교

항목 ripgrep 단독 zg 하이브리드 원격 벡터 DB
인덱싱 대상 텍스트만 벡터 + BM25 + 텍스트 벡터 + 메타
자연어 질의 불가 가능 가능
로컬 자립도 완전 완전 불가(API 의존)
에이전트 통합 직접 호출 MCP 기본 지원 별도 어댑터 필요
대표 비용 디스크 I/O CPU 임베딩 API 호출비

에이전트 워크플로에 zg를 끼워 넣는 법

에이전트와 결합하는 경로는 MCP(Model Context Protocol)다. 같은 로컬 인덱스를 여러 에이전트가 공유하므로 에이전트별 중복 인덱싱이 발생하지 않는다. 도구 설명에 검색 중단 조건까지 명시돼 있어 같은 질문을 반복 호출하는 일도 줄었다. 실무자 입장에서 눈에 띄는 건 비용 구조의 변화다. 현업에서 에이전트 기반 개발을 도입하는 사례가 늘고 있다는 점에서, 로컬검색 레이어는 비용 경쟁력의 다음 변수가 된다.

두 벤치마크가 보여준 로컬검색 효과

SWE-QA-Bench는 실제 코드 저장소 20개 질문으로 다단계 추론을 시험한다. zg 도입 시 도구 호출이 절반 이상 줄고 입력 토큰도 절반 가까이 감소했다. Judge 점수는 1.50점 상승했다.

BrowseComp-Plus는 80개 질문의 딥리서치 평가다. 정확도가 98.67%에서 99.00%로 올랐고, 입력 토큰 37.56%, 도구 호출 43.52%, 에이전트 실행시간 38.58%를 각각 줄였다. 단, 최초 1회 인덱스 생성과 원격 임베딩 API 비용은 평가에서 제외된 수치라는 점을 기억할 필요가 있다.

실무 적용 포인트

  • 저장소 루트에서 `zg index .`로 인덱싱을 시작하고, 기본 경로인 `.zvec/`를 `.gitignore`에 추가한다.
  • `.zgignore`로 `node_modules`, `dist`, `venv` 등 대용량 디렉터리를 명시적으로 제외해 인덱싱 시간을 단축한다.
  • MCP 서버 모드(`zg serve –mcp`)로 띄우고, 에이전트 시스템 프롬프트에 “3회 검색 후 정답 후보를 종합하라” 같은 중단 규칙을 함께 적는다.
  • 코드·문서·자연어 비율에 따라 11개 임베딩 모델을 교체한다. 코드 중심이라면 `potion-code-16m-v2`, 한국어 문서가 많다면 다국어 모델을 우선한다.

지금 바로 해볼 것

  • 데모 저장소(예: requests, fastapi)를 클론하고 `zg index .` 실행 시간을 측정한다.
  • ripgrep 단독 결과와 zg 하이브리드 결과를 동일 질의로 비교해 토큰 사용량을 비교한다.
  • 자신이 쓰는 에이전트(Claude Code, Cursor 등)의 MCP 설정 파일에 zg 서버를 등록한다.
  • `.zgignore`를 작성해 노이즈 디렉터리를 차단하고 인덱스 크기를 줄인다.
  • 11개 임베딩 모델 중 5종을 추려 각 질의 유형(심볼 검색·의미 검색·오타 교정)별 정확도를 기록한다.

검증되지 않은 부분과 남은 과제

필자는 이 도구의 의의가 검색 속도 자체보다 에이전트 한 사이클의 비용 구조에 있다고 본다. 토큰과 호출 횟수가 절반 가까이 줄어든다는 건 같은 예산으로 더 긴 추론을 돌릴 수 있다는 뜻이다. 다만 남은 검증 과제는 명확하다. 인덱스 갱신 정책, 모노레포 점유 메모리, 모델 교체 비용이다. 원문은 Hacker News Korea의 zg(zvec-grep) – 키워드를 넘어서는 로컬검색 인프라에서 확인할 수 있다.

자주 묻는 질문

zg는 ripgrep을 대체하는 도구인가?

대체가 아니라 그 위의 레이어다. ripgrep의 정확한 매칭을 결과 정밀화에 그대로 활용하면서, 그 앞에 BM25와 벡터 검색을 두어 후보 생성을 의미 기반으로 확장한 구조다.

GPU가 없어도 로컬검색이 가능한가?

기본 모델 local/potion-code-16m-v2는 CPU만으로 동작한다. 파라미터 16M, 로컬 캐시 약 32 MiB 수준으로 일반 노트북에서도 인덱싱과 검색이 가능하다.

에이전트 도구로 쓸 때 비용은 얼마나 줄어드는가?

BrowseComp-Plus 80개 질문 평가에서 입력 토큰 37.56%, 도구 호출 43.52%, 에이전트 실행시간 38.58%가 감소했다. 결과가 미리보기와 압축된 순위 목록으로 반환되기 때문이다.

인덱스 갱신은 자동인가 수동인가?

공개된 워크플로 기준으로는 수동 인덱싱(`zg index`)이 기본이다. 파일 변경 감지 기반 자동 갱신은 모노레포 환경에서의 검증 과제로 남아 있다.

참고 원문

이 기사는 다음 원문을 확인해 작성했습니다: geeknews — zg(zvec-grep) – 키워드를 넘어서는 로컬 검색 인프라

2의 “로컬검색 30초, 3,457개 파일 인덱싱 — Qwen의 zg가 에이전트 워크플로에 가져온 변화”에 대한 답변

  1. […] 검색형 컨텍스트는 에이전트 워크플로에서 로컬 검색이 갖는 의미와 맞닿아 있다. 메모리 전체를 매번 다시 읽는 대신 인덱스에서 다시 찾는 […]

  2. […] retrieval-style context model connects directly to what local search means in agent workflows. Instead of re-reading the entire memory on every turn, the agent now re-finds what it needs from […]

답글 남기기

이메일 주소는 공개되지 않습니다. 필수 필드는 *로 표시됩니다