Qwen Developers의 zg(zvec-grep): 사람과 AI를 위한 로컬 우선 검색
파일명이나 함수명을 안다면 ripgrep만으로도 충분하다. 하지만 “앱 시작 시 사용자 설정을 복원하는 코드”처럼 정확한 표현을 모르는 상태에서는 키워드 검색만으로 원하는 코드를 찾기 어렵다.
Qwen Developers가 Apache 2.0 라이선스로 공개한 zg(zvec-grep)는 이러한 탐색을 지원하는 로컬 우선 검색 계층이다. ripgrep, BM25, 벡터 검색을 단일 인터페이스로 통합하고, 개발자와 AI 에이전트가 같은 로컬 검색 기반을 사용하도록 설계됐다.1
정확한 문자열부터 의미가 비슷한 코드까지
zg가 결합하는 세 가지 검색 방식은 서로 다른 역할을 한다.2
ripgrep은 정확한 문자열과 정규식 검색에 적합하다.
BM25는 검색어와 문서의 관련도를 계산해 결과의 우선순위를 정한다.
벡터 검색은 표현이 달라도 의미가 비슷한 내용을 찾는다.
이 조합을 활용하면 처음부터 정확한 함수명이나 파일 경로를 추측할 필요가 없다. 자연어로 관련 후보를 찾고, 관련도가 높은 결과로 범위를 좁힌 다음, 정확한 문자열과 위치를 확인할 수 있다. 여러 파일에 분산된 호출 흐름이나 특정 기능의 구현 위치를 조사할 때 유용한 접근이다.
CLI와 AI 에이전트가 하나의 인덱스를 공유한다
zg는 macOS, Linux, Windows에서 CLI와 MCP 인터페이스를 제공한다. 개발자는 CLI로 검색하고, AI 에이전트는 MCP를 통해 같은 검색 기능을 호출한다.3
zg install은 로컬에 설치된 Codex, Claude Code, Cursor, OpenCode를 자동으로 탐지해 MCP 연결을 구성한다. 연결된 에이전트와 CLI는 동일한 로컬 인덱스를 사용하므로 도구별로 콘텐츠를 다시 인덱싱할 필요가 없다.3
설치에는 Node.js 22 이상이 필요하며, npm 패키지 이름은 @zvec/zvec-grep이다. 프로젝트에서 zg index를 실행하면 기본적으로 경량 로컬 모델 local/potion-code-16m-v2를 사용한다. 생성된 인덱스는 해당 프로젝트 루트의 .zvec-grep 디렉터리에 저장된다.23
첫 공개 릴리스에는 로컬 임베딩 모델과 내장형 인덱스가 포함돼 있다. 즉, 별도의 원격 검색 서비스 없이 기기 내에서 임베딩 카탈로그를 만들고 검색을 시작할 수 있다.3
중요한 판단 기준은 데이터 경계다
zg의 핵심 가치는 검색 방식의 통합뿐 아니라 로컬 콘텐츠의 이동을 통제하는 데 있다. 파일 분석, 임베딩 생성, 인덱싱, 검색은 기본적으로 기기 안에서 처리된다.
원격 모델을 선택하면 관련 텍스트나 질의가 외부로 전달될 수 있지만, 그 전에 명시적인 승인이 필요하다.3 로컬 콘텐츠와 원격 모델 사이에 권한 부여 게이트를 두는 구조는 사내 코드나 비공개 문서를 다루는 환경에서 특히 중요한 판단 기준이다.
요약: Qwen Developers의 zg를 어디에 적용할 것인가
Qwen Developers의 zg는 단순히 의미 검색을 추가한 grep이 아니다. 정확한 문자열 검색, 관련도 검색, 벡터 검색을 하나의 로컬 인터페이스로 묶고, 사람과 AI 에이전트가 같은 인덱스를 공유하게 만드는 검색 계층이다.
정확한 이름을 모른 채 코드를 자주 탐색하거나, 큰 저장소와 로컬 지식 기반을 AI 에이전트와 함께 검색해야 한다면 적용을 검토할 만하다. 특히 외부 전송 여부를 사용자가 통제해야 하는 환경에서 로컬 우선 설계의 실용적 가치가 크다.
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.