使用说明

🧠 黑曜石RAG系统-用户手册

RAG系统将您的黑曜石金库转变为智能学习助手

📋 目录

这是什么？
特性
需求
安装
配置
MCP集成
用法
用例
故障排除
建筑

🎯 这是什么？

A. 检索增强生成（RAG） 该系统允许您使用人工智能查询您的个人黑曜石知识库。

它解决了什么问题？

如果你用黑曜石做笔记，你可能会面临：

❌ 手动搜索数百条笔记很慢
❌ 你忘记了不同主题概念之间的联系
❌ 你没有利用你记录的所有知识

使用此RAG系统：

✅ 跨所有笔记的即时语义搜索
✅ 即使使用不同的单词，也能找到相关信息
✅ 自动发现主题之间的联系
✅ 一切都在您的PC上本地运行（隐私保证）

✨ 特性

🔍 智能语义搜索：按含义查找笔记，而不仅仅是精确的单词匹配
📊 主题/主题过滤：按类别组织搜索（黑曜石标签）
💾 本地矢量数据库：你的数据永远不会离开你的电脑
🚀 快速高效：优化嵌入模型（384维）
📈 详细统计：查看每个主题索引了多少笔记
🔄 增量更新：仅在添加新笔记时重新索引
💬 交互模式：用于多个查询的对话界面
🔌 MCP集成：直接从Claude Desktop和Claude Code使用您的保险库

💻 需求

最低系统要求

操作系统：Linux、macOS或带有WSL2的Windows
python：3.10或更高
随机存取存储器：最低4GB（建议8GB）
磁盘空间：~2GB用于模型和数据库

所需软件

Python 3.10+
pip（Python包管理器）
git（克隆存储库）
带有Markdown格式注释的黑曜石拱顶

🚀 安装

步骤1：克隆存储库

git clone https://github.com/GabrielFersPin/obsidian-rag-system.git
cd obsidian-rag-system

步骤2：创建虚拟环境

# Create virtual environment
python3 -m venv venv

# Activate virtual environment
# On Linux/macOS:
source venv/bin/activate

# On Windows (WSL2):
source venv/bin/activate

步骤3：安装依赖项

pip install -r requirements.txt

备注：第一次安装将下载约1GB的依赖项，包括PyTorch和句子转换器。

⚙️ 配置

步骤1：配置环境变量

创建一个 .env 项目根目录中的文件：

cp .env.example .env

编辑 .env 使用您的配置文件：

# Path to your Obsidian vault
OBSIDIAN_VAULT_PATH=/home/your-user/Documents/MyVault

# Embedding model (you can change it if desired)
EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2

# Directory for the vector database
CHROMA_PERSIST_DIR=./chroma_db

步骤2：创建指向vault的符号链接（可选）

如果不希望指定完整路径，可以创建符号链接：

# Create the data directory if it doesn't exist
mkdir -p data

# Create the symbolic link to your vault
ln -s /path/to/your/obsidian/vault ./data/vault

然后在 .env:

OBSIDIAN_VAULT_PATH=./data/vault

第三步：推荐笔记结构

如果您的笔记具有以下特征，则系统效果最佳：

YAML元数据（可选但推荐）：

---
deck: DataScience
tags: [machine-learning, python]
created: 2024-01-15
---

这 deck 字段用于按主题/主题过滤搜索。

🔌 MCP集成（模型上下文协议）

该系统包括一个MCP服务器，允许Claude Desktop和Claude Code直接从其界面搜索您的保险库。

什么是MCP？

MCP（模型上下文协议）允许像克劳德这样的人工智能助手访问外部工具和数据源。通过这种整合，克劳德可以：

🔍 实时搜索您的黑曜石金库
📊 获取保险库统计信息
📚 按主题列出笔记
💬 使用您的个人知识库回答问题

可用的MCP工具

搜索结果：在您的保险库中搜索信息
- 参数： query （必填）， deck （可选过滤器）， n_results (1-10)
get_ult_stats：获取vault统计信息
- 显示总笔记、按主题分布、上次索引时间
list_notes_by_deck：列出特定主题的所有笔记
- 参数： deck （算法、云、数据科学、架构）

