将你的 Obsidian 知识库转换为智能对话系统，支持语义检索和本地化部署。
中文 | English
- 🔍 语义检索：基于向量的相似度搜索，理解查询意图
- 📝 Markdown 解析：完整保留 Obsidian 元数据和链接
- 🌐 中英文支持：优化的多语言嵌入模型
- 💾 本地部署：数据安全，无需联网
- 🔄 增量更新：自动监测文件变化，无需重建索引
- 🎯 混合检索：结合向量搜索和关键词匹配
- 💬 对话接口：支持多轮对话和上下文理解
- 🚀 MCP 集成：通过 Claude Code 直接使用 RAG 功能
# 创建虚拟环境
python -m venv obsidian_rag_env
# 激活虚拟环境
source obsidian_rag_env/bin/activate # macOS/Linux
# 或
obsidian_rag_env\Scripts\activate # Windows
# 安装依赖
pip install -r requirements.txt# 复制配置文件
cp .env.example .env
# 编辑配置文件，设置你的 Obsidian 路径
nano .env在 .env 文件中设置：
OBSIDIAN_VAULT_PATH=/path/to/your/obsidian/vault每次运行时通过参数指定路径：
python src/build_index.py --vault-path /path/to/your/obsidian/vault在 config.yaml 中设置（可选，默认使用环境变量）：
# Obsidian RAG 系统配置
obsidian_vault_path: "/path/to/your/obsidian/vault"# 使用环境变量中的路径
python src/build_index.py
# 或直接指定路径
python src/build_index.py --vault-path /path/to/your/obsidian/vault# 命令行模式
python src/chat.py
# 或启动 Web 服务
python src/web_server.py
# 或通过 MCP 集成使用 Claude Code (推荐)
# 查看 MCP_README.md 了解详细配置# 交互模式（使用环境变量中的路径）
python src/query.py
# 交互模式（指定路径）
python src/query.py --vault-path /path/to/your/obsidian/vault
# 单次查询
python src/query.py "你的问题"
# 高级查询
python src/query.py "问题" --top-k 10 --threshold 0.8 --tags "AI,机器学习"from obsidian_rag import ObsidianRAG
# 初始化系统
rag = ObsidianRAG(
vault_path="/path/to/obsidian",
config_path="config.yaml"
)
# 查询
results = rag.query("关于机器学习的学习路径")
for result in results:
print(f"文件: {result['file_path']}")
print(f"内容: {result['content']}")
print(f"相似度: {result['score']:.3f}")
print("---")
# 对话
response = rag.chat("我想学习机器学习，应该从哪里开始？")
print(response)RAG 文件夹路径（Obsidian 保险库路径）支持三种配置方式，优先级从高到低：
- 命令行参数（最高优先级）：
--vault-path /path/to/vault - 环境变量（推荐）：在
.env文件中设置OBSIDIAN_VAULT_PATH - 配置文件：在
config.yaml中设置obsidian_vault_path
主要配置项位于 config.yaml 和 .env 文件中：
- 嵌入模型：默认使用
paraphrase-multilingual-MiniLM-L12-v2 - 文本分割：块大小 500，重叠 50
- 检索设置：返回前 5 个结果，相似度阈值 0.7
- 数据库：使用 ChromaDB，存储在
./data/chroma
# 必需配置
OBSIDIAN_VAULT_PATH=/path/to/your/obsidian/vault
# 可选配置
EMBEDDING_MODEL=paraphrase-multilingual-MiniLM-L12-v2
EMBEDDING_DEVICE=cpu # cpu/mps/cuda
TOP_K_RETRIEVAL=5
SIMILARITY_THRESHOLD=0.7obsidian_rag/
├── src/ # 源代码
│ ├── __init__.py
│ ├── config.py # 配置管理
│ ├── document_parser.py # 文档解析
│ ├── text_chunker.py # 文本分割
│ ├── embedding.py # 向量化
│ ├── database.py # 数据库操作
│ ├── retrieval.py # 检索系统
│ ├── build_index.py # 建立索引
│ ├── query.py # 查询接口
│ ├── chat.py # 对话系统
│ ├── web_server.py # Web 服务
│ ├── mcp_server.py # MCP 服务器
│ ├── update_index.py # 增量更新
│ └── mcp_server_minimal.py # MCP 简化服务器
├── data/ # 数据存储
│ ├── chroma/ # 向量数据库
│ └── cache/ # 缓存文件
├── tests/ # 测试文件
│ ├── test_basic.py # 基础测试
│ ├── test_mcp*.py # MCP 测试
│ └── test_vault/ # 测试数据
├── docs/ # 文档
│ ├── MCP_*.md # MCP 相关文档
│ └── PROJECT_SUMMARY.md
├── templates/ # 模板文件
├── requirements.txt # 依赖列表
├── config.yaml # 配置文件
├── .env.example # 环境变量示例
├── setup.sh # 安装脚本
├── run.sh # 运行脚本
├── start_mcp_server.py # MCP 启动脚本
├── .gitignore # Git 忽略文件
├── LICENSE # 许可证
└── README.md # 说明文档
系统会自动监测文件变化，只更新修改过的文件：
# 手动触发增量更新
python src/update_index.py支持基于标签、文件夹、日期等元数据的精确过滤：
# 按标签过滤
results = rag.query("AI", tags=["机器学习", "深度学习"])
# 按文件夹过滤
results = rag.query("笔记", folders=["Zettelkasten"])
# 按时间范围过滤
results = rag.query("最近", start_date="2024-01-01", end_date="2024-12-31")可以使用不同的嵌入模型：
from sentence_transformers import SentenceTransformer
# 使用自定义模型
rag = ObsidianRAG(
embedding_model="your-custom-model",
device="mps" # 使用 Apple Silicon GPU 加速
)- GPU 加速：设置
device=cuda或device=mps - 批量处理：调整
batch_size参数 - 缓存机制：启用嵌入向量缓存
- 并行处理：使用多进程处理文档
A:
- 调整相似度阈值
- 增加返回结果数量 (
top_k) - 优化文本分割策略
- 尝试不同的嵌入模型
A:
- 使用 GPU 加速
- 增加批处理大小
- 启用并行处理
A: 目前支持 Markdown (.md, .markdown)，计划支持 PDF、TXT 等格式。
MIT License
本项目支持通过 MCP (Model Context Protocol) 与 Claude Code 集成，提供无缝的 RAG 体验。
-
安装 MCP 依赖:
pip install mcp>=1.0.0 -
配置已自动添加到
~/.claude/plugins/config.json -
在 Claude Code 中使用:
- 直接对话询问关于您知识库的内容
- 使用向量检索功能
- 获取文档信息和列表
详细使用说明请查看 docs/MCP_README.md
欢迎提交 Issue 和 Pull Request！