Qwen开源zg：统一ripgrep/BM25/向量搜索的本地搜索层

人工智能

编程 agent 在工具调用预算中，有相当大一部分花在了搜索上。当目标是已知的符号时，ripgrep 能精确命中；当目标是用自然语言描述的行为时，关键字匹配常常落空，agent 只能退回到猜测词条、阅读整个文件、手动拼凑上下文。这些绕路每一次都要消耗工具调用次数、token 数量和墙上时间。

Qwen Developer 团队宣布开源 zg（zvec-grep），这是一个本地优先的搜索层，将语义搜索、BM25 和 ripgrep 统一在一个界面下，无论对人还是对 agent 都适用。代码发布在 zvec-ai GitHub 组织下，采用 Apache 2.0 许可证。

能部署吗？能，今天就能。通过 npm 安装 @zvec/zvec-grep，需要 macOS、Linux 或 Windows 上的 Node.js 22 或更高版本，默认模型无需 GPU，Apache 2.0 许可证允许商业使用。

一个索引，四条检索路径

zg 只需对工作区建立一次索引，随后暴露多种查询方式。检索管线的文档定义了四条路径：默认的 hybrid 模式结合意图与词法锚点；--fts 模式做 BM25 排序的精确词项搜索；--vector 模式做概念相似性检索，不做词法排序；--rg 模式做穷举的字面或正则匹配。前三条路径读取索引。--rg 路径完全不需要索引，这在代码库尚未建立索引时尤为重要。

一个匿名的 workspace 索引存放在 <root>/.zvec-grep/ 下。.git 和 .zvec-grep 始终被排除在外，常见的依赖目录、构建目录、缓存目录、日志目录，以及代码库自身 ignore 规则排除的内容也都会被排除。重新运行 zg index 会增量更新；更换 embedding 模型则需要显式加 --rebuild，因为不同模型的向量空间即使维度相同也无法兼容。

索引结果会报告新鲜度状态为 fresh 或 possibly_stale，这样 agent 可以在拿到"足够好"的结果后直接行动，而不必先跑一次状态预检。

Agent 实际看到的 MCP 接口

zg install 会检测机器上的 Codex、Claude Code、Cursor 和 OpenCode，并配置好本地 MCP 集成。服务器通过 Streamable HTTP MCP 协议在回环地址 http://127.0.0.1:7999/mcp 上通信，支持可选的 bearer 认证。

值得注意的设计决策是克制。依照 MCP 指南，默认的 agent 工具集只暴露两个工具：zvec_grep_search 用于意图已知但精确字符串未知的情况，zvec_grep_rg 用于符号、路径或正则已知的情况。索引生命周期由 CLI 负责。还有一个六工具的兼容集合（包含 index create、drop、status 和 server status），但需要通过 zg server --mcp-toolset full 手动开启，文档明确指出 agent 不得静默创建、重建或删除持久化索引。

输出格式为节省上下文而优化。结果按文件分组返回，带有行范围，且默认省略索引源的预览片段，除非显式请求。zg 同样拒绝会改变输出格式的 ripgrep 选项，如 --json、--count、-l 和 --vimgrep，以保证紧凑的结果格式始终一致。

Embedding 默认在设备上运行

当前 embedding 目录记录了十个本地模型和三个远程 Qwen 端点。快速开始默认使用 local/potion-code-16m-v2，这是一个 Model2Vec 静态模型，输出维度为 256，输入限制为 8,192 token；由于采用静态向量查找，选择 GPU 不会提速。更重的本地选项包括 jina-embeddings-v2-base-code、embeddinggemma-300m 和 qwen3-embedding-0.6b。远程选项包括 qwen/qwen3.7-text-embedding（128,000 token 输入）和多模态的 qwen/qwen3-vl-embedding。

远程使用有门控。配置提供方凭据并不会授权数据传输，需要通过 --allow-remote 执行单次命令，或通过 zg auth grant 签署工作区授权（可由 zg auth revoke 撤销）。发布博文列出了十一个设备端模型，而当前文档中只有十个，这里有一个值得注意的小差异。

基准数据说了什么

评估数据出现在发布博文中，而非代码库里——那里的 benchmarks 部分仍是占位符。两次运行均为配对 A/B 测试，固定了 agent、模型、提示词、运行时和任务约束，zg 这边只额外增加了预建索引、MCP 工具和使用指导。索引构建成本不计入表格。

在 20 题的 SWE-QA-Bench 样本上，zg 将工具调用次数削减了一半以上，输入 token 削减近一半，Judge 分数提升了 1.50 分。在 80 题的 BrowseComp-Plus 样本上，准确率从 98.67% 提升到 99.00%，同时输入 token 下降 37.56%、工具调用下降 43.52%、agent 时间下降 38.58%。另外，据报告在 Apple M4 Pro 上对 Django 代码库（3,457 个文件）建立索引可在 30 秒内完成。

样本量 20 和 80 都比较小，而且报告的削减数据来自厂商自己的运行，所以独立复现是显而易见的后续步骤。

交互式讲解

zg 在一个本地优先的界面下统一了 ripgrep、BM25 和向量搜索，对人和 agent 都适用。

默认 MCP 工具集只暴露两个工具；索引生命周期由 CLI 负责，这是设计决策。

索引、embedding 和检索都在设备上运行；远程 embedding 需要显式的单次命令授权或工作区授权。

厂商 A/B 运行报告在小样本上工具调用和输入 token 约削减 40% 到 50%。

Apache 2.0，可通过 npm 安装，Node.js 22+，默认模型无需 GPU。

更多资源

查看 zvec-ai/zvec-grep、Qwen Developers 发布博文和路线图。也欢迎关注我们的 Twitter，记得加入我们的 15 万+ ML SubReddit 并订阅我们的 Newsletter。对了，你用 telegram 吗？现在也可以加入我们了。

想与我们合作推广你的 GitHub 仓库、Hugging Face 页面、产品发布或网络研讨会吗？联系我们。

Michal Sutter 是数据科学专业人士，持有帕多瓦大学数据科学理学硕士学位。在统计分析、机器学习和数据工程方面基础扎实，擅长将复杂数据集转化为可操作的洞察。