Claude桌面设置

Claude Desktop允许您连接本地MCP服务器。方法如下：

步骤1：找到Claude Desktop配置文件

配置文件的位置取决于您的操作系统：

macOS：

~/Library/Application Support/Claude/claude_desktop_config.json

窗户：

%APPDATA%\Claude\claude_desktop_config.json

Linux：

~/.config/Claude/claude_desktop_config.json

步骤2：编辑配置文件

打开配置文件并添加MCP服务器配置：

{
  "mcpServers": {
    "obsidian-rag": {
      "command": "/FULL/PATH/TO/obsidian-rag-system/venv/bin/python",
      "args": [
        "/FULL/PATH/TO/obsidian-rag-system/mcp_server.py"
      ],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/FULL/PATH/TO/YOUR/VAULT"
      }
    }
  }
}

重要：用实际路径替换路径：

/FULL/PATH/TO/obsidian-rag-system/ → 您的项目目录
/FULL/PATH/TO/YOUR/VAULT → 您的黑曜石保险库目录

示例（macOS/Linux）：

{
  "mcpServers": {
    "obsidian-rag": {
      "command": "/FULL/PATH/TO/obsidian-rag-system/venv/bin/python",
      "args": [
        "/FULL/PATH/TO/obsidian-rag-system/mcp_server.py"
      ],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/FULL/PATH/TO/VAULT"
      }
    }
  }
}

示例（Windows）：

{
  "mcpServers": {
    "obsidian-rag": {
      "command": "C:\\Users\\YourName\\obsidian-rag-system\\venv\\Scripts\\python.exe",
      "args": [
        "C:\\Users\\YourName\\obsidian-rag-system\\mcp_server.py"
      ],
      "env": {
        "OBSIDIAN_VAULT_PATH": "C:\\Users\\YourName\\Documents\\MyVault"
      }
    }
  }
}

步骤3：重新启动克劳德桌面

完全关闭并重新打开Claude Desktop。

步骤4：验证连接

在Claude Desktop中，您应该看到🔌 图标或工具指示器。你现在可以问：

"Search my vault for information about QuickSort"
"What are my notes on Docker?"
"Show me statistics of my vault"

Claude代码（CLI）的设置

Claude Code也可以使用MCP服务器。设置不同：

步骤1：创建MCP配置文件

为Claude Code创建或编辑MCP配置文件：

地点： ~/.config/claude-code/mcp.json （Linux/macOS）或 %APPDATA%\claude-code\mcp.json （Windows）

# Create directory if it doesn't exist
mkdir -p ~/.config/claude-code

# Create or edit the config file
nano ~/.config/claude-code/mcp.json

步骤2：添加服务器配置

{
  "mcpServers": {
    "obsidian-rag": {
      "command": "/FULL/PATH/TO/obsidian-rag-system/venv/bin/python",
      "args": [
        "/FULL/PATH/TO/obsidian-rag-system/mcp_server.py"
      ],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/FULL/PATH/TO/YOUR/VAULT",
        "CHROMA_PERSIST_DIR": "/FULL/PATH/TO/obsidian-rag-system/chroma_db"
      }
    }
  }
}

示例（Linux/macOS）：

{
  "mcpServers": {
    "obsidian-rag": {
      "command": "/home/username/obsidian-rag-system/venv/bin/python",
      "args": [
        "/home/username/obsidian-rag-system/mcp_server.py"
      ],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/home/username/Documents/MyVault",
        "CHROMA_PERSIST_DIR": "/home/username/obsidian-rag-system/chroma_db"
      }
    }
  }
}

示例（Windows）：

{
  "mcpServers": {
    "obsidian-rag": {
      "command": "C:\\Users\\YourName\\obsidian-rag-system\\venv\\Scripts\\python.exe",
      "args": [
        "C:\\Users\\YourName\\obsidian-rag-system\\mcp_server.py"
      ],
      "env": {
        "OBSIDIAN_VAULT_PATH": "C:\\Users\\YourName\\Documents\\MyVault",
        "CHROMA_PERSIST_DIR": "C:\\Users\\YourName\\obsidian-rag-system\\chroma_db"
      }
    }
  }
}

