纯本地私人文档知识库搭建与运行指南

预览

本文详细介绍的是一款名为PrivRAG的开源工具，专注于私密文档的智能问答。其核心理念是在本地安全环境中，让AI基于用户自有文档回答问题，同时确保数据始终留存在本地设备中。

项目地址

GitHub仓库地址：github.com/SpanManX/pr…

安装包下载地址：github.com/SpanManX/pr…

核心特点

PrivRAG拥有多个引人注目的核心特性。首先，所有文档和对话均在本地处理，绝不对外传输，从根本上杜绝数据外泄风险。其次，它支持双模式灵活切换：既可调用本地大模型，也能使用在线API，适应不同场景。在格式兼容性方面，PDF、Word、Excel、Markdown、TXT等常见文档均可无缝导入。最突出的当属其RAG智能问答功能——用户可与文档进行自然对话，回答时自动提供引用来源，避免生成虚假信息。此外，该工具开箱即用，内置模型管理模块，无需繁琐配置。

解决什么问题

在日常办公中，用户常面临以下痛点：将机密文档上传至在线AI服务时，始终担忧数据泄露风险；面对大量文档，想快速定位某个知识点却无从下手；需要从Excel或Word报告中提取信息，但不愿逐个打开翻阅；向AI提问关于自有文档的问题，却得到一本正经的虚假答案。

PrivRAG正是为化解这些困扰而设计。用户只需导入文档，然后像与人交流一样自然提问。系统会从文档中精准检索答案，不会凭空捏造，且全过程在本地运行，数据安全得到充分保障。

什么是 RAG

RAG全称为Retrieval Augmented Generation，即检索增强生成。传统做法是将文档内容直接填入提示词（prompt），但文档一多便装不下，AI也容易“遗忘”前文。

而RAG的工作流程截然不同：文档经过切分、向量化处理后存入向量数据库；用户提问时，系统将问题同样向量化，在数据库中检索出最匹配的若干片段；随后将这些片段与问题一同输入大语言模型（LLM）生成答案。这样一来，无论文档规模多大，都能精准定位最相关的内容，效果显著。

功能展示

文档导入

支持拖拽或点击上传，可批量处理多个文件。兼容格式包括PDF（论文、合同、手册）、Word（报告、方案、文档）、Excel（表格、数据、报表）、Markdown（笔记、教程）以及TXT（纯文本）。导入后自动进行文本分块与向量化，存入本地数据库，全程离线完成，无需网络连接。

智能问答

提问方式十分自然，例如：“这份合同的关键条款有哪些？”“对比这两个报告的营收数据”“关于XXX问题的解决方案是什么？”系统回答时会附上引用来源，明确标注信息来自哪个文档及匹配度，既便于核实，也利于溯源。

双模式自由切换

PrivRAG支持在本地大模型与在线大模型之间自由切换。本地模式具备完全离线、保护隐私、节省API费用等优势，适用于处理敏感文档、频繁问答或无网络环境；在线模式则答案质量更高、响应速度更快，无需本地算力，适合追求最佳效果、具备稳定网络或偶发性使用场景。切换操作非常简单：进入设置页面，选择所需模式并按需配置即可完成。本地模式采用Qwen3-4B GGUF量化模型（约2.5GB），仅需4GB显存即可运行。在线模式兼容OpenAI标准API，可接入GPT-4o、Claude等模型。

流畅体验

流式输出带来打字机般的逐字显示效果，若对回答不满意可随时中断；Markdown渲染功能确保代码、表格、列表等格式正常呈现；基于Electron桌面框架构建，兼容Windows、macOS、Linux，提供流畅原生体验。

技术架构

技术栈

为什么选这些技术

Qwen3-4B GGUF是一款4B参数模型，经量化后体积约2.5GB，常规4GB显存即可流畅运行。即便没有独立显卡，仅依靠CPU也能正常推理（速度相对较慢）。LanceDB作为嵌入式向量数据库，所有数据存储于单个文件内，程序关闭后数据仍可持久保留，无需像Milvus或Pinecone那样额外部署服务。llama.cpp是采用C++编写的高效LLM推理库，跨平台且支持GPU加速，并通过llama-server封装为HTTP服务供前端直接调用。bge-small-zh-v1.5则是专为中文优化的Embedding模型，体积仅有几十MB，速度快且效果出色。

工作流程

文档导入流程：用户上传PDF、DOCX、XLSX、MD或TXT文件后，通过文档解析提取纯文本，随后进行文本分块（每块512字符），利用bge-small-zh-v1.5模型进行Embedding向量化（384维），最终存入LanceDB向量数据库（本地文件）。所有操作均在本地完成。

查询流程分为两种模式。本地模式下，用户提出问题后，系统对问题进行向量化处理，在LanceDB中执行向量相似度检索，获取Top-K最相关的文本块，最终由Qwen3-4B GGUF模型生成答案，并附上引用来源。在线模式则在向量检索后构建RAG提示词（Prompt），然后调用在线API（如GPT-4o、Claude等）生成答案，同样附带引用来源。

? 文档导入流程：PDF/DOCX/XLSX/MD/TXT → 文档解析提取纯文本 → 文本分块512字符 → bge-small-zh-v1.5 Embedding → LanceDB存储

? 查询流程（本地模式）：用户提问 → 问题向量化 → 向量相似度检索Top-K → Qwen3-4B GGUF生成回答 → 回答+引用来源

? 查询流程（在线模式）：用户提问 → 问题向量化 → 向量相似度检索Top-K → 构建RAG Prompt → GPT-4o/Claude等生成回答 → 回答+引用来源

快速上手

环境要求

下载安装（推荐）

前往Releases页面下载最新发行版本，双击安装包即可完成安装。

从源码运行

# 克隆仓库
git clone https://github.com/SpanManX/private-RAG.git
cd private-RAG
# 安装依赖包
npm install
# 构建项目
npm run build
# 启动开发服务器
npm run dev
# 构建Windows安装包
npm run build:win

使用步骤

第一步：首次启动时，系统会提示下载模型文件（约3GB），点击下载并等待完成。第二步：打开设置页面，选择使用本地大模型或在线大模型。本地模式下载后即可直接使用；在线模式需配置API地址、密钥和模型名称。第三步：点击侧边栏的“上传文件”按钮，或直接拖拽文件至窗口，支持多选，可一次性导入多个文档。第四步：点击侧边栏的“启动”按钮。若配备NVIDIA显卡，系统会自动启用GPU加速；无显卡则自动回退至CPU模式。第五步：在对话框输入问题，AI将从已导入的文档中检索答案。回答完成后会显示引用来源，点击可跳转至原文。

常见问题

Q: 需要联网吗？
A: 本地模式完全无需联网。在线模式在首次配置完毕后，即使离线也可使用（API密钥已本地保存）。

Q: 没有显卡能用吗？
A: 可以改用CPU模式，仅推理速度相对稍慢。

Q: 文档安全吗？
A: 所有数据处理均在本地进行，不会上传任何数据至服务器。

Q: 支持Mac/Linux吗？
A: 代码层面兼容Mac和Linux，但目前仅提供Windows版本的Release。如有需要，可自行编译。

Q: 本地模式和在线模式哪个好？
A: 本地模式适用于处理敏感文档及高频使用场景，可节省API费用。在线模式则更适合追求最佳答案质量与快速响应的情况。

Q: 支持哪些在线API？
A: 支持OpenAI兼容API，涵盖OpenAI GPT系列、Claude（通过API兼容接口）、本地部署的Llama/Ollama等模型。