bailian_faiss_kb

使用 Python、FAISS、BM25、阿里云百炼 text-embedding-v4 与可选的 qwen3-rerank，维护基于文件目录的本地知识库；适用于在 OpenClaw 预先抽取文本后，遍历 chunks 与 T2Q 建立索引，以及对指定知识库或全部知识库做综合、语义或关键词查询。

Safety Notice

This listing is from the official public ClawHub registry. Review SKILL.md and referenced scripts before running.

Copy this and send it to your AI assistant to learn

Install skill "bailian_faiss_kb" with this command: npx skills add kadbbz/rag-kb

基于阿里云百炼、FAISS 和 BM25 的知识库

这个 skill 用于配合 OpenClaw 自己的模型，维护目录化知识库。OpenClaw 负责从原始文件中抽取文本，并生成摘要、做语义切片、生成 T2Q；Python 只负责消费已经准备好的文本文件，建立语义与 BM25 索引，并执行查询。

适用场景

  • 消费 OpenClaw 已经抽取好的文本文件
  • 遍历某个知识库目录下的 chunks/ 和 t2q/ 建立或更新索引
  • 对整个知识库执行重建索引，同时重建语义与 BM25 工件
  • 在原始文档目录被删除后，从知识库级索引中移除对应数据
  • 对指定知识库增加或删除保护词，并离线刷新 BM25 工件
  • 对指定知识库做综合查询，默认同时使用语义与 BM25
  • 对指定知识库显式做语义查询
  • 对指定知识库显式做关键词查询
  • 对全部知识库做综合、语义或关键词查询

运行规则

  • 先安装依赖：python3 -m pip install -r {baseDir}/requirements.txt
  • 使用 Python 3.10+
  • 百炼密钥推荐使用环境变量 BAILIAN_SK；脚本同时兼容历史变量名 BAILIAN-SK
  • 向量模型固定为 text-embedding-v4
  • 向量维度固定为 1024
  • BM25 固定使用本地倒排索引和 jieba 分词
  • 每个知识库的保护词单独存放在 /var/openclaw-kb/{kb}/protected_terms.json
  • 可选重排模型固定为 qwen3-rerank
  • 查询默认模式固定为 hybrid
  • OpenClaw 必须先把原始文件抽取为文本，再进入这个 skill
  • summary 必须是单行纯文本，保存为 summary.txt
  • T2Q 只作为语义召回代理，最终查询结果只能返回真实 chunk
  • BM25 只索引真实 chunk，不索引 t2q

安全边界

  • 这个 skill 不执行 shell、不下载远程脚本、不启动后台服务、不监听端口
  • Python 只读写知识库目录下的本地文件，以及脚本显式传入的输入/输出路径
  • index 需要联网生成 embedding；query --retrieval-mode semantic|hybrid 需要联网生成查询 embedding；任意模式启用 --rerank 时需要联网做重排；且只会向阿里云百炼官方接口发起 HTTPS 请求：
    • https://dashscope.aliyuncs.com/compatible-mode/v1/embeddings
    • https://dashscope.aliyuncs.com/compatible-api/v1/reranks
  • 只有百炼密钥会被读取并放入对应请求的 Authorization 请求头；脚本不会收集或上传其他环境变量
  • doctor 与 query --retrieval-mode keyword 不依赖网络，也不会读取百炼密钥

先读路径规范

每次新增、抽取文本、摘要、切片、T2Q、索引、删除之前，必须先读 references/layout.md。

主文档不再重复展开所有命名细节。执行时以 layout.md 为准。

再读内容格式规范