步骤3：测试服务器

您可以测试MCP服务器是否正常工作：

# Activate virtual environment
source /path/to/obsidian-rag-system/venv/bin/activate

# Run the MCP server directly (for testing)
python /path/to/obsidian-rag-system/mcp_server.py

如果所有配置都正确，服务器应无错误启动（它将等待通过stdio的输入）。

步骤4：在Claude代码中使用

启动Claude Code时，它将自动加载MCP服务器。你可以通过让克劳德搜索你的保险库来使用它：

"Use the obsidian-rag server to search my notes about algorithms"
"Get statistics from my vault using the MCP tool"

MCP设置故障排除

服务器未出现在Claude Desktop中

问题：The🔌 图标未出现或工具不可用。

解决方案:

验证JSON语法是否正确（没有尾随逗号，引号正确）
检查所有路径是否都是绝对的（而不是相对的，如 ./ 或 ~/)
验证Python可执行文件是否存在： ls /path/to/venv/bin/python
检查vault路径是否存在： ls /path/to/vault
完全重新启动Claude Desktop（退出并重新打开）

错误：“ModuleNotFoundError”

问题：Python找不到所需的模块。

解决方案：确保您在虚拟环境中使用Python：

/FULL/PATH/TO/obsidian-rag-system/venv/bin/python

不是Python系统(/usr/bin/python3).

错误：“Vault未编入索引”

问题：保险库还没有索引。

解决方案：首先运行索引：

cd /path/to/obsidian-rag-system
source venv/bin/activate
python run_rag.py
# Select option 2 to index

MCP服务器启动但搜索失败

问题：ChromaDB找不到数据库。

解决方案：添加 CHROMA_PERSIST_DIR MCP配置的环境变量：

"env": {
  "OBSIDIAN_VAULT_PATH": "/path/to/vault",
  "CHROMA_PERSIST_DIR": "/path/to/obsidian-rag-system/chroma_db"
}

手动测试MCP服务器

您可以使用一个简单的脚本手动测试服务器：

cd /path/to/obsidian-rag-system
source venv/bin/activate

# Run server in test mode
python -c "
import asyncio
from mcp_server import get_rag_system

async def test():
    rag = get_rag_system()
    info = rag.get_system_info()
    print(f'Notes indexed: {info[\"indexed_notes\"]}')

asyncio.run(test())
"

Claude使用示例

配置后，您可以自然地与vault交互：

示例1：搜索特定主题

You: "Search my vault for notes about Docker containers"

Claude: *Uses search_vault tool*
Found 3 relevant notes:
1. Docker Introduction.md - Explains containerization...
2. Containers vs VMs.md - Compares containers with VMs...

示例2：获取vault概览

You: "Show me statistics of my note collection"

Claude: *Uses get_vault_stats tool*
Your vault has 98 indexed notes:
- general: 84 notes
- DataScience: 3 notes
- Algorithms: 2 notes
...

示例3：按主题筛选

You: "What notes do I have about algorithms?"

Claude: *Uses search_vault with deck filter*
Found notes in Algorithms:
- QuickSort.md
- Binary Search.md
- Sorting Algorithms.md

📖 用法

启动系统

# Make sure the virtual environment is activated
source venv/bin/activate

# Run the main program
python3 run_rag.py

主菜单

开始时，您将看到一个包含以下选项的菜单：

============================================================
MAIN MENU
============================================================
1. 📊 View system statistics
2. 🔄 Index vault (first time or update)
3. 🔍 Interactive search
4. 💬 Single query
5. 🧪 Query examples
6. 🚪 Exit
============================================================

第一次：索引你的保险库

重要：在搜索之前，您必须为笔记建立索引。

选择选项 2 （索引库）
确认要继续（键入 s 然后按Enter键）
等待系统处理您的所有笔记
根据您的保险库大小，索引可能需要1-10分钟

