shield_lock
JinDaGe
← Back to skills
extension
Category: Productivity & OfficeNo API key required

local-kb-rag

本地私有知识库 RAG Skill：把 PDF/Markdown/TXT 摄入本地向量库，提供带引用的语义检索与问答，全链路 OpenVINO 本地推理（NPU 跑 Embedding/Rerank，iGPU 跑 LLM，CPU 兜底），语料不出机。Use when the user asks to 检索我的笔记/文档、问一下知识库、PDF 问答、本地 RAG、私有第二大脑、研报摘要、ingest/search/ask my knowledge base、local private RAG、query my notes、offline knowledge assistant。适配 Qoder / WorkBuddy / TRAE Work，经 MCP 工具 kb_ingest / kb_search / kb_ask / kb_list_sources / kb_status 调用。触发词：知识库 / 笔记 / RAG / 问答 / 检索 / 摄入 / PDF / Markdown / 私有 / 离线 / 第二大脑 / 引用 / knowledge base / KB / local RAG / retrieval / citation / ingest。

personAuthor: XJH0247hubModelScope
downloadDownload package

本地私有知识库 RAG（local-kb-rag）

把个人 PDF/Markdown 笔记沉淀为「永不掉线、完全私有」的数字第二大脑。 全链路 OpenVINO 本地推理：BGE-M3 Embedding 与 BGE-reranker 精排跑在 NPU， Qwen2.5-7B-Instruct INT4 生成跑在 iGPU，无加速硬件时自动回退 CPU。 语料、向量、模型全部驻留本机，仅答案文本回传 Agent。

何时使用本 Skill

| 用户意图 | 应调用的工具 | |---|---| | 「把这个 PDF/笔记加入知识库」「记住这份文档」 | kb_ingest | | 「在我的笔记里找…」「知识库里关于 X 的片段」（只要原文，不要生成） | kb_search | | 「根据我的文档回答…」「知识库问答」（需要归纳的答案 + 引用） | kb_ask | | 「知识库里都有什么文档」 | kb_list_sources | | 「RAG 服务状态怎么样」「模型跑在什么设备上」 | kb_status |

工具使用指引（供 Agent 大脑决策）

  1. 先摄入后问答：若用户给出文件路径，先 kb_ingest(path=...)；kb_ingest 幂等， 同一 doc_id 重复摄入会覆盖更新。
  2. search vs ask：用户要「原文片段/出处定位」用 kb_search（秒级，实测约 2–5s）； 要「归纳性答案」用 kb_ask（检索+精排+本地 LLM，十秒级，视设备而定）。
  3. 引用可信：kb_ask 返回的 citations[] 是真实检索片段回填， 答案中 [1][2] 编号与之对应，可直接展示给用户核对出处。
  4. 首次调用：会自动拉起常驻推理 server；首跑需下载模型（数 GB，支持断点续传）， 请先调用 kb_status 告知用户 state（downloading/loading/running）。
  5. 空文件/不支持格式：kb_ingest 支持 .pdf .md .markdown .txt； 其他格式请先转换或用 content 参数直接传入文本。

接入方式

第 0 步：安装环境（两种方式都需要）

& .\scripts\install-env.ps1            # 默认官方 PyPI
& .\scripts\install-env.ps1 -Mirror    # 国内网络推荐：清华镜像

脚本会自动：

  • 选择 Python 3.12/3.11/3.10 创建专用 venv（%USERPROFILE%\.openvino\venvs\local-kb-rag）， 3.13+ 会被拒绝（openvino/onnxruntime 无预编译轮子，源码编译必败）；
  • 屏蔽外部 pip 配置与 PIP_TARGET/PYTHONPATH 污染，强制 --only-binary :all:；
  • 装完实测 import 验证通过才写完成标记，失败可直接重跑（幂等）。

方式 A：MCP（Qoder / WorkBuddy / TRAE Work 推荐）

在宿主的 MCP 配置（如 Qoder mcp.json）中注册：

{
  "mcpServers": {
    "local-kb-rag": {
      "command": "%USERPROFILE%\\.openvino\\venvs\\local-kb-rag\\Scripts\\python.exe",
      "args": ["<skill_root>\\scripts\\mcp_adapter.py"]
    }
  }
}

首次注册前先执行 scripts\install-env.ps1 完成环境安装。

方式 B：标准 CLI（官方 run.ps1 入口）

& .\scripts\run.ps1 status
& .\scripts\run.ps1 ingest --source "C:\notes\spec.pdf"
& .\scripts\run.ps1 search --query "OpenVINO 如何部署到 NPU"
& .\scripts\run.ps1 ask --query "本方案如何保证隐私不出机？"
& .\scripts\run.ps1 list-sources
& .\scripts\run.ps1 remove-source --doc-id a1b2c3
& .\scripts\run.ps1 shutdown

两种方式经同一条 named pipe（\\.\pipe\local-kb-rag）调同一个常驻 server， 模型只加载一次；空闲 300s 自动关停释放显存。

运行要求

  • Windows AIPC（Intel Core Ultra 推荐，NPU/iGPU 自动探测，无则 CPU 兜底； 实测 CPU+iGPU 机型可正常降级运行）
  • 内存 ≥ 8GB；磁盘 ≥ 10GB（模型缓存）
  • Python 3.10–3.12（硬性要求：闭源推理包仅发布 cp310–cp312 预编译轮子， 3.13/3.14 无法安装；install-env.ps1 会自动校验并拒绝不合规版本）
  • 首跑需联网下载模型（ModelScope，支持断点续传），此后完全离线

离线能力（实机断网验证）

本 Skill 的数据面（推理/向量库/问答全链路）100% 本地，断网可用； 但宿主 Agent 的「大脑」（如 Qoder 云端模型）离线时不可用：

| 场景 | 断网后 | 用法 | |---|---|---| | MCP 工具调用（自然语言） | ❌ 宿主云端大脑不可达 | 恢复联网后可用 | | CLI 直调（本地数据面） | ✅ ingest/search/ask 全链路正常 | & .\scripts\run.ps1 … |

前提：模型已下载完成（首跑联网一次）。

故障排查

日志与运行时文件（%USERPROFILE%\.openvino\ 下）：

| 文件 | 用途 | |---|---| | logs\local-kb-rag\server.log | server/pipeline 主日志（状态机、设备分配、异常） | | logs\local-kb-rag\server.stderr.log | 原生层崩溃取证（Python traceback 之外的硬崩） | | runtime\local-kb-rag\server.pid | 常驻 server 进程号 |

常见问题：

  • server 硬崩后能自愈：单实例判活基于 pipe 实探而非 pidfile，残留 pidfile / PID 复用不会导致拒启，下次调用自动拉起新 server。
  • 脚本升级后无需手动重启：client 比对脚本 hash，变更时自动 shutdown 旧 server 并重启（日志可见 script hash changed, restarting server）。
  • 磁盘占用迁移：模型/venv 占用数 GB，可用 NTFS junction 把 %USERPROFILE%\.openvino\{models,venvs} 透明映射到大盘（代码零改动）： New-Item -ItemType Junction -Path "$env:USERPROFILE\.openvino\models" -Target "D:\openvino-store\models"。
  • 首次安装失败：确认 Python 版本在 3.10–3.12，国内网络加 -Mirror 重跑； 模型下载中断后重跑会断点续传，已下载的原始权重不会丢失。