shield_lock
金大哥
← 返回 Skill 列表
extension
分类: 效率与办公无需 API Key

本地私人知识库智能问答

本地私人知识库智能问答

person作者: ylyhf2026hubModelScope
download下载资源包

本地私人知识库智能问答（Local RAG）

基于本地 AI 大模型的私有知识库 RAG 问答技能。所有文档处理、向量嵌入、检索与生成均在本地完成（OpenVINO 加速），隐私数据绝对不出机。

技术架构

用户指令 → run.ps1 / run.cmd / run.sh → client.py ──命名管道──→ server.py（长驻）
                                                  ├─ doc_loader.py  文档加载与分块
                                                  ├─ vector_store.py 向量存储（NumPy）
                                                  └─ rag_engine.py  嵌入→检索→生成
                                                       ├─ Qwen3-Embedding-0.6B（INT8）
                                                       └─ Qwen2.5-1.5B-Instruct（INT4）

入口选择：run.ps1（PowerShell 宿主，含硬件检测与环境安装）；run.cmd（cmd 宿主，纯 UTF-8 输出）；run.sh（Git Bash / MSYS 宿主，如 WorkBuddy / TRAE，Bash 原生、不经过 cmd.exe）。三者功能完全一致，参数相同。

  • 嵌入模型：OpenVINO/Qwen3-Embedding-0.6B-int8-ov（多语言，INT8 量化）
  • 生成模型：OpenVINO/qwen2.5-1.5b-instruct-int4-ov（INT4 量化）
  • 推理框架：OpenVINO GenAI（无需 PyTorch，轻量独立运行）
  • 向量存储：NumPy 余弦相似度（零外部数据库依赖）
  • 部署方式：Client/Server 命名管道架构（模型常驻内存，秒级响应）

Usage

入口脚本按宿主 shell 三选一：scripts\run.ps1（PowerShell 宿主）、scripts\run.cmd（cmd 宿主）、bash scripts/run.sh（Git Bash / MSYS 宿主）。三者参数完全相同。切勿直接调用 client.py/server.py 等内部脚本。

宿主调用矩阵

| 宿主 shell | 推荐入口 | 说明 | |------------|----------|------| | PowerShell | scripts\run.ps1 <命令> | 含硬件检测与环境安装 | | cmd | scripts\run.cmd <命令> | 纯 UTF-8 输出 | | Git Bash / MSYS（WorkBuddy、TRAE 等） | bash scripts/run.sh <命令> | Bash 原生，不经过 cmd.exe |

警告：在 Git Bash / MSYS 中切勿用 cmd //c 或 cmd /c 包装调用本技能——// 前缀会被 MSYS 路径转换破坏导致开关失效，中文参数会被 cp936 代码页转乱，表现为输出被吞、路径乱码。

命令示例

| 功能 | 命令 | |------|------| | 导入文档 | scripts\run.ps1 add "C:\docs\报告.pdf" | | 批量导入 | scripts\run.ps1 add "C:\docs\file1.pdf" "C:\docs\file2.txt" | | 导入目录 | scripts\run.ps1 add "C:\docs\folder" | | 导入文本 | scripts\run.ps1 add-text "这是一段知识内容" --source "笔记" | | 知识库问答 | scripts\run.ps1 ask "这份报告的主要结论是什么？" | | 指定检索数 | scripts\run.ps1 ask "问题" --top-k 8 | | 列出来源 | scripts\run.ps1 list | | 移除来源 | scripts\run.ps1 remove "报告.pdf" | | 清空知识库 | scripts\run.ps1 clear | | 重建索引 | scripts\run.ps1 reembed | | 查看状态 | scripts\run.ps1 status | | 关闭服务 | scripts\run.ps1 shutdown |

支持的文档格式

.txt .md .pdf .docx .csv .html .htm

输出解读

  • ask：返回 答: 答案正文 + 引用来源: 来源文件列表 + 检索片段: 匹配文本预览及相似度分数。若最高检索分数低于相关性阈值（默认 0.5，可用环境变量 LOCAL_RAG_SCORE_THRESHOLD 调整），会显示 ⚠ 低置信度 提示且相应片段标注 ⚠低置信，表示知识库中可能没有相关内容、回答仅供参考
  • add：返回每个文件的导入分块数，失败文件单独标注
  • status：返回服务状态（running/downloading/loading/error）、PID、运行时间、知识库分块数、设备与索引版本信息
  • reembed：用当前嵌入配置重建全部已有分块的向量（嵌入配置变更后迁移旧索引用，无需重新导入文档）。若索引过期，ask/add/status 会提示先运行该命令

--continue 续传协议

首次运行时模型需从 ModelScope 下载（约 1.5GB）。若下载未在 8 分钟内完成：

  1. 客户端保存待处理请求到 ~/.openvino/local-rag-pending-request.json
  2. 输出提示：模型正在下载中，请稍后使用 --continue 继续运行
  3. 退出码 3
  4. 用户执行 scripts\run.ps1 --continue 自动恢复中断的请求

失败处理

  • 服务未启动：客户端自动拉起服务端进程（独立模式）
  • 模型下载失败：检查网络连接，重新运行或使用 --continue
  • 文档格式不支持：返回不支持的格式列表及已支持的格式
  • 知识库为空时问答：返回提示信息，引导用户先导入文档

Important

  • 唯一入口：仅通过 scripts\run.ps1 调用，不要直接运行 client.py 或 server.py
  • 首次运行：需下载模型（约 1.5GB），请确保网络畅通；后续运行无网络需求
  • 平台要求：推荐 Intel AIPC（GPU/NPU 加速）；非 AIPC 平台以 CPU 模式运行
  • 无云端回退：所有推理纯本地完成，不发送任何数据到云端
  • 数据隐私：文档内容、向量索引均存储在本地 ~/.openvino/data/local-rag/
  • 内存占用：建议 ≥ 8GB 可用内存。实测常驻服务进程 WorkingSet：导入后 5,354.8MB → 首次问答后 5,600.7MB → 稳态 5,585.2MB（Private 5,883MB）。生成模型（Qwen2.5-1.5B-int4）与嵌入模型（Qwen3-Embedding-0.6B-int8）同时常驻，所以空闲内存低于 6GB 时首问容易 OOM；内存紧张可改 info.json 换用更小的生成模型（如 Qwen2.5-0.5B）

安装到 TRAE Work / WorkBuddy / Qoder

将本技能目录复制到宿主应用的 skills 目录：

  • TRAE Work: .trae\skills\local-rag\
  • WorkBuddy: 对应 skills 目录
  • Qoder: 对应 skills 目录

宿主应用会根据 SKILL.md 的 description 字段自动路由用户意图到本技能。