索引过程：

⏳ Starting indexing...

📚 Step 1/5: Loading notes from vault...
   ✅ 103 notes loaded

🔍 Step 2/5: Filtering valid notes...
   ✅ 98 valid notes

📝 Step 3/5: Creating collection 'obsidian_notes'...
   ✅ Collection created

🧮 Step 4/5: Generating embeddings...
   ⏳ Processing batch 1/2...
   ⏳ Processing batch 2/2...
   ✅ Embeddings generated

💾 Step 5/5: Storing in ChromaDB...
   ✅ Documents stored

✅ Indexing completed!
   📚 Notes processed: 98
   ⏱️  Total time: 45.32s

查看统计数据（选项1）

显示有关数据库的信息：

📊 SYSTEM STATISTICS
============================================================
📁 Vault: /home/user/vault
📚 Indexed notes: 98
🕐 Last indexing: 2025-11-18T13:52:45
🧮 Model: sentence-transformers/all-MiniLM-L6-v2
📏 Dimension: 384

🎴 Distribution by subject:
   general                         84 notes
   DataScience                      3 notes
   Algorithms                       2 notes
   Cloud                            5 notes
   Architecture                     2 notes
============================================================

交互式搜索（选项3）

多个查询的对话模式：

🔍 INTERACTIVE SEARCH MODE
============================================================
Type 'exit' to return to the main menu

💭 Your question: What is QuickSort?
🎴 Filter by subject (Enter for all): Algorithms

🔍 Searching in 2 notes from Algorithms...

📝 RETRIEVED CONTEXT:
============================================================
QuickSort is an efficient sorting algorithm that uses
the divide and conquer paradigm...

📚 SOURCES:
   1. [Algorithms] QuickSort.md (Relevance: 95%)
   2. [Algorithms] Sorting Algorithms.md (Relevance: 78%)
============================================================

💭 Your question: exit

单个查询（选项4）

对于快速的单个查询：

💬 SINGLE QUERY
============================================================
💭 Your question: Explain Docker
🎴 Filter by subject (Enter for all): [Enter]

🔍 Searching...

📝 RETRIEVED CONTEXT:
============================================================
Docker is a container platform that allows packaging
applications with all their dependencies...

📚 SOURCES:
   1. [Cloud] Docker Introduction.md (Relevance: 92%)
   2. [Cloud] Containers vs VMs.md (Relevance: 85%)
============================================================

预定义示例（选项5）

尝试示例查询以熟悉系统。

🎓 用例

1.为考试而学习

💭 Your question: Summarize key concepts of neural networks
🎴 Filter by subject: DataScience

该系统将找到你所有与神经网络相关的笔记，并向你展示一个综合摘要。

2.将主题之间的概念联系起来

💭 Your question: How does CPU pipeline relate to Docker?
🎴 Filter by subject: [Enter - search all]

发现不同研究领域之间你没有注意到的联系。

3.记得你几个月前写的东西

💭 Your question: That note where I talked about algorithmic complexity and examples with trees
🎴 Filter by subject: [Enter]

语义搜索可以帮助你找到笔记，即使你不记得确切的单词。

4.准备演示文稿

💭 Your question: Give me all the important concepts about microservices
🎴 Filter by subject: Cloud

从多个笔记中收集信息，以创建完整的演示文稿。

🔧 故障排除

错误：“ModuleNotFoundError:没有名为'dotenv'的模块”

问题：虚拟环境未激活。

解决方案:

source venv/bin/activate
pip install -r requirements.txt

错误：“在[path]处找不到保险库”

问题：中的vault路径 .env 不正确。

解决方案:

确认 .env 文件存在
核实一下 OBSIDIAN_VAULT_PATH 指向正确的文件夹
验证文件夹是否存在： ls /path/to/your/vault

系统找不到包含某些单词的笔记

问题：搜索是语义搜索，而不是字面搜索。

解释：系统按含义搜索，而不是精确的单词匹配。如果你搜索“ML”，除非有足够的上下文，否则可能找不到写着“机器学习”的注释。

