203 lines
7.9 KiB
Markdown
203 lines
7.9 KiB
Markdown
---
|
||
name: mengya-rag
|
||
description: 萌芽本地 RAG 知识库，基于 LlamaIndex + DeepSeek + BM25/向量混合检索的 Obsidian 笔记问答工具。当用户提到查笔记、查知识库、根据笔记回答问题、搜索自己的文档、翻看笔记内容、查自己的博客文章、查教程、查项目文档、整理笔记素材、问"我写过什么""我之前记录过什么""我的笔记里有没有关于X的内容"时，一定要使用本技能。也适用于用户需要查询知识库状态、同步笔记、重建索引的场景。该技能通过 CLI 工具 mengya-rag 实现，项目路径 /shumengya/project/agent/mengya-rag。
|
||
---
|
||
|
||
# 萌芽 RAG 知识库
|
||
|
||
基于 LlamaIndex + DeepSeek + BM25/本地向量混合检索的个人 Obsidian 笔记问答系统。
|
||
|
||
**当前状态：** 已索引 495 篇 Markdown 笔记，共计 1802 个语义分块，覆盖 Docker、Linux、Android、AI Agent、博客文章、工具教程等主题。
|
||
|
||
## 前置检查
|
||
|
||
执行任何操作前，先确认工具可用：
|
||
|
||
```bash
|
||
cd /shumengya/project/agent/mengya-rag && uv run mengya-rag status --json
|
||
```
|
||
|
||
返回示例：
|
||
```json
|
||
{"ok": true, "markdown_note_count": 495, "index_node_count": 1802, "db_exists": true, "deepseek_model": "deepseek-v4-flash"}
|
||
```
|
||
|
||
如果 `ok: false` 或 `db_exists: false`，需要先执行 `reindex` 重建索引后再继续。
|
||
|
||
## 项目路径
|
||
|
||
```text
|
||
项目根目录: /shumengya/project/agent/mengya-rag
|
||
笔记目录: data/notes/ (495 篇 Markdown 笔记)
|
||
索引目录: data/index/bm25/ (SQLite + sqlite-vec 向量库)
|
||
配置: .env (DeepSeek API Key)
|
||
```
|
||
|
||
## 技术栈
|
||
|
||
| 组件 | 技术 |
|
||
|------|------|
|
||
| RAG 框架 | LlamaIndex |
|
||
| 本地 embedding | BAAI/bge-small-zh-v1.5 (FastEmbed + ONNX，无 PyTorch/GPU 依赖) |
|
||
| 大模型回答 | DeepSeek API (默认 deepseek-v4-flash) |
|
||
| 检索方式 | BM25 关键词 + 向量语义 混合检索 + RRF 融合 + 同文件去重 |
|
||
| 向量库 | SQLite + sqlite-vec（单文件，无外部服务依赖）|
|
||
| 运行环境 | Python 3.11+, uv 包管理 |
|
||
|
||
## CLI 命令参考
|
||
|
||
所有命令从项目根目录执行，`uv run` 前缀：
|
||
|
||
### 核心命令（推荐 Agent 统一使用 `--json`）
|
||
|
||
| 命令 | 用途 | 推荐场景 |
|
||
|------|------|---------|
|
||
| `mengya-rag status --json` | 检查索引和配置状态 | 对话开始时先跑一次确认环境 |
|
||
| `mengya-rag search "Q" -k N --json` | 纯检索，不调大模型 | 需要自己分析检索结果时 |
|
||
| `mengya-rag context "Q" -k N --json` | 返回拼接好的 context 字符串 | 需要把检索结果注入其他大模型提示词时 |
|
||
| `mengya-rag read "path" --json` | 读取完整 Markdown 原文 | 检索命中后需要补充上下文时 |
|
||
| `mengya-rag ask "Q" -k N --json` | RAG + DeepSeek 完整问答 | 用户直接想问笔记里的内容时 |
|
||
| `mengya-rag reindex --json` | 同步笔记 + 重建索引 | 笔记更新后 |
|
||
|
||
### 常用参数
|
||
|
||
```bash
|
||
-k, --top-k <num> # 返回条数（默认 6）
|
||
--mode auto # 自动判断：普通问答或盘点列表（默认）
|
||
--mode hybrid # 强制语义检索模式
|
||
--mode inventory # 强制盘点/目录检索模式
|
||
--env-file /path/.env # 指定配置文件
|
||
--notes-dir /path # 覆盖笔记目录
|
||
--index-dir /path # 覆盖索引目录
|
||
```
|
||
|
||
## Agent 工作流
|
||
|
||
当用户提到查笔记、查知识库、找文档时，按以下顺序操作：
|
||
|
||
### 第一步：检查状态
|
||
|
||
```bash
|
||
cd /shumengya/project/agent/mengya-rag && uv run mengya-rag status --json
|
||
```
|
||
|
||
确认 `ok: true`、`db_exists: true`、`markdown_note_count > 0`。
|
||
|
||
### 第二步：根据用户问题类型选择命令
|
||
|
||
**场景 A：用户问"关于X的内容是什么""XX怎么做"**
|
||
→ 使用 `ask`，让 RAG 完成检索 + 回答
|
||
|
||
```bash
|
||
uv run mengya-rag ask "用户的问题" -k 4 --json
|
||
```
|
||
解析返回的 `answer` 和 `sources`，直接呈现给用户。
|
||
|
||
**场景 B：用户想查"有哪些笔记""我写过什么"**
|
||
→ 检索模式会自动切换到盘点模式，用 `search` 即可
|
||
|
||
```bash
|
||
uv run mengya-rag search "博客文章" -k 10 --json
|
||
```
|
||
返回结果中的 `results[].title` 和 `results[].heading_path` 可以直接展示给用户。
|
||
|
||
**场景 C：检索结果不够详细，需要看完整原文**
|
||
→ 先用 `search` 拿到 `source` 文件名，再用 `read` 读完整内容
|
||
|
||
```bash
|
||
# 先检索
|
||
uv run mengya-rag search "Docker 网络配置" -k 3 --json
|
||
# 取出结果中的 source 字段（如 "Docker/Docker网络配置.md"）后执行：
|
||
uv run mengya-rag read "Docker/Docker网络配置.md" --json
|
||
```
|
||
|
||
**场景 D：需要把笔记内容作为上下文给另一个大模型**
|
||
→ 使用 `context` 模式，返回纯文本 context
|
||
|
||
```bash
|
||
uv run mengya-rag context "WireGuard 配置方法" -k 4 --json
|
||
```
|
||
返回的 `context` 字段可直接拼入其他模型的提示词中。
|
||
|
||
**场景 E：用户说笔记更新了/查不到新内容**
|
||
→ 执行同步 + 重建索引
|
||
|
||
```bash
|
||
uv run mengya-rag reindex --json
|
||
```
|
||
|
||
### 第三步：呈现结果
|
||
|
||
- **ask 结果**：直接展示 `answer` 内容，并附上 `sources` 来源说明
|
||
- **search 结果**：列表展示文件名和标题路径，询问用户是否需要进一步阅读某篇
|
||
- **read 结果**：展示 `content`，如果内容较长则先总结再给用户
|
||
- **context 结果**：说明已获取上下文，询问用户想用它做什么
|
||
|
||
## 检索模式说明
|
||
|
||
系统自动识别两类问题，无需手动指定（也可通过 `--mode` 强制）：
|
||
|
||
| 问题类型 | 示例 | 检索策略 |
|
||
|---------|------|---------|
|
||
| 普通问答 | "Docker 常用命令有哪些""WireGuard 怎么配置" | Markdown 结构感知分块 → BM25 + 向量混合检索 → RRF 融合 → DeepSeek 生成回答 |
|
||
| 盘点列表 | "我有哪些博客文章""安卓 Gradle 相关笔记" | 文件级摘要节点 → BM25 检索 → 关键词覆盖过滤 → 输出文件列表和预览 |
|
||
|
||
## 查询模式示例
|
||
|
||
**普通问答：**
|
||
```
|
||
用户 > docker-compose 怎么设置资源限制
|
||
Agent > uv run mengya-rag ask "docker-compose 资源限制配置" -k 4 --json
|
||
返回 > answer: "在 docker-compose.yml 中通过 deploy.resources.limits 设置..."
|
||
> sources: ["Docker/Docker Compose配置.md", "Docker/资源限制.md"]
|
||
Agent > 展示回答内容和来源
|
||
```
|
||
|
||
**盘点列表：**
|
||
```
|
||
用户 > 我有哪些博客文章
|
||
Agent > uv run mengya-rag search "博客文章" -k 10 --json
|
||
返回 > results[].title 列表
|
||
Agent > 展示文件列表，询问用户想读哪篇
|
||
```
|
||
|
||
## 维护操作
|
||
|
||
```bash
|
||
# 同步笔记 + 重建索引（一步完成）
|
||
uv run mengya-rag reindex --json
|
||
|
||
# 或分步执行：
|
||
uv run mengya-sync-notes # 从 bigmengya 同步最新笔记
|
||
uv run mengya-build-index # 重建索引
|
||
```
|
||
|
||
## 错误处理
|
||
|
||
| 现象 | 可能原因 | 处理方式 |
|
||
|------|---------|---------|
|
||
| `db_exists: false` | 索引未构建 | 执行 `uv run mengya-rag reindex --json` |
|
||
| `ok: false` | 项目或配置问题 | 检查 `.env` 中 `DEEPSEEK_API_KEY` 是否配置 |
|
||
| `command not found: uv` | uv 未安装 | `pip install uv` 或 `curl -LsSf https://astral.sh/uv/install.sh | sh` |
|
||
| `markdown_note_count: 0` | 笔记目录为空 | 执行 `uv run mengya-rag reindex --json` 从 bigmengya 同步 |
|
||
| DeepSeek API 报错 | API Key 无效或网络问题 | 检查 `.env` 中的 `DEEPSEEK_API_KEY` 和网络连通性 |
|
||
|
||
## 配置参考
|
||
|
||
`.env` 文件中的可调参数：
|
||
|
||
```env
|
||
DEEPSEEK_API_KEY=你的API密钥 # 必填
|
||
TOP_K=6 # 默认检索返回条数
|
||
EMBED_MODEL=BAAI/bge-small-zh-v1.5 # 本地 embedding 模型
|
||
EMBED_BATCH_SIZE=32 # embedding 批处理大小
|
||
VECTOR_WEIGHT=0.65 # 向量检索权重（混合模式）
|
||
BM25_WEIGHT=0.35 # BM25 关键词权重
|
||
```
|
||
|
||
## 参考
|
||
|
||
- 完整文档：[README.md](/shumengya/project/agent/mengya-rag/README.md)
|
||
- JSON 输出格式参考：[references/output-schema.md](references/output-schema.md)
|
||
- 源码目录：`/shumengya/project/agent/mengya-rag/src/mengya_rag/`
|