离网也能查资料：Off Grid AI 本地知识库 RAG 搭建教程，MiniLM 嵌入 + SQLite 检索原理一次讲透

【免费下载链接】OGAMThe Swiss Army Knife of Offline AI. Chat, see, speak, and generate images on your phone or Mac — GGUF LLMs, vision, Whisper speech-to-text, Stable Diffusion, tool calling, and local-network servers. Runs on your CPU, GPU, or NPU. No account, no API key, zero data leaves your device.项目地址: https://gitcode.com/gh_mirrors/of/OGAM

Off Grid AI是一款完全离网（无账号、无 API Key、数据不出设备）的端侧 AI 应用，它内置了本地知识库 RAG（检索增强生成）能力：把 PDF、TXT 等文档导入手机或 Mac，应用会用内置的MiniLM 嵌入模型将文档切块并生成向量，存入本地SQLite数据库；聊天时自动做余弦相似度检索，把最相关的片段注入提示词——全程 CPU 可跑，无需任何云服务。本教程带你从零理解这套 RAG 的搭建步骤与检索原理。

为什么需要"本地知识库"？

对于处理合同、病历、论文、内部手册等敏感资料的用户，"数据不出设备"就是最大的价值点。整个 RAG 模块的代码集中在 src/services/rag/ 目录，结构非常清晰：

• index.ts —— 对外统一的RagService（索引、删除、搜索）
• chunking.ts —— 文档分块
• embedding.ts —— MiniLM 嵌入服务
• database.ts —— SQLite 存储
• retrieval.ts + vectorMath.ts —— 语义检索与向量计算

搭建本地知识库：4 步索引流水线

在应用的"项目 → 知识库"页面（KnowledgeBaseScreen.tsx）选中文档后，ragService.indexDocument会自动执行一条四步流水线（见 index.ts）：

第 1 步：文本抽取（Extracting）

调用 documentService 从 PDF / TXT 中抽取纯文本，单文档最多处理 50 万字符。注意：如果是扫描版 PDF（纯图片、无文字层），由于端上没有 OCR，会明确提示"无法抽取文字"而不是静默失败。

第 2 步：分块（Chunking）

长文档会被切成若干小块（chunk），每块记录position序号。分块逻辑来自共享包@offgrid/rag（chunking.ts），保证"检索时命中的是一个小段落，而不是整篇文档"。

第 3 步：生成嵌入向量（Embedding）⭐ 核心

这一步由内置的MiniLM 嵌入模型完成，是本文的重点，下一节详述。

第 4 步：写入 SQLite（Indexing）

三张表协同工作（建表语句见 database.ts），数据库文件名为rag.db：

🔒原子性保障：如果第 3 步嵌入失败，应用会整体回滚刚插入的文档和分块，绝不留"只有文本没有向量"的半截索引（回滚逻辑见 index.ts）——因为这样的文档在语义检索中是"隐形"的。

MiniLM：应用内置的"轻量级"嵌入模型

嵌入模型不需要你下载——它已经打包在应用内：

• Android 端：all-MiniLM-L6-v2-Q8_0.gguf
• iOS 端：all-MiniLM-L6-v2-Q8_0.gguf

关键参数定义在 embedding.ts：

两个工程细节值得新手学习：

1. 全局加载锁：嵌入模型加载时会通过模型驻留管理器（modelResidency）加锁，确保它永远不会和聊天大模型同时初始化，避免内存峰值触发系统 OOM（embedding.ts）。
2. 30 秒超时兜底：原生加载被限时 30 秒，卡住会自动释放锁并清理，防止阻塞整个应用的模型加载（embedding.ts）。

检索原理：余弦相似度 + Top-K

提问时发生了什么？核心代码在 retrieval.ts：