解决方案：使用更具描述性的短语而不是缩写。

索引需要太长时间

问题：你有很多笔记或CPU速度慢。

解决方案:

首次索引时正常（1-10分钟）
该模型默认使用CPU以实现兼容性
后续索引将更快

“没有索引的笔记”

问题：您尚未运行索引。

解决方案:

转到主菜单
选择选项 2 （索引库）
与……确认 s

特殊字符错误

问题：有些注释包含非UTF-8字符。

解决方案：确保你的Markdown笔记是UTF-8格式的。在黑曜石中，这是标准。

🏗️ 建筑

它在内部是如何工作的？

┌─────────────────────────────────────────────┐
│           OBSIDIAN RAG SYSTEM               │
├─────────────────────────────────────────────┤
│                                             │
│  📝 YOUR OBSIDIAN VAULT                     │
│      └─ Markdown notes                      │
│      └─ YAML metadata (deck, tags)          │
│           ↓                                 │
│  🔍 OBSIDIAN LOADER                         │
│      └─ Reads .md files                     │
│      └─ Extracts metadata                   │
│      └─ Ignores templates/.trash            │
│           ↓                                 │
│  🧮 SENTENCE TRANSFORMERS                   │
│      └─ Converts text to vectors            │
│      └─ Model: all-MiniLM-L6-v2             │
│      └─ Dimension: 384                      │
│           ↓                                 │
│  💾 CHROMADB (Vector Database)              │
│      └─ Stores vectors + metadata           │
│      └─ Similarity search (cosine)          │
│      └─ Local disk persistence              │
│           ↓                                 │
│  🔎 SEARCH SYSTEM                           │
│      └─ Top-K most relevant documents       │
│      └─ Filters by deck/subject             │
│      └─ Ranking by relevance                │
│           ↓                                 │
│  💬 USER INTERFACE                          │
│      └─ Interactive menu                    │
│      └─ Natural language queries            │
│                                             │
└─────────────────────────────────────────────┘

主要组件

组件	功能	技术
加载器	读取和解析Markdown注释	Python+YAML
嵌入	将文本转换为向量	句子转换器
矢量数据库	存储和搜索向量	ChromaDB
RAG链条	编排整个管道	Python
接口	用户菜单	交互式CLI

查询流程

用户提问：“什么是快速排序？”
问题→ 矢量：问题转换为384维向量
语义搜索：ChromaDB搜索最相似的向量
排名：按相关性（余弦相似性）对结果进行排序
响应：显示最相关的注释和上下文

📁 项目结构

obsidian-rag-system/
├── src/                      # Source code
│   ├── obsidian_loader.py    # Reads Obsidian notes
│   ├── embeddings.py         # Generates vectors
│   ├── vectorstore.py        # Manages ChromaDB
│   └── rag_chain.py          # Complete pipeline
│
├── run_rag.py                # Main script (run this)
├── requirements.txt          # Python dependencies
├── .env                      # Configuration (create this)
├── .env.example              # Configuration template
│
├── venv/                     # Virtual environment (create with python -m venv venv)
├── chroma_db/                # Vector database (created automatically)
└── data/                     # Link to your vault (optional)
    └── vault/                # Symlink to Obsidian

🔄 系统更新

添加新笔记时

# 1. Run the program
python3 run_rag.py

# 2. Select option 2 (Index vault)

# 3. Confirm reindexing

备注：系统将替换完整索引。这确保了没有重复。

更新依赖关系

source venv/bin/activate
pip install --upgrade -r requirements.txt

🛡️ 隐私与安全

✅ 一切都是本地的：你的笔记永远不会离开你的电脑
✅ 无遥测：ChromaDB可能会报告匿名统计数据，但您的数据不会共享
✅ 没有API密钥：不需要外部服务API密钥
✅ 开源：您可以审核所有代码

💡 提示和最佳实践

1.用元数据组织笔记

将YAML frontmatter添加到您的笔记中：

---
deck: DataScience
tags: [python, jupyter, pandas]
created: 2025-01-15
---

# Introduction to Pandas

