zg – Zvec AI 开源的本地优先统一检索基础工具
不想看长文？关于 zg 的高频问题，下面用问答直接说清楚。
zg核心问答
zg是什么，主要解决什么问题
zg（zvec-grep） 是 Zvec AI 开源的本地优先统一检索基础工具，面向开发者与 AI Agent。工具将 ripgrep 精确匹配、BM25 词法检索与向量语义检索融为一体，解决自然语言意图与代码/文档实际表述之间的词汇鸿沟，实现从模糊探索到精确定位的完整检索链路。zg支持文件扫描、Embedding、索引与检索默认全部在本地设备完成，内置轻量端侧模型，无需 GPU 或外部服务，兼顾隐私与效率。
zg开源吗
zg已开源（正文已说明其开源版本与本地部署方式），具体许可协议以官方仓库公示为准。
zg怎么上手 / 怎么用
访问官网或对应平台（文内链接）注册或下载即可体验；开源版本按官方仓库说明本地部署，消费级显卡大多能跑。
功能细节
zg 是什么
zg（zvec-grep） 是 Zvec AI 开源的本地优先统一检索基础工具，面向开发者与 AI Agent。工具将 ripgrep 精确匹配、BM25 词法检索与向量语义检索融为一体，解决自然语言意图与代码/文档实际表述之间的词汇鸿沟，实现从模糊探索到精确定位的完整检索链路。zg支持文件扫描、Embedding、索引与检索默认全部在本地设备完成，内置轻量端侧模型，无需 GPU 或外部服务，兼顾隐私与效率。
zg 的主要功能
- 语义检索：按自然语言意图发现代码与文档中的相关内容，无需预先猜准关键词。
- BM25 检索：基于词频加权对文本片段进行相关性排序，快速聚焦最匹配的结果。
- 混合检索：联合语义向量与 BM25 多路召回，通过 RRF 融合去重并统一排序。
- ripgrep 精确匹配：对已知符号、函数名、配置键或文本模式进行穷尽式精确验证。
- 多格式内容提取：自动解析代码符号层级、文档章节结构及数据文件，保留定位元数据。
- 本地端侧 Embedding：内置 11 种轻量模型，默认设备内运行，无需 GPU 或上传数据。
- 嵌入式索引存储：基于 Zvec 进程内数据库实现向量与 BM25 索引，无需部署独立服务。
- 增量索引更新：首次构建后仅处理变更内容，索引可跨查询与 Agent 任务长期复用。
- CLI + MCP 双入口：提供命令行供人使用，同时通过 MCP 协议供 Codex、Cursor 等 Agent 调用。
- 自动 Agent 集成：
zg install一键自动发现本机已安装的 Agent 并完成 MCP 配置。
如何使用zg
- 安装：通过
npm install -g @zvec/zvec-grep全局安装 zg 工具。 - 配置：运行
zg install自动发现本机已安装的 Codex、Cursor 等 Agent 并完成 MCP 集成。 - 建索引：进入目标仓库目录，执行
zg index为代码和文档构建本地语义与 BM25 索引。 - CLI 检索：在终端通过
zg query --human "你的问题"用自然语言搜索本地内容。 - Agent 检索：在已连接的 Agent 中直接自然语言提问，Agent 自动通过 MCP 调用 zg 完成检索。
zg的核心优势
- 统一检索范式：将语义发现、BM25 排序与 ripgrep 精确匹配整合为一条完整检索链路，覆盖从模糊意图到符号验证的全流程。
- Agent 原生设计：通过 MCP 协议深度集成主流 Agent，实测可减少 40% 以上工具调用与 Token 消耗。
- 本地优先隐私：文件扫描、Embedding、索引与检索默认全部在设备内完成，无需上传任何内容。
- 端侧轻量模型：内置 11 种端侧 Embedding 模型，默认 16M 参数即可运行，无需 GPU 或远程 API。
- 嵌入式零依赖存储：基于 Zvec 进程内数据库实现向量与 BM25 索引，无需部署和维护独立数据库服务。
- 增量索引复用：首次构建后仅处理变更内容，同一份索引可供 CLI 与多个 Agent 任务长期共享复用。
- 结构化内容提取：自动解析代码符号层级、文档章节结构及元数据，让检索结果可定位、可验证。
- 一键 Agent 集成：
zg install自动发现本机 Codex、Cursor、Claude Code 等并完成 MCP 配置。
zg的项目地址
- GitHub仓库：https://github.com/zvec-ai/zvec-grep
zg的同类竞品对比
| 对比维度 | zg（zvec-grep） | ripgrep（rg） |
|---|---|---|
| 核心定位 | 本地优先的统一检索基础设施（语义 + BM25 + 精确匹配） | 高性能的递归正则文本搜索工具 |
| 检索能力 | 语义检索、BM25、混合检索、ripgrep 精确匹配四合一 | 支持基于正则的精确文本匹配 |
| 自然语言查询 | ✅ 支持，可按意图发现相关内容（如”恢复主题偏好”→hydratePreferences） |
❌ 不支持，必须提供准确关键词或正则模式 |
| 结果排序 | 多路召回后通过 RRF 融合去重并统一相关性排序 | 按文件遍历顺序输出，无相关性排序 |
| 内容结构化 | 自动提取代码符号层级、文档章节结构，保留元数据 | 纯文本行级匹配，不识别代码/文档结构 |
| Agent 集成 | 原生 MCP 支持，自动配置 Codex / Cursor / Claude Code | 无原生 MCP，Agent 需通过 shell 调用并自行解析输出 |
| 索引机制 | 预建本地语义+BM25索引，支持增量更新与长期复用 | 无索引，每次搜索实时遍历文件系统 |
| 本地优先 | 端侧 Embedding + 嵌入式索引，默认零外部依赖 | 完全本地，但无语义能力 |
| 适用场景 | 模糊意图探索 → 相关性聚焦 → 精确验证的完整链路 | 已知符号、函数名、错误信息的快速穷尽匹配 |
| 隐私保障 | 默认全本地处理，远程 Embedding 需显式授权 | 完全本地，不涉及任何外部传输 |
zg的应用场景
- 代码库意图探索：开发者或 Agent 用自然语言描述业务现象，zg 语义检索定位到代码中
hydratePreferences或文档中”账号授权与审批”的相关实现。 - 故障定位与根因分析：面对报错日志或用户反馈的模糊描述，Agent 通过 zg 语义检索快速发现相关代码路径、配置文件和文档说明，减少多轮搜索和无关文件读取。
- 跨文件代码理解：在大型代码库中理解某个功能的全链路实现时，用自然语言提问可获取跨模块、跨语言的相关函数、接口定义和调用关系，避免在目录树中手动遍历。
- 本地知识库问答：将技术文档、研究资料、笔记等 Markdown/文本文件建立索引后，通过自然语言查询快速获取准确答案，附带来源文件与具体章节定位。
再展开聊聊
zg（zvec-grep） 是 Zvec AI 开源的本地优先统一检索基础工具，面向开发者与 AI Agent。工具将 ripgrep 精确匹配、BM25 词法检索与向量语义检索融为一体，解决自然语言意图与代码/文档实际表述之间的词汇鸿沟，实现从模糊探索到精确定位的完整检索链路。zg支持文件扫描、Embedding、索引与检索默认全部在本地设备完成，内置轻量端侧模型，无需 GPU 或外部服务，兼顾隐私与效率。
常见问题
zg是什么，主要解决什么问题
zg（zvec-grep） 是 Zvec AI 开源的本地优先统一检索基础工具，面向开发者与 AI Agent。工具将 ripgrep 精确匹配、BM25 词法检索与向量语义检索融为一体，解决自然语言意图与代码/文档实际表述之间的词汇鸿沟，实现从模糊探索到精确定位的完整检索链路。zg支持文件扫描、Embedding、索引与检索默认全部在本地设备完成，内置轻量端侧模型，无需 GPU 或外部服务，兼顾隐私与效率。
zg开源吗
zg已开源（正文已说明其开源版本与本地部署方式），具体许可协议以官方仓库公示为准。
zg怎么上手 / 怎么用
访问官网或对应平台（文内链接）注册或下载即可体验；开源版本按官方仓库说明本地部署，消费级显卡大多能跑。
zg和同类工具比，选哪个
zg侧重「Zvec AI 开源的本地优先统一检索基础工具」；选哪个看你是个人尝鲜还是企业落地，建议先试免费或开源版再决定。
zg适合谁用，不适合谁
适合想快速体验新能力、做原型或本地部署的开发者与爱好者；涉及生产级稳定性、合规审计的场景，先评估再上车，别直接当关键链路。
评论(0)