如何 10 分钟搭建私有知识库:Kwipu 本地 Graph RAG 安装与快速上手教程

原创2026-11-15 18:28:441,413 阅读

如何 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?

Kwipu 终端问答界面:左侧 Obsidian 笔记,右侧本地 Graph RAG 返回带引用的回答

💡 只想要终端界面到这里就完成了!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 作为第二大脑的价值所在 🚀

登录后查看全文
Kwipu