Pandas is a library...

2.使用 `deck` 要分类的字段

这 deck 字段用于筛选搜索：

deck: DataScience
deck: Algorithms
deck: Cloud

3.写出完整的问题

❌ 坏：“快速排序” ✅ 好：“快速排序算法是如何工作的？”

语义搜索在上下文中效果更好。

4.定期重新索引

建议：如果你添加了很多笔记，每周重新索引一次。

5.清理空笔记或模板

系统会自动忽略：

名为的文件夹 template 或 .trash
非常简短的笔记（<50个字符）
.obsidian 和 .git 文件

📊 技术栈

技术	版本	目的
Python	3.10+	主要语言
句子转换器	2.2.0+	嵌入生成
ChromaDB	0.4.22+	矢量数据库
PyTorch	2.0.0+	ML后端
python dotenv	1.0.0+	环境变量

🤝 贡献

该项目对捐款开放：

分叉存储库
为您的功能创建分支(git checkout -b feature/new-functionality)
提交您的更改(git commit -m 'Add new functionality')
推到分支(git push origin feature/new-functionality)
打开拉取请求

📄 许可证

MIT许可证-您可以自由使用、修改和分发此软件。

看许可证了解更多详情。

📧 支持

如果您有问题：

查看故障排除章节
在中搜索问题
使用以下命令打开新问题：
- 问题描述
- 重现步骤
- 错误日志（如有）
- 您的操作系统和Python版本

🙏 致谢

句子转换 -嵌入模型
色度数据库 -矢量数据库
黑曜石 -记笔记系统
Niklas Luhmann的纸币盒方法

最后更新：2025年11月

💡 小贴士：如果你觉得这个项目有用，就给它一个⭐ 在GitHub上，并与使用Obsidian的其他学生分享。

使用说明

🧠 黑曜石RAG系统-用户手册

📋 目录

🎯 这是什么？

它解决了什么问题？

✨ 特性

💻 需求

最低系统要求

所需软件

🚀 安装

步骤1：克隆存储库

步骤2：创建虚拟环境

步骤3：安装依赖项

⚙️ 配置

步骤1：配置环境变量

步骤2：创建指向vault的符号链接（可选）

第三步：推荐笔记结构

🔌 MCP集成（模型上下文协议）

什么是MCP？

可用的MCP工具

Claude桌面设置

步骤1：找到Claude Desktop配置文件

步骤2：编辑配置文件

步骤3：重新启动克劳德桌面

步骤4：验证连接

Claude代码（CLI）的设置

步骤1：创建MCP配置文件

步骤2：添加服务器配置

步骤3：测试服务器

步骤4：在Claude代码中使用

MCP设置故障排除

服务器未出现在Claude Desktop中

错误：“ModuleNotFoundError”

错误：“Vault未编入索引”

MCP服务器启动但搜索失败

手动测试MCP服务器

Claude使用示例

📖 用法

启动系统

主菜单

第一次：索引你的保险库

查看统计数据（选项1）

交互式搜索（选项3）

单个查询（选项4）

预定义示例（选项5）

🎓 用例

1.为考试而学习

2.将主题之间的概念联系起来

3.记得你几个月前写的东西

4.准备演示文稿

🔧 故障排除

错误：“ModuleNotFoundError:没有名为'dotenv'的模块”

错误：“在[path]处找不到保险库”

系统找不到包含某些单词的笔记

索引需要太长时间

“没有索引的笔记”

特殊字符错误

🏗️ 建筑

它在内部是如何工作的？

主要组件

查询流程

📁 项目结构

🔄 系统更新

添加新笔记时

更新依赖关系

🛡️ 隐私与安全

💡 提示和最佳实践

1.用元数据组织笔记

2.使用 deck 要分类的字段

3.写出完整的问题

4.定期重新索引

5.清理空笔记或模板

📊 技术栈

🤝 贡献

📄 许可证

📧 支持

🙏 致谢

相关 MCP

AI持久记忆服务器

Zotero文献库搜索与阅读MCP服务

2.使用 `deck` 要分类的字段