# zvec-grep **Repository Path**: howuger/zvec-grep ## Basic Information - **Project Name**: zvec-grep - **Description**: No description available - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-09-30 - **Last Updated**: 2026-09-30 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README

English | 中文

Know the words—or don’t. Just zg.

面向人与 Agent 的本地优先统一检索层。

**zg**（**z**vec-**g**rep），由 [zvec](https://github.com/alibaba/zvec) 驱动，将 ripgrep、BM25 与向量检索统一在一个[本地优先的检索入口](./docs/05-architecture.md)中。既可以由人在终端中搜索，也可以让 Agent 根据问题选择合适的本地检索方式。本 README 和[使用文档](./docs/README.md)以 TypeScript / Node.js 实现为主。 Rust 实现位于独立的 [`rust/`](./rust/README.md) 目录。 ## 🎬 功能演示

安装 Agent 集成、为工作区建索引并让 Agent 使用 zvec-grep 检索本地内容

## 💫 为什么选择 zg？ - **人与 Agent 开箱即用**：安装一次、索引一次，即可在 macOS、Linux 和 Windows 上通过 CLI 或 Agent 复用同一个工作区。 - **不止关键词搜索**：先按语义发现内容、按相关性排序，再在需要时使用精确文本或正则完成验证。 - **多格式检索**：搜索源代码、文档和结构化数据，同时保留有用的内容结构与来源位置。 - **更少搜索，更少上下文**：经过排序并保留来源的结果，可以减少工具调用、 Token 消耗与无关噪声，更快找到所需证据。 - **默认本地运行**：文件、索引与本地模型都留在本机；只有经过你的授权，远程 Embedding 服务才能接收数据。 ## 🚀 动手体验 ### 1. 准备示例书架 ```bash # 需要 Node.js 22 或更新版本。 npm install -g @zvec/zvec-grep mkdir zg-mystery && cd zg-mystery curl --retry 3 --retry-all-errors --progress-bar -fL \ -o alice-in-wonderland.txt https://raw.githubusercontent.com/GITenberg/Alice-s-Adventures-in-Wonderland_11/master/11.txt \ -o sherlock-holmes.txt https://raw.githubusercontent.com/GITenberg/The-Memoirs-of-Sherlock-Holmes_834/master/834.txt zg index --embedding local/potion-retrieval-32m ``` > [!NOTE] > 索引保存在被索引项目根目录的 `.zvec-grep/` 中。 > [!TIP] > `zg index` 或 `zg query` 失败时，在原命令后加 `--debug` 重跑，查看诊断信息（direct 和 server 模式均支持）。 > 在同一项目下，可用 `zg status --mode direct --debug` 或 > `zg status --mode server --debug` 查看已记录的索引错误。 > Server 连接失败时，检查 `zg server status` 和[服务日志](./docs/06-server.md#logs-and-state)。 ### 2. 选择检索方式 #### Agent：通过 OpenCode 提问配置好 [OpenCode](https://opencode.ai/) 后： ```bash zg install --target opencode --yes opencode models opencode run --model opencode/nemotron-3-ultra-free \ "An unseen creature left a few marks. What did the detective infer? Cite local evidence." ``` 免费模型的可用性可能变化。请通过 `opencode models` 检查，并将示例模型替换为当前环境中可用的模型。 Prompt 中没有指定任何工具，OpenCode 会自主选择 zg。

展开查看完整 Agent 调用与回答

```text ⚙ zvec_grep_zvec_grep_search {"root":".../zg-mystery","query":"An unseen creature left a few marks. What did the detective infer?","fts":["marks","unseen creature","inferred","detective"],"fuse":true} → Read sherlock-holmes.txt [offset=5440, limit=120] Answer: The detective is Sherlock Holmes in *The Adventure of the Crooked Man*. From the animal's foot-marks, he inferred: - It was not a dog, cat, monkey, or other familiar creature: its print had five foot-pads, long nails, and was nearly as large as a dessert-spoon (sherlock-holmes.txt:5479-5486). - It had a long body and very short legs: nearly two feet long, but with a stride of only about three inches (sherlock-holmes.txt:5497-5502). - It was carnivorous because it climbed the curtain toward a canary's cage (sherlock-holmes.txt:5509-5510). - It was probably from the weasel or stoat tribe, though unusually large (sherlock-holmes.txt:5514-5516). Holmes also inferred that a man entered through the window with it and later left with the key (sherlock-holmes.txt:5464-5470, 5527-5528). ```

#### 用户：直接检索不通过 Agent，直接搜索同一个书架： ```bash zg query --human "An unseen creature left a few marks. What did the detective infer?" --limit 3 ``` zg 会将 `sherlock-holmes.txt` 中的相关段落排在 `alice-in-wonderland.txt` 前面。 ### 索引 Embedding 并发与 GPU 错误 `zg --index --index-embedding-concurrency ` 和 `ZVEC_GREP_INDEX_EMBEDDING_CONCURRENCY` 控制构建或更新索引时的 Embedding 并发，对本地和远程模型均生效。环境变量也适用于自动建索引和刷新；这些设置不影响查询文本的向量推理。 CLI 参数仅与 `--index` 一起使用。对于 llama.cpp，上限控制索引模型实例的 context 数；对于 Transformers.js，控制同一缓存 pipeline 中尚未完成的调用数，不保证原生运行时或 GPU 同时执行。这两个后端取正整数，超过 **8** 按 8 处理。对于 Potion/model2vec，上限控制并发 Embedding 批次数，没有该 8 路限制；默认为 **2**，CPU worker 池还有独立容量上限。对于远程模型，CLI 参数和环境变量均控制并发批次数，也不额外限制为 8；原有自适应调度及默认值保持不变，遇到限流或可重试错误时可能降低并发。优先级为：显式 CLI/API 索引参数 > 索引环境变量 > `ZVEC_GREP_LLAMA_CONTEXT_PARALLELISM`（仅 llama.cpp 索引阶段）> 自动默认值。对于 llama.cpp 和 Transformers.js，未显式设置时，CPU 或没有显存查询接口的运行时使用 1。Transformers.js 目前没有该接口，因此自动上限为 1。 GPU 运行时提供空闲显存时，按 `floor(空闲显存 × 0.25 / 150 MiB)` 计算，并限制在 1–8；查询失败或返回无效值时使用 2。这里沿用原有的 150 MiB 启发式估算，不保证模型一定能装入显存。遇到 CUDA 错误、内存不足或原生运行时崩溃时，可将上限设为 1 后重试索引。以下示例使用直接执行模式，使新的环境变量立即生效： ```bash export ZVEC_GREP_INDEX_EMBEDDING_CONCURRENCY=1 zg --index --mode direct ``` Windows PowerShell： ```powershell $env:ZVEC_GREP_INDEX_EMBEDDING_CONCURRENCY = "1" zg --index --mode direct ``` 显式 CLI 参数会在本次索引操作中覆盖环境变量，使用后台服务时也会生效，无需为 CLI 参数重启后台服务： ```bash export ZVEC_GREP_INDEX_EMBEDDING_CONCURRENCY=8 zg --index --index-embedding-concurrency 1 ``` 若要修改后台服务的环境变量默认值，需更新其启动环境，然后在该环境中运行 `zg --server off` 和 `zg --server on`。如果由 Agent 启动 zg，还需更新其环境并重启 Agent/MCP 连接。JavaScript 异常可以捕获，但原生 abort 可能在 CPU 回退之前直接结束进程。将上限设为 1 可以降低并发，但不能避免所有 GPU 故障；也可使用 `--device cpu` 重试。 ## 📊 性能测试每项测试均采用配对 A/B 评测：任务、Agent/模型、Prompt、环境和资源限制保持一致，仅 zg 访问权限及使用说明不同。完整结果和复现细节参见[性能测试文档](./benchmarks/README_CN.md)。 ### 1. 跨领域 Agent Benchmark [SWE-QA-Bench](./benchmarks/swe-qa-bench/README_CN.md) 使用 Claude Code 与 Claude Opus 5（high 推理强度）； [BrowseComp-Plus](./benchmarks/browse-comp-plus/README_CN.md) 使用 Codex gpt-5.6-sol 与 medium 推理强度。两项测试中的 zg Profile 均使用 Qwen3.7 Text Embedding。

zg 在 Coding 和通用文本检索场景中的整体测试结果，对比 Baseline 的答案质量、输入 Token、工具调用和 Agent 耗时

- **为何有效：** 语义发现先收窄搜索范围，排序后的词法检索再锚定精确标识符；紧凑的证据结果减少了大范围扫描、重复工具调用和模型上下文。 - **为何通用：** 同一检索流程可以适配不同内容：代码索引保留符号、签名和层级路径，通用文本则按相关 section 与 chunk 返回证据。 ### 2. 真实案例分析

三个代码库理解任务中 Baseline 与 zg 的 Judge、输入 Token、工具调用和耗时对比

- **[Pylint](https://github.com/pylint-dev/pylint) — Python 静态分析器：** 任务需要理解 AST 节点处理如何区分带标注与不带标注的属性初始化；由于架构入口事先未知，保留符号与层级路径的检索更适合定位相关实现。 - **[Matplotlib](https://github.com/matplotlib/matplotlib) — 绘图与渲染库：** 任务需要沿数学文本渲染的多个阶段追踪 `FontInfo` 与字体选择；语义与词法联合排序有助于还原跨文件的数据流和控制流。 - **[Django](https://github.com/django/django) — Web 框架：** 任务关联 username 唯一约束、ORM 事务和 formset 批量操作；紧凑的排序证据便于汇集分散在多处的设计依据。

测试仓库与具体问题

| 仓库 | 问题类型 | 具体问题 | | --- | --- | --- | | **`pylint-dev/pylint`** | What
架构探索 | 使用 AST 节点类型区分带类型标注和不带类型标注的实例属性初始化时，采用了什么架构模式？ | | **`matplotlib/matplotlib`** | Where
数据 / 控制流 | `FontInfo` NamedTuple 在数学文本渲染 Pipeline 中如何传递字体度量和字形数据？控制流如何决定在字符渲染的不同阶段使用 `postscript_name` 还是 `FT2Font` 对象？ | | **`django/django`** | Why
设计原理 | User 模型中 username 字段的唯一约束为什么会与 Django ORM 事务处理产生关联？如果在已有数据库中移除该约束，会对基于 formset 的批量操作产生哪些级联影响？ |

| 💬 钉钉群 | 📱 微信群 | 🎮 Discord | X (Twitter) | | :---: | :---: | :---: | :---: | | 钉钉二维码

| [![Discord](https://img.shields.io/badge/Discord-Join%20Server-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/rKddFBBu9z) | [![X (formerly Twitter) Follow](https://img.shields.io/twitter/follow/ZvecAI)]() | | 扫码加入 | 扫码加入 | 点击加入 | 点击关注 |

## ❤️ 参与贡献始终欢迎社区贡献——缺陷修复、新功能和文档改进都会让 zvec-grep 变得更好。请查阅我们的[贡献指南](./CONTRIBUTING.md)开始参与！