如何为Pi智能编码助手搭建完全离线的本地知识库？

为 Pi 智能编码助手 设计的本地 BM25一种基于概率信息检索理论的文本检索模型，通过词频和逆文档频率对文档进行排名，考虑词项的相关性和稀有性。 RAG 流水线。索引您的本地文件并使用关键词匹配进行搜索——零云依赖，完全离线工作。

A local BM25一种基于概率信息检索理论的文本检索模型，通过词频和逆文档频率对文档进行排名，考虑词项的相关性和稀有性。 RAG pipeline for the Pi coding agent. Index your local files and search them with keyword matching — zero cloud dependency, works fully offline.

核心特性

• 混合 BM25一种基于概率信息检索理论的文本检索模型，通过词频和逆文档频率对文档进行排名，考虑词项的相关性和稀有性。 + 向量搜索 — 结合了 TF-IDF 评分（支持精确短语和文件名加权）与本地 ONNX 嵌入模型。
• 智能分块 — 在自然的空行边界处将文件分割成约 50 行的块。
• 增量索引向量数据库支持动态添加新文档而无需重建整个索引的技术，适用于数据持续更新的应用场景。 — 跳过未更改的文件（通过 SHA-256 哈希校验）。
• 零云依赖 — 仅使用 Node.js 内置模块和本地 Transformers.js 模型。
• 3 个 AI 工具 — 为智能体直接提供 rag_index、rag_query、rag_status 三个工具。

• Hybrid BM25一种基于概率信息检索理论的文本检索模型，通过词频和逆文档频率对文档进行排名，考虑词项的相关性和稀有性。 + vector search — TF-IDF scoring with exact phrase and filename boosts, combined with local ONNX embeddings.
• Smart chunking — splits files into ~50-line blocks at natural blank-line boundaries.
• Incremental indexing — skips unchanged files (SHA-256 hash check).
• Zero cloud dependency — uses only Node.js built-ins + local Transformers.js model.
• 3 AI tools — rag_index, rag_query, rag_status for the agent to use directly.

安装指南

通过 npm 安装：

pi install npm:pi-local-rag

pi install npm:pi-local-rag

或通过 git 安装：

pi install git:github.com/vahidkowsari/pi-local-rag

pi install git:github.com/vahidkowsari/pi-local-rag

命令参考

下表列出了所有可用的命令及其功能描述。

AI 工具集成

该扩展注册了三个工具，可供 Pi 智能体直接调用：

• rag_index — 将指定路径的内容索引到流水线中。
• rag_query — 执行混合 BM25一种基于概率信息检索理论的文本检索模型，通过词频和逆文档频率对文档进行排名，考虑词项的相关性和稀有性。+向量搜索，返回文件路径、行号和内容预览。
• rag_status — 显示索引统计信息和 RAG 配置。

The extension registers three tools the agent can call directly:

• rag_index — Index a path into the pipeline.
• rag_query — Hybrid BM25一种基于概率信息检索理论的文本检索模型，通过词频和逆文档频率对文档进行排名，考虑词项的相关性和稀有性。+vector search, returns file paths + line numbers + previews.
• rag_status — Show index stats and RAG config.

工作原理

1. 索引 — 文件被分块（每块约 50 行），使用 Xenova/all-MiniLM-L6-v2 模型（384 维）生成嵌入向量，并存储在本地目录 ~/.pi/rag/ 下。
2. 搜索 — 采用混合评分机制：alpha × BM25 + (1-alpha) × cosine_similarity（默认 alpha=0.4）。
3. 自动注入 — 在智能体的每个回合开始前，系统会自动搜索当前提示词，并将相关的文本块前置到系统提示中。

1. Index — files are chunked (50 lines each), embedded with Xenova/all-MiniLM-L6-v2 (384-dim), and stored locally at `/.pi/rag/`.
2. Search — hybrid scoring: alpha × BM25 + (1-alpha) × cosine_similarity (default alpha=0.4).
3. Auto-inject — before every agent turn, the prompt is searched and relevant chunks are prepended to the system prompt.

数据存储

索引数据存储在 ~/.pi/rag/ 目录下。如果您之前使用过此插件的旧版本（数据存储在 ~/.pi/lens/），系统会在首次运行时自动迁移目录。

Index data is stored at ~/.pi/rag/. If you previously used an older version of this plugin (~/.pi/lens/), the directory is automatically migrated on first run.

配置参数

自动上下文注入功能默认开启。您可以通过 /rag status 查看并调整以下配置参数：

Auto-injection is on by default. Tune via /rag status:

常见问题（FAQ）

Pi-Local-RAG 如何实现完全离线工作？

它仅使用 Node.js 内置模块和本地 Transformers.js 模型进行索引与搜索，所有数据存储在本地 ~/.pi/rag/ 目录，无需连接任何云服务。

这个 RAG 管道支持哪些搜索方式？

支持混合搜索：结合 BM25一种基于概率信息检索理论的文本检索模型，通过词频和逆文档频率对文档进行排名，考虑词项的相关性和稀有性。 关键词匹配（支持精确短语和文件名加权）与本地 ONNX 嵌入模型的向量相似度计算，通过可调参数平衡两者结果。

如何开始使用并索引我的文件？

通过 pi install npm:pi-local-rag 安装后，使用命令 /rag index <路径> 即可索引文件或目录，系统会智能分块并生成嵌入向量。