shield_lock
JinDaGe
← Back to skills
extension
Category: Development & EngineeringNo API key required

LocalRAG 私有知识库问答

把本地 PDF / Word / Markdown / TXT 文档构建成完全离线的私有知识库，语义检索 +本地小模型生成回答，文档与模型全程不出机。基于 OpenVINO INT4 量化的 Qwen3-4B 与 bge-small-zh，在 16GB 内存的 Intel轻薄本上纯 CPU 可跑。含 18 项单元测试、三种推理设备实测、自动建 venv 与模型自动下载，已在 WorkBuddy 中验证可稳定调用。

personAuthor: oranhsdshubModelScope
downloadDownload package

LocalRAG — 本地私有知识库问答

触发场景

  • 用户需要对本地文档（PDF / Word / Markdown / 纯文本）进行语义检索问答时
  • 用户提到"知识库""本地文档问答""资料检索""私有数据"等意图
  • 文档内容敏感，不能上传云端时（数据不出机是核心卖点）

调用方式

统一通过固定入口 scripts/run.ps1 调用：它负责定位项目根目录与 Python 环境，并把参数原样转发给唯一客户端 client.py；服务检测、拉起与等待就绪由 client.py 完成，随后通过 HTTP 调用本地模型服务。

# 索引文档目录（首次使用必须先执行一次）
powershell -NoProfile -ExecutionPolicy Bypass -File "<SKILL_DIR>\scripts\run.ps1" index --dir "D:\我的资料" --collection mydocs

# 知识库问答
powershell -NoProfile -ExecutionPolicy Bypass -File "<SKILL_DIR>\scripts\run.ps1" query "我们部门的报销流程是什么？" --collection mydocs

# 纯对话（不检索知识库）
powershell -NoProfile -ExecutionPolicy Bypass -File "<SKILL_DIR>\scripts\run.ps1" chat "用一句话介绍你自己"

<SKILL_DIR> 为本 SKILL.md 所在目录。本机已安装在 C:\Users\86155\.workbuddy\skills\local-rag（目录联接指向项目 skill\ 目录）。

重要：请只通过 scripts\run.ps1 调用本技能，不要直接调用其内部的其他脚本。

参数说明

| 参数 | 说明 | 默认 | |---|---|---| | --dir | 待索引的文档目录（递归扫描 pdf/docx/md/txt/markdown） | 必填 | | --collection | 知识库名称（隔离不同资料集） | default | | --top-k | 问答时召回片段数 | 4 | | --server | 本地服务地址 | http://127.0.0.1:8765 | | --timeout | 请求超时秒数（问答 600 / 索引 1800） | 见左 | | --json | 问答时输出 JSON，便于 Agent 解析 | 关闭 |

行为说明

  • 索引：递归扫描目录，逐个文件解析 → 分块（500 字/块，80 字重叠，优先在句号或换行处断开）→ 向量化入库
  • 检索：bge-small-zh 向量化 + 余弦相似度，返回 top-k 片段（分数 0~1，越大越相关）
  • 生成：把检索片段拼成上下文交给本地 Qwen3-4B，要求只依据资料回答；资料里没有的会明确答"资料中未找到相关信息"，不编造
  • 输出包含回答 + 来源文件 + 相似度，便于溯源

前置条件

  1. 依赖与模型获取见项目根 README.md（模型走魔搭，python server/download_models.py 一键下载）。首次运行需先下载模型（Qwen3-4B INT4 约 2.3GB + bge 约 90MB），耗时较长，请耐心等待
  2. 模型服务由 run.ps1 自动拉起；也可手动常驻：cd server && python app.py --preload
  3. 首次使用需先执行一次 index，否则 query 会返回"知识库为空"
  4. 本技能面向 Windows + OpenVINO 环境（纯 CPU 可运行）。若运行环境不满足（如未找到可用的 Python、模型服务无法启动），run.ps1 会明确报错并以非零退出码结束，不会静默继续
  5. 本技能无云端回退：所有模型推理均在本地完成，数据不出机；服务不可用时直接报错，不会偷偷调用云端 API

性能与注意事项（i5-1035G1 + 16GB + 纯 CPU 实测）

  • 单轮问答：冷机约 110 秒，连续使用后会退化到 4 分钟以上。同一问题三次实测 111.8s / 123.7s / 258.5s—— 答案与相似度完全一致，但耗时抖动 2.3 倍：轻薄本持续推理会掉频，这是低配机跑本地大模型的真实特征，不是偶发。
  • 索引很快：4 个文件 5070 字 → 13 块，1.8 秒
  • 模型加载约 20 秒（服务常驻后不再重复加载），这也是必须用 Client/Server 而非每次起进程的原因
  • 服务已对推理加锁：并发请求排队而不是报错，Agent 连续发问不会打断
  • 建议把问题问具体，命中更准、生成更短

技术栈

  • 推理框架：OpenVINO™ + Optimum-Intel
  • 生成模型：OpenVINO/Qwen3-4B-int4-ov（官方预量化 INT4，2.29GB）
  • Embedding：bge-small-zh-v1.5（约 90MB，首次启动自动导出 OpenVINO IR）
  • 向量库：ChromaDB（不可用时自动降级 numpy）
  • 服务：FastAPI（Client/Server，模型常驻，绑定 127.0.0.1）
  • 推理设备：server/config.py 的 GEN_DEVICE 可切 CPU / GPU / NPU，目标设备不可用会自动回落 CPU