seekdb 本地混合检索知识库

本 Skill 提供一个单文件脚本 scripts/kb.py。它基于 OceanBase 开源的 AI 原生数据库 seekdb 的 Python SDK pyseekdb，以嵌入式模式运行：所有数据保存在一个本地目录（默认 ./kb.seekdb），无需启动或部署任何服务。

混合检索：同一个 collection 内同时建立 HNSW 向量索引（all-MiniLM-L6-v2，384 维，余弦距离）和 IK 分词全文索引，查询时两路召回后用 RRF（Reciprocal Rank Fusion）融合排序。全文路径负责精确词，例如错误码、型号、函数名；向量路径负责同义改写。
增量入库：分块 ID 由“文件路径 + 分块序号”确定；文件内容哈希未变化时跳过；文件变短时自动删除多余的旧分块。重复执行 ingest 不会产生重复数据。
可引用结果：每条结果都带 source（文件绝对路径）和 chunk（分块序号）；--json 输出完整分块文本，便于交给大模型作答并标注出处。

何时使用

用户要求“在我的文档或笔记里搜索”“给这个目录建一个本地知识库”“基于这些文档回答问题并给出出处”。
需要同时命中精确关键词和语义相近内容；纯向量检索容易漏掉编号、错误码等精确词。
运行环境不能或不想安装数据库服务器，例如笔记本、CI 或离线机器（模型下载完成后即可离线使用）。

不适用：PDF、Word 等二进制文档（请先转换为文本或 Markdown）；需要多机共享的大规模线上检索（应改用 seekdb/OceanBase 服务器模式）。

环境准备

pip install -U pyseekdb          # 需要 Python 3.11+；嵌入式引擎 pylibseekdb 随包安装（已在 pyseekdb 1.4.0 / Linux x86_64 上验证）

首次写入或查询时会自动下载约 90MB 的 ONNX 嵌入模型。默认从 https://hf-mirror.com 下载；网络不通时可设置 HF_ENDPOINT 指向可访问的 Hugging Face 镜像，或配置 https_proxy。

使用步骤

脚本路径相对本 Skill 目录。--db 与 --collection 是全局参数，必须写在子命令之前，也可以通过环境变量 KB_DB、KB_COLLECTION 设置。

入库：传入文件或目录。目录会递归读取 .md/.markdown/.txt/.rst，并跳过以 . 开头的隐藏路径。

python scripts/kb.py --db ./kb.seekdb ingest ./docs
# 可选：--chunk-size 800 --overlap 100 --ext .md,.txt --force

检索：默认使用混合检索，返回前 5 条。

python scripts/kb.py --db ./kb.seekdb search "如何不部署服务器就使用数据库"
python scripts/kb.py --db ./kb.seekdb search "启动报错怎么办" --keywords "1235"   # 全文路径改用精确词
python scripts/kb.py --db ./kb.seekdb search "下载超时" --mode vector -k 3          # 仅向量 / --mode fulltext 仅全文
python scripts/kb.py --db ./kb.seekdb search "RRF" --name seekdb-intro.md --json   # 按文件名过滤，输出 JSON

维护：

python scripts/kb.py --db ./kb.seekdb stats                        # 分块数、文件数和文件清单
python scripts/kb.py --db ./kb.seekdb remove ./docs/old.md         # 删除某个文件的全部分块

智能体工作流程建议

先运行 stats，确认知识库是否已经存在；如果不存在，或者用户提到文档有更新，再对相应目录运行 ingest。增量更新开销很小。
用用户的问题执行 search --json -k 5。如果问题中包含错误码、版本号、表名等精确词，同时传入 --keywords。
只根据返回的 text 作答，并以 source#chunkN 形式标注引用；结果为空或不相关时，如实说明未找到，不要凭空补充内容。
结果偏向语义近似但缺少精确词时，改用 --mode fulltext 交叉验证；反之可以改用 --mode vector。

示例

本 Skill 的 examples/docs/ 目录附带两个示例文档：

python scripts/kb.py --db /tmp/demo.seekdb ingest examples/docs
# indexed examples/docs/seekdb-intro.md -> 1 chunks
# indexed examples/docs/troubleshooting.md -> 1 chunks
# done: 2 file(s) indexed, 2 chunk(s) written, 0 unchanged file(s) skipped

python scripts/kb.py --db /tmp/demo.seekdb search "error 1235" --mode fulltext -k 1
# [1] /.../examples/docs/troubleshooting.md#chunk0
#     # Troubleshooting ## Embedding model download fails ...

再次执行同一条 ingest 命令时，会输出 2 unchanged file(s) skipped。

注意事项

source 记录的是文件的绝对路径。移动文档目录后，旧路径的数据不会自动清理，需要先运行 remove 删除旧路径，或者删除整个 --db 目录后重新入库。
默认集合使用 384 维模型。若要改用其他嵌入模型，需要换一个新的 --collection，不能与旧集合混用。
嵌入式数据目录同一时间只应由一个进程写入。