1. 查询向量化：把你的问题用同一个 MiniLM 模型嵌入成 384 维向量；
2. 逐块打分：取出该项目下所有已启用文档的向量，计算余弦相似度（公式实现见 vectorMath.ts）——本质是"两个向量夹角的余弦值，越接近 1 语义越相近"；
3. 排序取 Top-K：默认取相似度最高的5 块；
4. 注入提示词：命中片段被包装成<knowledge_base>...</knowledge_base>块（retrieval.ts），连同来源文件名和块序号一起交给本地大模型作答。

💡 两个兜底设计让检索"永不空手"：

• 项目还没有任何向量时，退化为直接返回文档开头的若干块；
• 检索结果还会经过上下文预算控制（searchWithBudget），保证注入的片段不会撑爆当前 LLM 的上下文窗口。

在聊天中自动"查资料"

你不需要手动触发检索。发送消息时，聊天动作层会自动执行两步（useChatGenerationActions.ts）：

1. 调用ragService.searchProject(projectId, query)检索当前项目知识库；
2. 将结果格式化后追加到本轮生成请求中。

此外还有一个显式的searchKnowledgeBase工具（tools/handlers.ts），当模型判断"需要查资料"时可主动调用。知识库按项目隔离，不同项目的文档互不干扰；不需要的文档可以随时关闭（enabled 开关）或删除。

进阶：知识库的跨设备同步

Off Grid AI 还支持把知识库文档在多设备之间端到端加密同步（同步事件由 services/sync/knowledgeDocument 发出）。手机上的文档索引到 Mac 上，indexSyncedDocument会通过sync_id自动去重，同一文档在两台设备上各建一次向量索引，配对过程见 PERSONAL_MESH.md。

常见问题（FAQ）

Q1：支持哪些文档格式？PDF 和 TXT（粘贴文本也会被写入 .txt 后再走同一套索引流程，见 indexPastedText）。扫描版 PDF 无文字层，端上没有 OCR，会明确报错。

Q2：重复导入同一个文件会怎样？会被拦截并提示"已在知识库中"（按路径/文件名去重，index.ts）。

Q3：嵌入模型占内存吗？会影响聊天模型吗？约 90 MB 常驻预算，且可被内存管理器作为"旁路模型"驱逐；它永远不会驱逐你正在生成回复的大模型。

Q4：向量存在哪？用了专门的向量数据库吗？没有——就是普通 SQLite（rag.db）里的 BLOB 列，向量在内存里用 JS 计算余弦相似度。对个人级文档量（几千块）完全够用，这是刻意的简化取舍。

Q5：如何验证检索正确性？项目自带回归测试，例如知识库检索往返测试 searchKnowledgeBaseRoundtrip.test.ts 和嵌入契约测试 ragEmbedding.contract.test.ts。

相关源码与文档导航

• RAG 核心模块：src/services/rag/
• 知识库页面：KnowledgeBaseScreen.tsx
• 项目详情中的知识库区域：ProjectDetailKnowledgeBaseSection.tsx
• 嵌入模型加载（Android）：all-MiniLM-L6-v2-Q8_0.gguf
• 架构总览：docs/ARCHITECTURE.md
• 代码库导读：docs/standards/CODEBASE_GUIDE.md

写在最后

Off Grid AI 的本地知识库 RAG 证明了：RAG 不一定要云端向量数据库。一个 25 MB 的 GGUF 嵌入模型 + SQLite 的 BLOB 列 + 几十行余弦相似度代码，就足以在手机上构建一个完全私密的"离线资料库"。理解这条"抽取 → 分块 → 嵌入 → 检索"的流水线后，你也能在自己的项目里复刻它。

【免费下载链接】OGAMThe Swiss Army Knife of Offline AI. Chat, see, speak, and generate images on your phone or Mac — GGUF LLMs, vision, Whisper speech-to-text, Stable Diffusion, tool calling, and local-network servers. Runs on your CPU, GPU, or NPU. No account, no API key, zero data leaves your device.项目地址: https://gitcode.com/gh_mirrors/of/OGAM