shield_lock
金大哥
← 返回 Skill 列表
extension
分类: 开发与工程API Key 暂未确认

LocalRAG：本地知识库与文档专家套件

面向人事、行政的本地文档处理：查询制度、生成带来源的中文速查，再翻译成英文。三个技能共享 OpenVINO 与 Qwen3 INT4 本地 引擎，在 2020 年购入的 i5、16GB 笔记本上完成样例验证。速查复用已有问答，不新增检索或模型生成。主问答已在 WorkBuddy、QwenWork、TRAEWork 实测，三技能组合流程已在 WorkBuddy 跑通。模型和依赖就绪后，本地引擎可离线运行。

person作者: oranhsdshubModelScope
download下载资源包

LocalRAG：本地知识库与文档专家套件

在一台 2020 年买的 i5、16GB 笔记本上，用 CPU 跑通带来源问答、中文速查和英文翻译。

人事、行政处理请假和报销咨询时，需要反复查制度、核对条件，再把答案整理成能发给员工的说明。有英文材料需求时，还要翻译同一份内容。LocalRAG 用 OpenVINO 和 Qwen3 INT4 小模型完成这些步骤，支持 PDF、DOCX、Markdown、TXT，三个技能共享同一个本地引擎。

本地模型带来什么

| 使用价值 | 实现方式 | |---|---| | 利用现有电脑 | i5-1035G1、16GB、CPU 已完成样例验证；生成模型提供 1.7B / 4B 两档 | | 模型就绪后可离线处理 | 索引、检索、生成和翻译调用本机服务，不调用云端推理 API | | 按需调用本地模型 | 同一档位复用常驻模型；--from-query --brief 直接整理已有问答，0 次新增检索、0 次模型生成 |

首次准备模型和依赖需要联网。接入云模型宿主时，宿主仍可能消耗 credits，并处理它读回的资料；本地引擎的离线能力与宿主行为需分别判断。

一个文档任务，三个专家技能

用示例员工制度验证的流程：查询“员工请假需要提前多久申请？”和“报销单需要附上哪些材料？”，整理成中文速查，再生成英文版。

| 技能 | 负责什么 | 交付文件 | |---|---|---| | local-rag（上传名 local-rag-offline） | 建库、查资料、回答并附来源 | 问答 JSON 与完整检索片段 | | local-doc-report | 复用问答生成速查，或综合详细报告 | 中文 Markdown | | local-doc-translate | 翻译上一步实际生成的文档 | 英文 Markdown，保留来源文件名 |

三个成员各有 SKILL.md 和固定入口。速查使用 --brief 逐题保留已有答案；详细报告调用本地模型综合。翻译读取实际中文文件，对时限、常用制度术语和来源列表做保护，交付前仍需核对全文。

成员说明：报告技能 · 翻译技能。宿主按文末“套件任务交接”执行。

实机结果

以下记录来自 i5-1035G1、16GB、CPU，使用 demo 档 Qwen3 1.7B INT4。各行计时范围不同：

| 验证内容 | 耗时 | 计时范围 | |---|---|---| | 单题短问答 | 16.1–23.8 秒 | 历史热查询，模型已常驻 | | 完整命令行样例 | 73.54 秒 | 索引、两次问答、中文速查与翻译；不含宿主调度 | | WorkBuddy 完整任务 | 8 分 4 秒（日志 484.489 秒） | 包含技能读取、调度、命令拦截排查、网络恢复和文件核对 |

WorkBuddy 本轮原始产物保留了两道问题、请假提前 1 天与连续超过 3 天的条件、发票照片与行程说明，以及来源文件名；英文正文未经手工改写。1.2.1 版本源码与分发包各有 116 项自动化检查通过，内容另行逐项核对。

中文原始文件 · 英文原始文件 · 完整验证记录

WorkBuddy 三技能完成页

界面 8 分 4 秒与整轮日志一致；截图正文中的 286 秒只覆盖中间区间。中文文件截图与英文文件截图可核对内容；截图左侧“翻译数秒级”不作为计时依据，成功翻译调用到返回为 26.030 秒。

主问答已在 WorkBuddy、QwenWork、TRAEWork 实测；三技能组合流程已在 WorkBuddy 验证。平台接入与开发过程见实践文章。

快速使用与平台接入

