OpenKB 中文教程：v0.4.5 安装、长 PDF 与权限边界

OpenKB 不是上传一份 PDF 就结束的聊天壳。它先把文件或网页转换为资料源，再编译成带摘要、概念、实体和交叉链接的 Markdown Wiki，查询、对话、演示文稿和 Agent Skill 都从这个 Wiki 读取。2026 年 9 月 23 日核对时，最新正式版是 v0.4.5，发布于 2026 年 7 月 20 日；

安装前先定好数据边界

基础要求是 Python 3.10 以上。建议新建虚拟环境，避免 OpenKB 固定的模型依赖与现有项目冲突。模型写成 provider/model，密钥放进知识库目录的 .env，不要提交。PageIndex 本地版是默认选项；设置 PAGEINDEX_API_KEY 后才能使用云端 OCR 和结构解析。也就是说，“无需向量数据库”不等于“资料一定不出本机”：你选用的 LLM API 和 PageIndex Cloud 都有独立的数据处理路径。

路径一：固定正式版建立命令行知识库

python3 -m venv .venv
source .venv/bin/activate
python -m pip install "openkb==0.4.5"
mkdir product-kb && cd product-kb
openkb init
openkb add ./manual.pdf
openkb query "这份手册的升级前置条件是什么？"
openkb status
openkb list
openkb lint

openkb init 会生成 .openkb/config.yaml。短资料通常整篇交给模型；官方默认在 PDF 达到 20 页时切入 PageIndex 树索引。导入后先用 list 看登记状态，再用一个能在原文定位的问题检查答案和引用，最后运行 lint。预期不是某一句固定答案，而是命令成功、资料出现在列表中、查询给出可回查的引用、lint 没有结构错误。若资料变更，重新编译前先提交或备份 wiki；手改生成页可能在重编译时被覆盖。

路径二：源码审读或本地网页界面

git clone https://github.com/VectifyAI/OpenKB.git
cd OpenKB
git checkout v0.4.5
python -m pip install -e .

# 需要网页界面时，改用：
python -m pip install "openkb[web]==0.4.5"
openkb-web

源码安装适合审计转换器、固定补丁或开发插件。网页界面默认地址是 http://127.0.0.1:7566，本地认证默认关闭。不要为了远程访问直接改成公网监听；先设置 OPENKB_API_TOKEN，再由带 TLS 的反向代理限制来源。Skill 路径也要区分读写权限：项目附带的 OpenKB skill 按官方说明是只读的，不会自行执行 add、remove 或 lint --fix；只有你明确要求时，Agent 才应更改知识库。

导入失败、结果不准时怎么查

第一类错误是 Python 或依赖不匹配。先运行 python --version 和 python -m pip show openkb openai；v0.4.5 是一次兼容性热修复，官方固定了 openai==2.44.0，不要随手解除约束。第二类是模型配置：检查 .openkb/config.yaml 的 provider/model 与 .env 的密钥是否属于同一家服务。第三类是长 PDF 解析：先用一份短文本验证模型链路，再检查本地 PageIndex；若改用云端，确认 API key、上传许可和敏感资料政策。删除资料前用 openkb remove <doc> --dry-run 查看会清理哪些 Wiki 页、图片和索引状态。

升级、回滚和结果验证

cp -R .openkb .openkb.backup
cp -R wiki wiki.backup
python -m pip install --upgrade "openkb==0.4.5"
openkb status
openkb list
openkb lint

升级后用同一组问题复测：一个直接事实、一个跨文档关系、一个应回答“不知道”的问题。记录引用是否仍指向原资料，避免只看文字是否流畅。Skill Factory 生成内容后运行 openkb skill validate NAME 和 openkb skill eval NAME --save，保留 history；效果退化时再 rollback，而不是覆盖旧结果。这里能验证命令和文件结构，不能替你证明召回率、答案正确率或云端合规。

与 LlamaIndex 的实际区别

LlamaIndex 是面向开发者的数据与 Agent 框架，提供连接器、索引、检索器和工作流，适合把检索能力嵌进应用。OpenKB 的产品边界更窄：把资料编译成可直接浏览和版本控制的 Wiki，并围绕它提供 query、chat、skill 和 deck。需要自定义检索管线、服务端集成或复杂应用时，LlamaIndex 的扩展面更大；想得到一套可审阅的 Markdown 知识库、长期维护引用和生成 Skill 时，OpenKB 路径更短。两者都需要用真实资料评测，不能用“无向量”三个字直接推断准确率更高。

常见问题