开源本地 RAG 方案 ReferenceRAG： 把 Obsidian 里的笔记、磁盘中的海量内容，直接变成 AI 的外挂大脑、支持 Obsidian.

ReferenceRAG 介绍文档

Github: github.com/csvkse/Refe…

平台支持情况 Windows：已完整支持，作为当前主要维护和推荐使用的环境。

---

效果预览： github.com/csvkse/Refe…

---

项目简介

ReferenceRAG 是一个本地优先、高召回率、低延迟的知识库 RAG（检索增强生成）系统，支持多源文件夹索引，不限于 Obsidian。

基于 ASP.NET Core + ONNX Runtime + SQLite 向量存储构建，集成 MCP 工具集，可与 Claude、CherryStudio 等多种 AI 客户端协同工作，让 AI 在对话中实时查询本地知识。

---

核心痛点

AI 大模型无法直接使用本地笔记库作为外挂知识库进行检索增强。ReferenceRAG 将本地笔记库索引为向量，支持多种检索方式和模型切换，解决这一核心问题。

---

特色功能

功能	说明
限定查询	支持限定笔记源（Sources）和文件夹路径，精准控制检索范围
混合检索	向量查询 + BM25 全文检索 + Rerank 重排，多种组合方式
模型切换	一键切换 Embedding/Reranker 模型，支持本地 ONNX 加速
多源支持	同时索引 Obsidian/Markdown/代码文档等多个文件夹
自动后台同步	监控文件夹变化，自动后台执行向量索引，无需手动触发

---

系统架构

┌─────────────────────────────────────────────────┐
│                  AI 客户端层                      │
│  Obsidian/claudian · CherryStudio · Claude Code  │
└──────────────────────┬──────────────────────────┘
                       │ MCP / REST API
┌──────────────────────▼──────────────────────────┐
│              ReferenceRAG 服务                    │
│  ┌──────────┐  ┌──────────┐  ┌───────────────┐  │
│  │ 向量检索  │  │ BM25检索  │  │ Rerank 重排   │  │
│  └──────────┘  └──────────┘  └───────────────┘  │
│  ┌──────────────────────────────────────────┐    │
│  │         ONNX Runtime 推理引擎             │    │
│  └──────────────────────────────────────────┘    │
└──────────────────────┬──────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────┐
│           SQLite + sqlite-vec 向量存储            │
└─────────────────────────────────────────────────┘

技术栈：

• 后端：ASP.NET Core
• 推理：ONNX Runtime（支持 CUDA GPU 加速）
• 存储：SQLite + sqlite-vec 向量扩展
• 协议：MCP（Model Context Protocol）

---

使用方式

ReferenceRAG 支持四种方式接入 AI 客户端：

方案一：Obsidian + claudian

在 Obsidian 内直接进行 RAG 问答，无需切换工具。

1. 在 Obsidian 社区插件市场搜索安装 claudian
2. 配置服务地址：http://localhost:7897
3. 开始使用 RAG 问答

方案二：CherryStudio + MCP

CherryStudio 通过 MCP 协议连接 ReferenceRAG，实现知识库检索增强。

MCP 配置：

{
  "mcpServers": {
    "ReferenceRAG": {
      "isActive": true,
      "name": "ReferenceRAG",
      "type": "streamableHttp",
      "baseUrl": "http://127.0.0.1:7897/api/mcp"
    }
  }
}

方案三：Claude Code + Skills

1. 将项目中的 Skills 文件夹复制到 Claude Code 配置目录
2. 直接调用：/ReferenceRAG 搜索 "查询内容"

方案四：直接调用 API

# 查询知识库
curl -X POST http://localhost:7897/api/ai/query \
  -H "Content-Type: application/json" \
  -d '{"query": "如何在 C# 中使用异步编程？", "topK": 5}'

# 限定笔记源查询
curl -X POST http://localhost:7897/api/ai/query \
  -H "Content-Type: application/json" \
  -d '{"query": "关键词", "sources": ["我的笔记"]}'

---

前端仪表板

启动服务后访问 http://localhost:7897，提供以下功能模块：

首页仪表盘

展示系统核心指标：源数量、文件数量、分块数量、平均查询时间。快速操作区提供一键索引、搜索跳转、源管理入口。底部实时显示索引进度。

向量搜索

混合检索界面，支持 BM25 + 向量检索融合。展示当前嵌入模型、重排模型、索引状态等信息。搜索结果展示来源文件、相关度分数、关键词高亮，点击可展开查看完整分块内容。

模型管理

管理嵌入模型（Embedding）和重排模型（Reranker），支持模型扫描、在线下载、一键切换。每个模型卡片展示向量维度、最大序列长度、模型格式、下载状态等信息。

BM25 索引

基于关键词的传统全文检索管理，支持指定分块大小和重叠长度，提供索引状态监控与重建功能。

源管理

配置与管理知识库源：添加文件夹路径、设置源名称和递归扫描选项、查看索引统计、管理已索引文件列表。

系统监控

实时系统状态监控：运行状态指示、活动告警、全局索引统计、正在进行的索引任务及实时进度。

系统设置

系统级配置：向量索引参数（分块大小、重叠）、搜索参数（混合权重、Top-K、重排数量、BM25 参数）、日志级别、API Key 管理。

---

API 概览

接口	说明
POST /api/ai/query	知识库语义查询
POST /api/ai/drill-down	深入查询（上下文扩展）
POST /api/index/all	触发全量索引
GET /api/index/status	索引状态
GET /api/models	模型列表
POST /api/models/switch	切换模型

---

快速开始

环境要求

• .NET 10.0 Runtime（下载 Release 版本无需安装 SDK）
• SQLite（自动包含）
• CUDA 12.x（可选，GPU 加速）

下载 Release（推荐）

直接下载 Release 程序包，解压后运行即可。下载地址：GitHub Releases

常用配置参数

配置项	路径	默认值	说明
程序端口	ReferenceRAG.service.port	7897	服务监听端口
API Key	ReferenceRAG.service.apiKey	空	接口认证密钥，为空则不启用
向量数据目录	ReferenceRAG.dataPath	-	SQLite 向量库存储路径
模型存放目录	ReferenceRAG.modelsRootPath	-	Embedding/Reranker 模型文件根目录

Windows 脚本管理

cd src/ReferenceRAG.Service/scripts
menu.bat

选项	功能
1	构建 (Build)
2	安装服务 (Install)
3	启动服务 (Start)
4	停止服务 (Stop)
5	查看状态 (Status)
6	卸载服务 (Uninstall)
7	控制台运行 (Run as Console)
8	打开浏览器

Docker 部署

docker-compose up -d
docker-compose logs -f

配置持久化：容器内配置文件挂载到宿主 config/ 目录。GPU 版本使用 Dockerfile.gpu 构建。

编译运行

git clone https://github.com/csvkse/ReferenceRAG.git
cd ReferenceRAG
dotnet run --project src/ReferenceRAG.Service

---

常见问题

模型下载/转换失败：安装 Python 依赖 pip install torch transformers optimum onnx numpy，网络问题可使用国内镜像。

ONNX 转换失败提示缺少 DLL：将 CUDA bin 目录加入系统 PATH 后重启。

模型下载缓慢：使用 huggingface-cli download 下载到本地再指定路径加载。

前端跨域报错：确保 appsettings.json 中 Cors.AllowedOrigins 包含前端地址。

---

相关项目

项目	说明
claudian	Obsidian RAG 插件
sqlite-vec	SQLite 向量扩展
ONNX Runtime	跨平台 ML 推理加速器

---