下载完整 local-rag-offline 文件夹，在该目录的 PowerShell 中执行：

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\run.ps1 index --dir "D:\我的资料" --collection mydocs
if ($LASTEXITCODE -ne 0) { throw '索引未成功，请检查输出' }
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\run.ps1 query "报销流程是什么？" --collection mydocs --profile demo

入口会检查环境、准备依赖并按需启动本地服务。遇到模型下载等待，按提示用 --continue 续跑。运行 .\demo.bat --quick 可执行完整示例流程，结果写入本轮新目录。

在 WorkBuddy 中分别安装主技能、kit/local-doc-report 和 kit/local-doc-translate，刷新技能或新开会话后即可让宿主读取并调用。成员需分别安装，只有嵌套 kit 目录不足以保证自动发现。目录联接命令、手动启动与健康检查见 README。

模型与适用范围

demo 档使用 Qwen3 1.7B INT4，quality 档使用 Qwen3 4B INT4；两档共用 bge-small-zh INT8 与 ChromaDB。服务常驻，同档位连续任务复用模型，切档可能重新加载。各技能采用 SKILL.md 与 scripts/run.ps1 固定入口，结构参考 local-ai-skill-authoring。

适合已索引文字资料的事实查询、报告整理和中英翻译。扫描 PDF 需先取得文本；资料不足时返回 delegate 交宿主处理。时限和来源保护有明确范围，其他文档仍需核对内容。

本次机器有 UHD 核显与 MX350 独显，无 NPU，实际使用 CPU 推理。Intel Core Ultra / NPU 尚未实测；其他设备的兼容性与速度需单独验证。

宿主调用约定（Agent 必读）

每个技能通过自己的 scripts/run.ps1 入口调用，由入口处理环境、常驻服务和 HTTP 请求。套件协作使用对应成员的入口，不直接调用内部 Python 脚本或 HTTP 端点。

快速决策

用户想……
│
├─ “加载 local rag”
│   └─ 调用一次入口，简短回复“已加载，可以直接提问”，不要复述模型、架构和参数
│
├─ 提问（公司制度 / 福利 / 报销 / 入职等已索引内容）
│   └─ 走下方「普通问答」
│
├─ 给新资料建库 ───────────────── 走下方「索引与报告」
├─ 查资料后生成简报 / 翻译交付 ─── 走下方「套件任务交接」
│
├─ 想看到生成过程 ─────────────── query 加 --stream
├─ 想要更高质量的回答 ─────────── query 加 --profile quality
│
└─ 本地资料答不了
    └─ status=delegate（退出码 4）：读 delegate.privacy 分级，
       safe_to_forward 才可交给联网等其它能力，不视为执行故障

delegate.privacy 是启发式提示，safe_to_forward 不代表用户授权；对外转交前，仍须结合实际内容和用户已有授权判断。

适用边界

  • 知识边界就是已索引的文件。边界外的问题不硬答、不编造，走 delegate 转交。
  • 支持 PDF / DOCX / Markdown / TXT；不解析图片、音频、视频。
  • 模型和依赖就绪后，本地检索与生成不调用云 API；首次准备需要网络。实时信息请求走 delegate，宿主联网、费用与读回资料的处理由宿主决定。

普通问答

使用用户指定或索引时返回的 collection。项目历史示例使用 demo，短流程使用 kit_demo；其他机器需要先索引示例资料，新资料使用其索引时指定的 collection。

WorkBuddy 有时只返回退出码，不返回 stdout。首次查询使用 --out 将同一次请求的 JSON 保存到唯一结果文件，随后用宿主文件读取工具读取：

& "<SKILL_DIR>/scripts/run.ps1" query "<QUESTION>" --collection "<COLLECTION>" --json --out "<UNIQUE_RESULT_FILE>" --from-skill workbuddy --timeout 600
exit $LASTEXITCODE
  • <SKILL_DIR> 是本文件所在目录。
  • <UNIQUE_RESULT_FILE> 使用工作区或临时目录下的新绝对路径，每次请求换一个文件名；不要删除或覆盖已有文件。
  • 命令完成后直接 Read 同一个结果文件。若返回后台 task_id，用 TaskOutput 等待同一任务完成，再 Read。
  • 同一问题只执行一次 query。结果文件收取失败时报告错误，不得重跑查询、改用其它端点或重复健康检查。
  • 普通单主题问题省略 --top-k：demo 默认 2 段、quality 默认 4 段。跨多个主题或要求完整汇总时，在首次查询中加 --top-k 4。
  • --json 与 --stream 互斥。仅在用户要求查看生成过程时使用 --stream。
  • 后续需要生成报告时，在首次查询增加 --full-sources，将完整片段保存给报告技能；普通问答保持短预览。