每次生成 summary.txt、chunks/*.md、t2q/*.md 之前，必须再读 references/content-rules.md。

主文档不再重复展开这三类内容的细节。执行时以 content-rules.md 为准。

路径最小约束

知识库根目录默认是 /var/openclaw-kb，但可通过 --root-dir 覆盖。

每个知识库目录下的保护词文件固定为：

/var/openclaw-kb/{kb}/protected_terms.json

每次进入这个 skill 前，必须先算出这三个值：

  • kb：知识库名，例如 regulation
  • ts：上传时间戳，格式固定为 yyyyMMddhhmm
  • safe_name：去掉危险字符后的文件基础名

只有先得到这三个值，后面的文本保存、摘要、切片、T2Q、索引才能继续。

  • 当前文档目录固定为：
/var/openclaw-kb/{kb}/{ts}-{safe_name}
  • OpenClaw 抽取出的文本文件、summary.txt、chunks/、t2q/ 都必须放在这个目录下

职责拆分

1. 文件保存

这是 OpenClaw 的前置步骤，不调用 Python。

OpenClaw 需要：

  • 先按 references/layout.md 算出目标目录和目标文件名
  • 创建目录 /var/openclaw-kb/{kb}/{ts}-{safe_name}/
  • 先从原始文件中抽取文本
  • 将抽取结果保存为 /var/openclaw-kb/{kb}/{ts}-{safe_name}/{safe_name}.md

2. 文本前置条件

这个 skill 不负责文件转文本。

进入摘要、切片、T2Q、索引之前，OpenClaw 必须已经把原始文件抽取成文本文件，推荐保存为：

/var/openclaw-kb/{kb}/{ts}-{safe_name}/{safe_name}.md

也兼容：

/var/openclaw-kb/{kb}/{ts}-{safe_name}/{safe_name}.txt

3. 摘要

这是纯 skill 步骤，不调用 Python。

OpenClaw 读取已经抽取好的文本文件后，需要：

4. 切片

这是纯 skill 步骤，不调用 Python。

OpenClaw 读取已经抽取好的文本文件后，需要：

注意：

  • 只有在文本文件已经准备好的前提下，才进入这个 skill 的后续流程
  • 这个 skill 自身不处理 doc/docx/pdf/ppt/xls/xlsx 到文本的转换

5. T2Q

这是纯 skill 步骤，不调用 Python。

OpenClaw 需要：

6. 建立索引

这一步调用 Python。它会遍历一个文档目录下的 chunks/ 和 t2q/，建立语义索引和 BM25 索引。

python3 {baseDir}/scripts/bailian_faiss_kb.py index \
  --root-dir /var/openclaw-kb \
  --kb regulation \
  --doc-dir /var/openclaw-kb/regulation/{ts}-xx \
  --topk 10 \
  --topN 10

行为：

  • 遍历 chunks/*.md
  • 遍历 t2q/*.md
  • 用 text-embedding-v4 生成 1024 维向量
  • 将 chunk 与 T2Q 代理一起写入 vectors.jsonl
  • 更新 index.faiss
  • 仅基于真实 chunk 构建 BM25 倒排索引并写入 bm25.json
  • 更新 manifest.json
  • 将 topk 与 topN 写入知识库配置
  • 构建 BM25 时读取当前知识库目录下的 protected_terms.json

6.1 重建知识库索引

这一步调用 Python。它会扫描某个知识库目录下的全部文档目录，重新生成整个知识库的语义索引和 BM25 索引。

python3 {baseDir}/scripts/bailian_faiss_kb.py rebuild \
  --root-dir /var/openclaw-kb \
  --kb regulation \
  --topk 10 \
  --topN 10

行为：

  • 遍历 /var/openclaw-kb/{kb}/ 下所有合法文档目录
  • 读取每个文档目录中的 chunks/*.md
  • 读取每个文档目录中的 t2q/*.md
  • 重新写出完整的 vectors.jsonl
  • 重新写出完整的 index.faiss
  • 重新写出完整的 bm25.json
  • 重新写出完整的 manifest.json
  • 这个入口用于“全量重建”，保证语义检索和关键词检索始终一起重建
  • 重建 BM25 时会读取当前知识库目录下的 protected_terms.json

7. 删除

删除分成两步，而且顺序固定为先删索引，再删文件：

  1. 先调 Python 删除知识库索引中的对应数据并持久化：
python3 {baseDir}/scripts/bailian_faiss_kb.py delete \
  --root-dir /var/openclaw-kb \
  --kb regulation \
  --doc-id {ts}-xx

行为：

  • 从 vectors.jsonl 中删除该文档对应的 chunk 和 T2Q 向量记录
  • 重写 index.faiss
  • 重写 bm25.json
  • 重写 manifest.json
  1. 再由 OpenClaw 删除整个文档目录：
/var/openclaw-kb/regulation/{ts}-xx

7.1 增加保护词

这一步调用 Python。它会把保护词写入知识库目录下的 protected_terms.json，然后离线刷新 bm25.json 与 manifest.json。

python3 {baseDir}/scripts/bailian_faiss_kb.py protect-add \
  --root-dir /var/openclaw-kb \
  --kb regulation \
  --term 测试环境权限 \
  --term OpenClaw

行为：

  • 保护词写入 /var/openclaw-kb/{kb}/protected_terms.json
  • 仅更新当前知识库
  • 基于现有 vectors.jsonl 离线重建 bm25.json
  • 刷新 manifest.json
  • 不重建向量，不重写 index.faiss

7.2 删除保护词

这一步调用 Python。它会从知识库目录下的 protected_terms.json 删除指定词条，然后离线刷新 bm25.json 与 manifest.json。

python3 {baseDir}/scripts/bailian_faiss_kb.py protect-delete \
  --root-dir /var/openclaw-kb \
  --kb regulation \
  --term 测试环境权限

行为：

  • 从 /var/openclaw-kb/{kb}/protected_terms.json 删除指定保护词
  • 仅更新当前知识库
  • 基于现有 vectors.jsonl 离线重建 bm25.json
  • 刷新 manifest.json
  • 不重建向量，不重写 index.faiss

8. 查询

这一步调用 Python。

默认综合查询指定知识库：

python3 {baseDir}/scripts/bailian_faiss_kb.py query \
  --root-dir /var/openclaw-kb \
  --kb regulation \
  --query "报销审批流程是什么"

默认综合查询全部知识库：

python3 {baseDir}/scripts/bailian_faiss_kb.py query \
  --root-dir /var/openclaw-kb \
  --query "报销审批流程是什么"

显式只做语义查询：

python3 {baseDir}/scripts/bailian_faiss_kb.py query \
  --root-dir /var/openclaw-kb \
  --kb regulation \
  --query "报销审批流程是什么" \
  --retrieval-mode semantic

显式只做关键词查询：

python3 {baseDir}/scripts/bailian_faiss_kb.py query \
  --root-dir /var/openclaw-kb \
  --kb regulation \
  --query "报销审批流程是什么" \
  --retrieval-mode keyword

需要更高精度时，显式启用 rerank：

python3 {baseDir}/scripts/bailian_faiss_kb.py query \
  --root-dir /var/openclaw-kb \
  --kb regulation \
  --query "报销审批流程是什么" \
  --retrieval-mode hybrid \
  --rerank

查询规则：

  • 若指定 --kb regulation，只查询该知识库
  • 若未指定 --kb，遍历根目录下所有知识库
  • 若知识库索引未加载，则从文件中加载
  • 若未显式指定 --retrieval-mode，默认按 hybrid 做综合检索
  • --retrieval-mode semantic 时，按 FAISS 做语义召回；chunk 与 t2q 都参与召回，命中 t2q 时必须反查回真实 chunk
  • --retrieval-mode keyword 时，只按 BM25 检索真实 chunk；t2q 不参与关键词检索
  • --retrieval-mode hybrid 时，先分别做语义召回和 BM25 召回，再在真实 chunk 级别融合
  • 无 rerank 时，先做召回，再按 topN 返回
  • 有 rerank 时，先做召回与融合，再对真实 chunk 候选做 rerank，返回前 topN
  • 关键词查询分词会读取当前知识库目录下的 protected_terms.json

查询输出格式

默认返回 Markdown，按文件分组，每个命中的 chunk 单独成节。

格式固定为：

## xx.docx

- uploaded at {ts}
- summary: 摘要文本
- total chunks: 该文件的切片数量

### Chunk 00001

这里是 chunk 内容

### Chunk 00002

这里是 chunk 内容

注意：

  • summary 来自 summary.txt
  • 只能返回真实 chunk 内容，不能返回生成的问题文本

检查运行环境

python3 {baseDir}/scripts/bailian_faiss_kb.py doctor \
  --root-dir /var/openclaw-kb

操作说明

  • 这个 skill 不负责替 OpenClaw 生成摘要、切片或 T2Q 的内容，只负责规范这些文件应该长成什么样，以及如何调用 Python
  • 如果某个 chunk 文件或 T2Q 文件命名不合法，Python 会拒绝索引
  • 如果 summary.txt 超过 200 字，Python 会拒绝索引
  • 如果要让新建或更新过的文档参与 BM25，必须重新执行 index
  • 如果只变更保护词，不需要重新做 embedding，可直接执行 protect-add 或 protect-delete
  • 需要更详细的实现说明时，读取 references/runtime-notes.md

Source Transparency

This detail page is rendered from real SKILL.md content. Trust labels are metadata-based hints, not a safety guarantee.

Open Registry RecordOpen in ClawHub

Related Skills

Related by shared tags or category signals.

Coding

YiHui GIT MONITOR

通用 Git 项目监控工具。支持 GitHub、GitLab、Gitee 等所有 Git 平台。可以添加、删除、检查任意 Git 仓库的更新，自动拉取代码并生成变更摘要。

Registry SourceRecently Updated
00Profile unavailable
Coding

Workspace Governance

A methodology-first workspace governance skill for AI agents. Focuses on principles, decision framework, and safe execution patterns instead of fixed directo...

Registry SourceRecently Updated
00mars2003
Coding

Nox Influencer - Creator Discovery & Influencer Marketing

Runs NoxInfluencer creator and marketing-ops workflows via CLI, including creator discovery for influencer marketing, creator marketing, UGC, social media ma...

Registry SourceRecently Updated
2783noxinfluencer
Coding

Gigo Lobster Doctor

🦞 GIGO · gigo-lobster-doctor: 环境体检模式：只检查 gateway、Python 依赖、题包链路与 PNG 证书能力，不跑正式试吃。 Triggers: 龙虾体检 / 检查龙虾环境 / lobster doctor / check lobster environment.

Registry SourceRecently Updated
3220gigolab