zg: Локальный поиск для AI-агентов, объединяющий ripgrep, BM25 и векторы

В современной экосистеме искусственного интеллекта, особенно в области автономных агентов (Agentic AI), наблюдается четкий сдвиг в сторону локальных, надежных и эффективных решений. Одной из самых больших проблем, с которыми сталкиваются разработчики, является «бюджет инструментов» (tool budget) — лимит вызовов API, токенов и вычислительного времени, который тратится на выполнение задач. Когда агенту нужно найти конкретный символ или функцию в коде, традиционные методы часто оказываются неэффективными. Они либо слишком медленны, либо требуют огромных затрат контекста. Именно на этот разрыв отвечает новый проект от команды Qwen Developer — zg (zvec-grep).

Это не просто еще одна утилита для поиска по файлам. zg представляет собой слой поиска «local-first» (сначала локально), который объединяет мощь ripgrep, алгоритм BM25 и векторный поиск под одним интерфейсом. Это решение предназначено как для людей, работающих с кодом, так и для AI-агентов, которым нужно быстро и точно находить контекст. В этой статье мы подробно разберем, как работает zg, почему его архитектура важна для будущего автономного программирования, и как его можно внедрить в свой рабочий процесс, особенно с учетом доступности из России и локального запуска.

01Проблема: Почему агенты тратят слишком много ресурсов на поиск?

Чтобы понять ценность zg, нужно сначала осознать масштаб проблемы, которую он решает. Современные AI-агенты, такие как Codex, Claude Code или Cursor, часто выполняют сложные задачи, требующие глубокого понимания кодовой базы. Когда агенту нужно найти решение, он обычно прибегает к одному из двух сценариев, и оба они неоптимальны.

Первый сценарий: цель известна точно (например, «найти функцию calculate_tax»). В этом случае стандартный инструмент ripgrep работает идеально. Он молниеносен, точен и не требует больших затрат токенов. Однако, как только задача становится сложнее — например, «найти код, который обрабатывает ошибки сети» — ripgrep бессилен. Он ищет по ключевым словам, а не по смыслу.

Второй сценарий: цель описана на естественном языке. Здесь на сцену выходит семантический поиск (векторный). Но у него есть свои недостатки. Векторный поиск может быть медленным, требовать GPU для ускорения (хотя zg это обходит) и часто дает «шумные» результаты, которые нужно фильтровать. Кроме того, агенты часто вынуждены читать целые файлы, чтобы собрать контекст вручную, что приводит к взрывному росту потребления токенов и времени выполнения. Каждый такой «детур» (отклонение от прямого пути) стоит дорого. zg призван устранить эту неэффективность, предлагая единую точку входа для всех типов поиска.

02Архитектура zg: Один индекс, четыре пути извлечения

Ключевая инновация zg заключается в том, что он индексирует рабочую область (workspace) один раз, а затем предоставляет несколько способов запроса к этому индексу. Это позволяет агенту или разработчику выбирать наиболее подходящий метод в зависимости от конкретной задачи. Документация по конвейеру извлечения (retrieval pipeline) определяет четыре основных маршрута:

1. Гибридный режим (по умолчанию): Этот режим сочетает намерение (intent) с лексическими якорями. Он пытается понять смысл запроса, но также ищет точные совпадения ключевых слов. Это наиболее универсальный вариант, который часто дает лучший баланс между точностью и полнотой.
2. --fts (Full-Text Search): Использует алгоритм BM25 для ранжирования результатов по точным терминам. Это классический полнотекстовый поиск, который отлично подходит, когда вы знаете конкретные технические термины или названия функций.
3. --vector: Включает концептуальное сходство без лексического ранжирования. Этот режим идеален для поиска по смыслу, когда вы не знаете точных названий, но описываете поведение или логику. Например, поиск «кода, который отправляет email».
4. --rg (Ripgrep): Режим исчерпывающего буквального или регулярного поиска. Важно отметить, что этот маршрут не требует индекса. Это критически важно для репозиториев, которые еще не были проиндексированы, или для быстрого поиска по временным файлам.

Первые три режима читают из индекса, что обеспечивает высокую скорость. Режим --rg работает напрямую с файлами, что дает гибкость, но может быть медленнее на больших проектах. Такая многоуровневая архитектура позволяет zg адаптироваться под любые сценарии использования.

03Интеграция с AI-агентами: MCP и экономия контекста

Одной из самых сильных сторон zg является его глубокая интеграция с современными AI-агентами через протокол MCP (Model Context Protocol). Команда Qwen Developer проявила сдержанность в дизайне, что является редким и ценным качеством.

При запуске команды zg install, инструмент автоматически обнаруживает такие среды, как Codex, Claude Code, Cursor и OpenCode, и настраивает локальную интеграцию MCP. Сервер работает через Streamable HTTP MCP на локальном адресе http://127.0.0.1:7999/mcp с опциональной аутентификацией по bearer-токену.

Что особенно важно, стандартный набор инструментов (toolset) для агентов включает всего два инструмента:

• zvec_grep_search: Используется, когда намерение известно, но точная строка не известна (семантический/гибридный поиск).
• zvec_grep_rg: Используется, когда символ, путь или регулярное выражение известны точно (поиск ripgrep).

Жизненный цикл индекса (создание, удаление, обновление) остается в зоне ответственности CLI-интерфейса. Это предотвращает ситуации, когда агент случайно или ошибочно перестраивает или удаляет индекс. Существует расширенный набор из шести инструментов, включающий управление индексом, но он доступен только по явному запросу через флаг zg server on --mcp-toolset full. Документация прямо предупреждает: агент никогда не должен молча создавать, перестраивать или удалять постоянный индекс.

Формат вывода также оптимизирован для «экономики контекста». Результаты возвращаются сгруппированными по файлам с указанием диапазонов строк. Предварительные просмотры исходного кода из индекса по умолчанию отключены, если они не запрошены явно. Кроме того, zg блокирует использование флагов ripgrep, которые меняют формат вывода (таких как --json, --count, -l, --vimgrep), чтобы сохранить компактный и предсказуемый формат результата.

04Встраивания (Embeddings): Работа на устройстве без GPU

Еще одним ключевым преимуществом zg является возможность работы полностью на устройстве (on-device). В каталоге встраиваний на данный момент задокументированы десять локальных моделей и три удаленных endpoint от Qwen. По умолчанию используется модель local/potion-code-16m-v2.

Это статическая модель Model2Vec с выходным размером 256 измерений и лимитом входа в 8192 токенов. Поскольку она использует статический поиск векторов, выбор GPU не ускоряет ее работу, что делает zg доступным даже на слабых машинах. Для более сложных задач доступны более тяжелые локальные опции, такие как jina-embeddings-v2-base-code, embeddinggemma-300m и qwen3-embedding-0.6b. Удаленные опции, такие как qwen/qwen3.7-text-embedding (с лимитом 128 000 токенов) и мультимодальная qwen/qwen3-vl-embedding, требуют явного разрешения на передачу данных.

Для разработчиков из России это особенно актуально: локальный запуск гарантирует, что ваш код и контекст не покидают вашу машину, что соответствует строгим требованиям к безопасности данных и обходит возможные ограничения доступа к зарубежным облачным API.

05Результаты бенчмарков: Экономия ресурсов

Хотя официальные бенчмарки пока не опубликованы в репозитории (раздел benchmarks является placeholder), команда Qwen Developer поделилась результатами в своем анонсе. Эти тесты проводились в формате A/B с фиксированными агентами, моделями, промптами и задачами. Стоимость сборки индекса не включалась в расчеты.

На выборке SWE-QA-Bench из 20 вопросов zg позволил сократить количество вызовов инструментов более чем наполовину и уменьшить количество входных токенов почти на 50%, при этом повысив оценку Judge на 1.50 балла. На более крупной выборке BrowseComp-Plus из 80 вопросов точность выросла с 98.67% до 99.00%, в то время как количество входных токенов упало на 37.56%, вызовов инструментов — на 43.52%, а время выполнения агента — на 38.58%.

Также сообщается, что индексирование репозитория Django (3457 файлов) занимает менее 30 секунд на Apple M4 Pro. Важно отметить, что выборки в 20 и 80 вопросов относительно малы, а результаты получены от самого разработчика, поэтому независимая репликация остается желаемой, но уже сейчас цифры выглядят очень многообещающе.

06Установка и развертывание

zg уже готов к использованию. Он устанавливается через npm как @zvec/zvec-grep. Требования минимальны: Node.js 22 или новее, поддержка macOS, Linux или Windows. Для работы с моделью по умолчанию GPU не требуется. Лицензия Apache 2.0 разрешает коммерческое использование, что делает zg отличным выбором для корпоративной среды.

Для начала работы достаточно выполнить:

npm install @zvec/zvec-grep
zg index

После этого вы можете использовать zg как через CLI, так и через интегрированные инструменты для AI-агентов. Документация и исходный код доступны в организации zvec-ai на GitHub.

07Что это значит на практике

Для разработчиков, работающих с AI-агентами, zg представляет собой значительное улучшение в эффективности. Сокращение количества вызовов инструментов и токенов на 40-50% означает не только экономию денег (если вы используете платные API), но и ускорение работы. Меньше токенов — меньше задержек. Меньше вызовов — меньше риска превышения лимитов.

Локальный характер zg обеспечивает безопасность данных, что критически важно для проектов с конфиденциальным кодом. Возможность работать без GPU делает его доступным для широкого круга пользователей. А гибкость выбора между семантическим, лексическим и точным поиском позволяет агентам принимать более обоснованные решения, снижая вероятность ошибок.

В долгосрочной перспективе zg может стать стандартом де-факто для локального поиска в кодовых базах, особенно в сочетании с развитием протокола MCP. Если вы используете AI-агентов для разработки, стоит обязательно попробовать zg и оценить, как он улучшит ваш рабочий процесс.

Вы можете ознакомиться с репозиторием zvec-grep, дорожной картой и руководством по MCP. Также следите за обновлениями в Twitter и присоединяйтесь к сообществу в Reddit.

Источник: MarkTechPost ↗