Vexor：AI时代的语义文件搜索利器Vexor 是一款基于向量嵌入的智能命令行工具，让你在终端中以语义方式快速搜索文件

背景与挑战

在现代软件项目中，代码和文档库通常体量庞大、结构复杂。开发者经常记得某个文件的作用，却忘记它具体的文件名或目录。这时只能依赖手动浏览或关键词匹配的 grep，既低效又容易遗漏。面对这种痛点，Vexor 应运而生。

项目简介

Vexor 是由 scarletkc 发布的一款开源命令行工具，它利用向量嵌入和余弦相似度实现语义文件搜索。项目主页的说明指出，Vexor “是一个基于向量的命令行工具，可对文件进行语义搜索，并支持可配置的远程嵌入模型”github.com。它不仅适合人与人的交互，还专门为 AI 编程助手等自主代理设计，能够在终端内轻松完成语义检索github.com。

在一次简单的搜索中，用户不必记住复杂的正则表达式。当你记得文件实现了某个功能，却想不起文件名或路径时，Vexor 的语义搜索可以立即找到它——再也不需要遍历目录或构造 grep 模式github.com。

核心功能与亮点

语义向量搜索：Vexor 采用向量嵌入模型对文件名和内容进行编码，并用余弦相似度评估查询与文件之间的语义相关性github.com。因此它能理解语义关联，而不仅仅是字面匹配。
灵活的嵌入模型：默认使用 Google 的 Gemini 嵌入模型，可根据需要切换至 OpenAI 等其他提供方。用户可通过 vexor config --set-provider 指定提供商，并指定模型名称github.com；也可指定自定义的代理地址或使用本地推理服务github.com。
可配置的索引模式：索引建立时可选择不同的模式，以适应性能与精度的需求github.com：
- name：仅嵌入文件名，速度最快，适合快速定位文件github.com。
- head：抓取支持格式文件的开头片段（文本/代码/PDF/DOCX/PPTX），提供轻量级语义上下文github.com。
- brief：对需求文档和 PRD 提炼高频关键词或摘要，可用于定位关键需求github.com。
- full：对支持的文本、代码或 Office 文件进行分块嵌入，使长文档也能端到端搜索github.com。
丰富的命令行工具：Vexor 提供一系列命令，其中 index 根据指定路径生成嵌入索引；search 根据用户查询返回最相似的文件；doctor 检查安装状态；update 检查新版本；config 用于设置 API 密钥、模型和其他默认参数github.com。此外，config --show-index-all 和 config --clear-index-all 可以查看或清除所有缓存索引github.com。
高效缓存与增量更新：Vexor 将索引缓存到 ~/.vexor 目录，重新运行 vexor index 时，仅重新嵌入名称发生变化的文件；当超过一半文件发生变化时才回退到完整重建github.com。这种设计保证了索引更新效率。
灵活的搜索过滤选项：在搜索时可以使用 --include-hidden 包含隐藏文件，--no-recursive 限制为当前目录，--ext 指定特定扩展名等github.com。这些选项让用户能够精准控制搜索范围。
AI 代理友好：项目文档强调 Vexor 面向人与 AI 编程助手的无缝使用github.com。这意味着它可以嵌入到自主代理工作流中，帮助自动化工具在大型代码库中查找相关文件。
丰富的文档格式支持：除源代码外，Vexor 还支持对 PDF、Word、PowerPoint 等文件建立索引github.com。这使它不仅适合开发者，也适用于需要搜索产品文档、需求说明或报告的团队。

索引模式与用途

下表概述了 Vexor 的主要索引模式及适用场景github.com：

模式	描述	适用场景
`name`	仅对文件名进行嵌入，速度快，不读取文件内容github.com	快速定位文件，适合大型仓库
`head`	获取文本/代码/PDF/DOCX/PPTX 文件的开头片段作为语义上下文github.com	需要少量上下文但避免完整读取文件
`brief`	提炼需求文档的关键词和摘要，支持中英双语github.com	产品需求文档、PRD 索引
`full`	分块嵌入整个文件内容，使长文档端到端搜索github.com	深入搜索代码或长篇文档

安装与配置

Vexor 可以通过 pip 或者下载已构建的发行包进行安装。官方文档建议使用 pip：

pip install vexor  # 或者使用 pipx、uv

安装完成后，命令行入口为 vexorgithub.com。首次使用需配置嵌入模型的 API 密钥。默认使用 Gemini 提供商，可通过以下命令设置：

vexor config --set-api-key "YOUR_KEY"

还可以设置默认模型、批量大小、提供商和自定义代理地址github.com。例如切换到 OpenAI 提供商的示例：

vexor config --set-provider openai
vexor config --set-model text-embedding-3-small
export OPENAI_API_KEY="sk-..."  # 或使用 vexor config --set-api-key

所有配置都会存储在 ~/.vexor/config.json 中github.com。

使用流程示例

一个典型的工作流程包含两步github.com：

生成索引：在项目根目录执行索引，支持递归遍历并可包括隐藏文件。例如：
```
vexor index --path ~/projects/demo --mode name --include-hidden
```
执行语义搜索：在任何目录下使用相同的 --path 指向索引位置，输入自然语言查询并设定返回条数：
```
vexor search "api client config" --path ~/projects/demo --mode name --top 5
```

Vexor 会输出相似度排名、文件路径和简短预览github.com。例如，查询 “api client config” 时，结果显示 config_loader.py、config_parse.py 等文件与查询最相关github.com。

针对大型项目，可以为不同根目录生成多个索引；当只需要当前目录的索引时，可使用 --no-recursive 选项github.com。若只想搜索特定文件类型，如 .py 或 .md，则可重复使用 --ext 参数github.com。

使用场景与优势

开发者的记忆助手：当你记得某段代码的功能却忘记文件名时，Vexor 能通过自然语言检索快速定位。它支持多个文件类型，适用于混合项目和文档仓库。
AI 编程代理的伙伴：很多自主代理需要在项目中查找相关文件，Vexor 可以作为其语义检索模块，为智能工具提供上下文github.com。
文档团队的搜索引擎：对于大量需求文档、规范或报告，使用 brief 或 full 模式生成索引，就能在秒级范围内定位关键段落github.com。

开源社区与未来展望

该项目采用 MIT 开源许可证github.com。截至 2025‑11‑11 已发布多个版本，并在 GitHub 上获得 14 颗星、2 次 forkgithub.com。维护者鼓励社区贡献代码、提交问题并提出改进建议github.com。

未来随着向量数据库和大语言模型的快速发展，Vexor 有望集成更多嵌入模型和检索策略，为开发者提供更智能的文件导航体验。欢迎访问其仓库了解详情并加入贡献者行列。

视觉示意

下面的插图展示了 Vexor 所代表的语义检索概念：向量节点连接着不同类型的文件图标，中央的放大镜象征搜索，呈现出未来感的蓝紫配色：

结语

Vexor 用现代向量技术颠覆了传统的文件搜索方式。它的多模式索引和灵活配置让开发者能够针对不同项目和需求快速构建语义索引，减轻记忆压力，提升工作效率。无论你是软件开发者、技术写作团队，还是在构建 AI 自动代理，Vexor 都是值得尝试的新工具。赶快安装体验，开启语义搜索的新旅程吧！