如何 10 分钟搭建私有知识库:Kwipu 本地 Graph RAG 安装与快速上手教程
如何 10 分钟搭建私有知识库:Kwipu 本地 Graph RAG 安装与快速上手教程
Kwipu 是一款完全运行在本地的 Graph RAG 引擎,可以把你的 Markdown 笔记文件夹变成可提问的私有知识库:它从笔记的 wikilinks 和 YAML frontmatter 中提取实体-关系三元组,再通过向量 + BM25 + 时间元数据的混合检索,让 Ollama 上的大模型给出带引用来源的答案。支持 Obsidian vault 或任意 Markdown 文件夹,无需云端服务,终端、3D Web 界面、MCP 客户端三种方式随时查问。
Kwipu 是什么?核心功能一览 🧠
简单说,Kwipu = 笔记文件夹 → 属性图索引 → 可提问的第二大脑。它的核心能力:
- 📚 从
.md、.txt、.pdf、.docx文档构建属性图(property graph) - 🔗 用 LLM 提取语义关系,同时从
[[wikilink]]和 YAML frontmatter 提取结构关系 - 🔍 混合检索:向量相似度 + BM25 + 时间元数据,答案附带原文引用
- 🕸️ 交互式 3D 图谱可视化实体、文档和关系,点击节点查看上下文卡片
- 👀 监视源文件夹,笔记变更自动增量更新索引
- 🌐 多语言支持(英、意、法、德、西、葡语模式)
下图展示了 Kwipu 的 Web 界面:左侧提问并获得带来源的回答,中间是 3D 知识图谱,右侧是节点的属性、链接和引用详情:
Kwipu 本地 Graph RAG Web 界面:3D 知识图谱、问答与引用来源面板
安装前准备:4 个前置条件
| 软件 | 用途 | 是否需要 |
|---|---|---|
| Git | 下载 Kwipu 仓库 | ✅ 必需 |
| Python 3.12+ | 运行核心引擎与索引器 | ✅ 必需 |
| Ollama | 本地运行 LLM 与嵌入模型 | ✅ 必需 |
| Node.js + npm | 运行 3D Web 前端 | ⭕ 仅 Web 界面需要 |
⚠️ 提醒:只用终端提问的话,前 3 项就够了,不需要 Node.js。
验证安装(打开终端逐个执行):
git --version
python3.12 --version
ollama --version
node --version # 仅 Web 界面需要
快速上手:6 步完成本地 Graph RAG 安装
第 1 步:下载 Kwipu 并安装依赖
git clone https://gitcode.com/gh_mirrors/kw/Kwipu
cd Kwipu
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip==25.1.1
python -m pip install -r bridge/requirements.txt
# 仅 Web 界面需要:
npm --prefix frontend ci
bridge/requirements.txt 已包含核心终端依赖,一套 Python 环境同时支持终端和 Web 两种界面。
第 2 步:放入你的笔记文档
仓库自带一套演示文档,放在 knowledge_base/examples/ 目录下(Alice、Bob、Project Alpha 等示例笔记),零配置即可体验。要用自己的文件,把 .md、.txt、.pdf、.docx 复制到 knowledge_base/ 目录下即可:
Kwipu/
└── knowledge_base/
├── examples/ # 内置演示文档
└── your-notes/ # 你自己的笔记
Kwipu 只读取源文档,不会修改你的任何笔记。
第 3 步:拉取 Ollama 模型
确保 Ollama 正在运行(桌面版通常已自带服务),然后拉取嵌入模型 + 一个 LLM:
# 本地模型(推荐,数据完全不出机器):
ollama pull qwen2.5:7b
# 或云端默认模型(文档内容会发送到模型提供方,慎用!):
# ollama pull gpt-oss:20b-cloud
# 嵌入模型(始终在本地运行):
ollama pull nomic-embed-text
🔐 关于"完全本地":默认的 gpt-oss:20b-cloud 可能把文档分块和问题转发到云端。若要保证数据不出本机,请选用 qwen2.5:7b 这类本地模型。
第 4 步:设置环境变量
export KWIPU_ROOT_DIR="$PWD"
export KWIPU_KNOWLEDGE_DIR="knowledge_base"
export KWIPU_STORAGE_DIR="storage_graph"
export KWIPU_EMBED_MODEL="nomic-embed-text"
export KWIPU_OLLAMA_BASE_URL="http://localhost:11434"
export KWIPU_LLM_MODEL="qwen2.5:7b"
这些变量由 kwipu_config.py 统一解析,进程启动时读取,修改后需重启对应进程。
第 5 步:启动索引器 + 终端问答
python geode_graph.py --fast
看到 Graph built and saved successfully.(首次)或 Graph loaded successfully.(复用已有索引)后,即可在 > 提示符后直接提问:
> Who works on Project Alpha, and what are their roles?
💡 只想要终端界面到这里就完成了!exit 退出,Ctrl+C 停止。保持进程运行还能让它监视文档文件夹的变更。
第 6 步(可选):启动 Web 3D 界面
再开两个终端(每个都要先执行第 4 步的环境变量):
# 终端 3:API 桥接服务
$env:BRIDGE_HOST = "127.0.0.1" # Linux/macOS 用 export BRIDGE_HOST=127.0.0.1
export BRIDGE_HOST="127.0.0.1"
export BRIDGE_PORT="8765"
python -m bridge
# 终端 4:前端
npm --prefix frontend run dev
浏览器打开 http://localhost:5173,对着演示文档试试这个问题:
Who works on Project Alpha, and what are their roles?
点击图谱中任意节点,会弹出上下文卡片:frontmatter 属性、带行号的链接、反向链接、LLM 提取的关系和来源分块。
Kwipu 3D 知识图谱:重建会议时间线,回答附带来源引用
进阶:用自己的笔记文件夹
笔记不必放在仓库里,用绝对路径即可(终端、bridge、MCP 三处保持相同配置):
export KWIPU_ROOT_DIR="/path/to/Kwipu"
export KWIPU_KNOWLEDGE_DIR="/path/to/MyVault"
export KWIPU_STORAGE_DIR="graph-index"
export KWIPU_LLM_MODEL="qwen2.5:7b"
python geode_graph.py --fast
源目录与索引存储目录必须分开,Kwipu 会拒绝嵌套布局以保护源文档。文档变更后,索引器会按变更类型执行增量插入或批量重建,详见 bridge/README.md 中的存储模型说明。
遇到问题?常见故障排查表
| 症状 | 解决方法 |
|---|---|
python/ollama/npm 命令不存在 |
安装缺失的前置软件,重开终端再检查版本 |
Ollama is not running |
启动 Ollama 应用或执行 ollama serve |
Missing model(s) |
按提示执行 ollama pull <模型名>,确保索引器与 bridge 使用同名模型 |
No files found. Waiting for documents... |
确认文档放在 KWIPU_KNOWLEDGE_DIR 指向的目录下 |
查询返回 503 |
先启动 CLI 索引器并等待图构建完成,bridge 是只读消费者 |
| 端口 8765 / 5173 被占用 | 停掉旧进程,或一致地修改 bridge/Vite 端口配置 |
| 浏览器打不开页面 | 保持 Vite 进程运行,手动访问 http://localhost:5173 |
项目结构速览
| 模块 | 说明 |
|---|---|
| geode_graph.py | 核心引擎:建图、问答、目录监视 |
| bridge/ | FastAPI 桥接服务(健康检查、图快照、只读查询) |
| frontend/ | TypeScript/Vite 3D 前端 |
| kwipu_mcp_server.py | MCP 服务器,供 AI 客户端调用 query_graph |
| kwipu_config.py | 环境变量配置的唯一入口 |
| tests/ | 标准库 unittest 测试套件 |
完整 API 契约和部署说明见 bridge/README.md,中文文档参考 README.zh-CN.md。
总结
按照上面的步骤,10 分钟内你就能拥有一个完全本地运行的私有知识库:Git 克隆、装依赖、拉模型、启动索引器、开始提问。它不上传你的任何笔记,答案都有原文引用可溯源,还能用 3D 图谱直观地"看见"你的知识网络——这正是 Kwipu 作为第二大脑的价值所在 🚀
