benmaster82-Kwipu

repository

loading code, commits, and activity

repositories

loading repo index

#1	# Kwipu（geode_graph 项目）
#2
#3	> 🌐 语言版本 · [English](README.md) · 简体中文
#4
#5	一个完全本地运行的 Graph RAG 系统，可以把你的 Markdown 笔记构建成一张可被自然语言查询的知识图谱。用人话提问，就能获得跨多个文件关联出来的答案。
#6
#7	为 [Obsidian](https://obsidian.md/) vault 而生，但同样适用于任何 Markdown 文件夹。
#8
#9	[![Geode Graph 运行截图](https://github.com/benmaster82/Kwipu/raw/main/img/screen.png)](/benmaster82/Kwipu/blob/main/img/screen.png)
#10
#11	[![查询响应示例](https://github.com/benmaster82/Kwipu/raw/main/img/screen_2.png)](/benmaster82/Kwipu/blob/main/img/screen_2.png)
#12
#13	## 核心特性
#14
#15	* MCP 服务器 — 可作为 Claude Desktop、Cursor、Windsurf 等 AI 代理的工具使用，所有处理通过 Ollama 在本地完成
#16	* Property Graph 索引 — 使用 LLM 抽取关系，从你的笔记构建知识图谱
#17	* Obsidian 原生支持 — 自动解析 `[[wikilinks]]` 和 YAML frontmatter，转化为结构化的图三元组
#18	* 多语言 — 支持意大利语、英语、法语、德语、西班牙语、葡萄牙语（自动识别）
#19	* 混合检索 — 同时融合 4 种检索策略：
#20	+ LLM 同义词扩展（可选，`--fast` 模式下跳过）
#21	+ 向量相似度检索
#22	+ BM25 关键词打分
#23	+ 时间/元数据匹配
#24	* 实时同步 — 监听笔记文件夹变化，自动增量更新图索引
#25	* 增量更新 — 修改笔记后无需重建整个图，单文件秒级更新
#26	* 反幻觉提示词 — 严格要求引用来源，避免编造事实
#27	* 完全本地 — 基于 Ollama 运行，数据绝不离开本机
#28
#29	## 环境要求
#30
#31	* Python 3.11+
#32	* 本地运行的 [Ollama](https://ollama.ai/)
#33	* 一个 LLM 模型（例如 `llama3.1:8b`、`qwen2.5:7b`、`mistral:7b`）
#34	* 一个嵌入模型（默认：`nomic-embed-text`）
#35
#36	## 安装
#37
#38	```bash
#39	# 安装依赖
#40	pip install -r requirements.txt
#41
#42	# 在 Ollama 中拉取模型
#43	ollama pull llama3.1:8b
#44	ollama pull nomic-embed-text
#45	```
#46
#47	在 `geode_graph.py` 中设置你要使用的模型：
#48
#49	```python
#50	MODEL_NAME = "llama3.1:8b" # 或 Ollama 中任意可用的模型
#51	```
#52
#53	## MCP 服务器（Claude Desktop、Cursor、Windsurf）
#54
#55	Kwipu 可以作为 MCP 服务器运行，让 AI 代理直接查询你的知识图谱。所有处理通过 Ollama 在本地完成，最大限度减少客户端 token 消耗。
#56
#57	在 `claude_desktop_config.json`（或对应的 MCP 配置文件）中添加：
#58
#59	```json
#60	{
#61	"mcpServers": {
#62	"kwipu": {
#63	"command": "C:/path/to/python.exe",
#64	"args": ["C:/path/to/kwipu_mcp_server.py"]
#65	}
#66	}
#67	}
#68	```
#69
#70	将路径替换为你实际的 Python 和项目路径。需要 Ollama 正在运行并加载了配置的模型。
#71
#72	## 使用
#73
#74	```bash
#75	# 完整模式（启用全部检索器，质量最佳）
#76	python geode_graph.py
#77
#78	# 快速模式（跳过 LLM 同义词检索器，CPU 下单次查询快约 50%）
#79	python geode_graph.py --fast
#80	```
#81
#82	把你的 Markdown 文件放到 `./knowledge_base/` 目录下（或者修改配置中的 `KNOWLEDGE_DIR`）。系统首次运行时会构建图，之后持续监听文件变化。
#83
#84	## 工作原理
#85
#86	```
#87	你的笔记 (.md)
#88	│
#89	▼
#90	┌─────────────────────┐
#91	│ 预处理 │ ← 提取 [[wikilinks]] 和 YAML frontmatter
#92	│ (lang_config.py) │ ← 根据上下文推断关系
#93	└─────────┬───────────┘
#94	│
#95	▼
#96	┌─────────────────────┐
#97	│ LLM 抽取 │ ← 抽取额外的实体-关系三元组
#98	│ (SimpleLLMPath) │
#99	└─────────┬───────────┘
#100	│
#101	▼
#102	┌─────────────────────┐
#103	│ Property Graph │ ← 合并结构化 + LLM 三元组
#104	│ 索引 │ ← 持久化到磁盘 (storage_graph/)
#105	└─────────┬───────────┘
#106	│
#107	▼
#108	┌─────────────────────┐
#109	│ 混合检索 │ ← 同义词 + 向量 + BM25 + 时间维度
#110	└─────────┬───────────┘
#111	│
#112	▼
#113	┌─────────────────────┐
#114	│ LLM 生成回答 │ ← 根据召回上下文生成答案
#115	└─────────────────────┘
#116	```
#117
#118	## 项目结构
#119
#120	```
#121	├── geode_graph.py # 主程序入口
#122	├── kwipu_mcp_server.py # MCP 服务器，用于 AI 代理集成
#123	├── lang_config.py # 多语言配置（停用词、模式、关系）
#124	├── requirements.txt # Python 依赖
#125	├── knowledge_base/ # 把你的笔记放在这里
#126	│ └── examples/ # 示例笔记，方便上手
#127	└── storage_graph/ # 自动生成的图索引（已在 .gitignore 中）
#128	```
#129
#130	## 指向 Obsidian Vault
#131
#132	把 `KNOWLEDGE_DIR` 改为你的 vault 路径：
#133
#134	```python
#135	KNOWLEDGE_DIR = "C:/Users/YourName/Documents/MyVault"
#136	```
#137
#138	系统只读取文件，不会修改任何内容。`.obsidian/` 配置目录会被自动忽略。
#139
#140	## 模型推荐
#141
#142	\| 模型规模 \| 内存（Q4） \| 质量 \| CPU 速度 \| GPU 速度 \|
#143	\| --- \| --- \| --- \| --- \| --- \|
#144	\| 1B \| ~2 GB \| 基础可用 \| ~8s \| ~2s \|
#145	\| 3B \| ~3 GB \| 良好 \| ~60s \| ~8s \|
#146	\| 7-8B \| ~5-6 GB \| 优秀 \| ~300s \| ~15-25s \|
#147	\| 20B \| ~12 GB \| 最佳 \| 不推荐 \| ~15s \|
#148
#149	正式使用推荐 7B+ 配合 GPU，体验最为均衡。
#150
#151	## 构建时间预估
#152
#153	首次构建图时，每个文档分块都需要一次 LLM 调用。之后从磁盘加载图，速度是秒级的。
#154
#155	\| 笔记数量 \| GPU (7B) \| CPU (7B) \| CPU (3B) \|
#156	\| --- \| --- \| --- \| --- \|
#157	\| 5 \| ~2 分钟 \| ~5 分钟 \| ~3 分钟 \|
#158	\| 20 \| ~7 分钟 \| ~20 分钟 \| ~10 分钟 \|
#159	\| 50 \| ~17 分钟 \| ~50 分钟 \| ~25 分钟 \|
#160	\| 100 \| ~35 分钟 \| ~100 分钟 \| ~50 分钟 \|
#161	\| 500+ \| ~3 小时 \| 不推荐 \| ~4 小时 \|
#162
#163	新增一个文件采用增量更新（约 20-60 秒），不会重建整个图。
#164
#165	## 资源占用
#166
#167	\| 组件 \| 内存 \| 备注 \|
#168	\| --- \| --- \| --- \|
#169	\| Ollama（LLM） \| 2-14 GB \| 取决于模型规模和量化等级 \|
#170	\| Ollama（嵌入） \| ~300 MB \| nomic-embed-text \|
#171	\| Geode Graph（建图） \| 0.5-4 GB \| 取决于笔记数量 \|
#172	\| Geode Graph（查询） \| 200-500 MB \| 图构建完成后 \|
#173	\| 合计（7B Q4） \| ~8-12 GB \| 建议最低系统内存：16 GB \|
#174
#175	## 实用技巧：用云端模型建图，本地模型日常查询
#176
#177	如果你的硬件比较有限，可以通过 Ollama 接入一次性的强力云端模型来构建图，然后切换为轻量级本地模型做日常查询。图持久化在磁盘上，因此只有构建阶段才需要大模型。
#178
#179	```bash
#180	# 步骤 1：用云端模型构建图（一次性，高质量抽取）
#181	# 在 geode_graph.py 中设置 MODEL_NAME = "gpt-oss:20b-cloud"，然后运行：
#182	python geode_graph.py
#183	# 等待出现 "Graph built and saved successfully"，然后退出。
#184
#185	# 步骤 2：切换为小模型用于查询（快速，低资源占用）
#186	# 在 geode_graph.py 中设置 MODEL_NAME = "qwen2.5:3b"，然后运行：
#187	python geode_graph.py --fast
#188	```
#189
#190	这样可以兼顾两端的优势：由 20B+ 模型构建出高质量的图，再由 3B 模型实现快速轻量的查询。图结构（实体、关系、三元组）与模型解耦，切换模型不会影响图本身，只影响回答生成质量。
#191
#192	## 路线图
#193
#194	* Telegram Bot — 通过 Telegram 随时随地查询你的 Obsidian vault 或知识库，外出时也能基于自己的笔记问答。
#195
#196	## 媒体报道
#197
#198	* [《把 Markdown 笔记变成可问答的知识图谱：本地 Graph RAG 工具 Kwipu 实测》](https://juejin.cn/post/7637134822670876699) — 掘金 · 龙哥AI · 2026-05-08
#199
#200	## 许可协议
#201
#202	MIT
#203

z6MkqRzA/benmaster82-Kwipu