结果处理：

  • status=ok：使用 answer 回答，并把 sources 中实际采用的文件名作为来源。
  • status=delegate：这是有效结果。说明本地资料未能回答；根据 delegate.privacy 判断是否可交给其它能力，退出码 4 不视为执行故障。
  • 面向用户只给自然答案和必要来源。除非用户主动询问诊断信息，不展示模型名称、CPU/设备、档位、相似度、端点、脚本、退出码或内部耗时。
  • 示例文档中的公司和政策均为虚构；需要说明时称为“示例资料”，不要称为真实企业资料。
  • 不要重复整理或扩写模型已经给出的答案，不主动邀请切换模型或继续测试。

索引与报告

& "<SKILL_DIR>/scripts/run.ps1" index --dir "D:/资料目录" --collection mydocs
& "<SKILL_DIR>/scripts/run.ps1" report --topic "新员工入职" --collection mydocs --num-questions 3

索引支持 PDF、DOCX、Markdown、TXT。首次使用新 collection 前必须先索引。报告默认每题召回 4 段，并完成问题规划、逐条检索和 Markdown 交付。

套件任务交接

用户同时要求查资料、整理报告和翻译时，先读取两个套件成员的 SKILL.md，再根据业务范围拆分任务：

  1. 主技能执行一次 query --full-sources --json --out <QUERY_JSON>，保留本轮问答与完整来源。需要多份独立问答时各使用新文件。
  2. 调用 local-doc-report 的入口，使用 --topic <主题> --collection <同一知识库> --from-query <QUERY_JSON> --brief --out <REPORT_MD>。速查逐题保留原答案，不再检索或调用模型改写；详细报告省略 --brief，再调用模型综合一次。多份问答必须逐一传入，重复使用 --from-query。
  3. 调用 local-doc-translate 的入口，以刚才的 <REPORT_MD> 作为 --in，新路径作为 --out。同一次任务翻译实际报告，保留来源文件名。
  4. 读取两个实际产物，核对每道问题、条件、数字、材料名称与来源。引用列表保留检索到的文件，不代表每份文件都支持所有结论。发现遗漏或误译时如实指出；如用户需要校订，另存修订版，保留原始文件，不能将宿主修文称为本地模型一次成功。

资料已索引时复用 collection；短流程脚本使用独立的 kit_demo 示例库。快速演示可在首次查询使用 --profile demo，后续默认沿用该档位。完整流程耗时包含多个步骤，应单独计时。

问答文件若缺少完整来源标记、知识库不匹配或文件不存在，报告入口会报错；读取并说明错误，不悄悄重复查询。核心检索与生成在本地执行，宿主读取结果后的数据处理方式由宿主决定。

常用参数

| 参数 | 用途 | 默认 | |---|---|---| | --collection | 隔离不同资料集 | default | | --top-k | 问答召回片段数 | demo=2，quality=4 | | --profile | demo 低延迟；quality 更高质量 | 当前档位 | | --json | 输出结构化结果 | 关闭 | | --out | query 保存本轮 JSON；report/translate 保存文档 | 按命令指定 | | --full-sources | query 保留完整来源供报告复用 | 关闭 | | --stream | 实时输出来源和回答 | 关闭 | | --timeout | 查询超时秒数 | 600 |

服务未启动时入口会自动拉起并等待模型就绪；服务常驻后无需重复加载。不要在普通问答前额外调用健康检查或切换档位。

异常处理速查

| 退出码 | 含义 | 宿主动作 | |---|---|---| | 0 | 成功 | 正常读取结果 | | 1 | 一般错误 | 读取结果文件中的错误信息，如实报告用户 | | 2 | 连接错误 | 入口通常会自动拉起服务；仍失败则报告用户，不重复重试 | | 3 | 模型下载中 | 按提示加 --continue 续跑，断点安全 | | 4 | 本地无法回答 | 读取 delegate 字段按隐私分级转交，不视为故障 |