为 KiraAI 量身打造的知识库插件 —— 让数字生命们拥有长期记忆的多版本共存可检索与实时操作的知识库
- 多版本管理：支持为同一知识库创建不同嵌入模型（如 BGE-M3、OpenAI）的版本，随时切换，对比效果，无需重复上传文档。
- 智能检索：混合检索（向量 + BM25）结合重排序（可选），精准召回用户所需信息。
- 文档全生命周期：支持上传、编辑、软删除、恢复文档，所有操作均可通过 WebUI 或聊天工具（AI 自动调用）完成。
- OCR 支持：利用 KiraAI 的默认多模态（视觉）模型，自动识别扫描版 PDF 中的文字。
- 后台任务：创建版本、批量向量化等耗时操作在后台运行，WebUI 实时显示进度，不阻塞主程序。
- 权限控制：通过提示词约定，只有主人可以删除/修改知识条目，普通用户只能新增（AI 会判断信息是否有价值）。
- 零配置启动：插件自动使用 KiraAI 主系统中配置的默认嵌入模型和视觉模型，可无需重复配置。
向量模型（嵌入模型）是将文字转化为数字向量的工具，不同的模型输出的向量维度（例如 384 维、768 维、1024 维）和语义空间都不一样。如果直接更换模型，之前用旧模型生成的向量索引将无法被新模型检索——要么维度不匹配导致程序崩溃，要么检索结果完全随机。
KiraKB 的解决方案：
为同一个知识库保留多个独立版本，每个版本记录当时使用的模型名称、维度和创建时间。你可以：
- 随时在版本间切换，不影响其他版本的数据。
- 用新模型增量创建版本（只处理新增文档），无需重建整个知识库。
- 对比不同模型的检索效果，选择最适合当前场景的版本激活。
这样一来，更换模型不再是“推倒重来”的噩梦，而是灵活可逆的探索过程。
- 已安装Python 3.10+
- 已部署并成功运行 KiraAI
- KiraAI 主系统中已配置至少一个嵌入模型（作为
default_embedding） - （可选）如需 OCR 功能，需配置视觉模型（作为
default_vlm）
-
下载插件压缩包
从发布页下载，解压后得到kirakB文件夹。 -
放置插件
将整个kiraKB文件夹复制到 KiraAI 的插件目录中：KiraAI项目文件夹/data/plugins/ -
安装依赖
进入 KiraAI 的虚拟环境（如果使用），然后执行：pip install -r data/plugins/kiraKB/requirements.txt
-
重启 KiraAI
重启后插件会自动加载。 -
访问管理界面
打开浏览器访问http://127.0.0.1:19122（端口可在插件配置中修改）。
KiraKB/
├── manifest.json # 插件元信息
├── schema.json # 配置定义
├── requirements.txt # Python 依赖
├── main.py # 插件主逻辑（LLM 工具）
├── kb_manager.py # 知识库核心管理（版本、文档、软删除）
├── task_manager.py # 后台任务管理
├── web_server.py # WebUI 服务端
├── document_parser.py # 文档解析（含 OCR）
├── vector_store.py # 向量存储（FAISS + SQLite）
├── chunking.py # 文本分块
├── retriever.py # 混合检索
└── web/
└── index.html # 管理界面前端
插件配置通过 KiraAI 的 WebUI 进行（主界面 → 插件管理 → KiraKB）。主要配置项：
| 配置项 | 说明 | 默认值 |
|---|---|---|
knowledge_base_dir |
知识库存储根目录 | data/knowledge_base |
chunk_size |
文档分块字符数 | 500 |
chunk_overlap |
分块重叠字符数 | 50 |
default_top_k |
默认检索结果数量 | 5 |
enable_hybrid_search |
是否启用 BM25 混合检索 | true |
enable_rerank |
是否启用重排序（需配置重排序模型） | false |
webui_port |
管理界面端口 | 19122 |
webui_token |
访问令牌（留空无认证） | 空 |
💡 嵌入模型和视觉模型无需在插件中配置，直接使用 KiraAI 主系统的
default_embedding和default_vlm。
- 打开 WebUI (
http://127.0.0.1:19122)，点击 + 新建知识库，输入 ID（如kiraai_docs），系统会自动创建目录。
- 支持
.txt、.md文本文件，也可上传 PDF、Word、Excel、PPT（需安装markitdown）。 - 点击“上传”选择文件，文档会被保存为原始文本并自动向量化到当前激活版本。
- 每个知识库需要至少一个版本才能检索。在右侧“版本管理”中点击 + 创建新版本。
- 填写模型名称（例如
BAAI/bge-m3）和维度（例如1024），可选择仅处理部分文档。 - 提交后后台开始向量化，WebUI 底部会显示进度条。完成后点击“激活”即可。
- 在下方“检索测试”区输入问题（如“KiraAI 如何安装插件”），点击检索，查看返回的文档片段。注意：这个搜索依然是调用当前配置的默认嵌入模型，是会花费token的。
- 在 KiraAI 的角色设定中添加以下提示词（示例）：
## 知识库使用规则（KiraKB）
- **检索**：当用户询问 KiraAI 相关问题时，必须调用 `knowledge_search` 工具，格式：`knowledge_search(query="用户问题")`。完整采纳答案，保留链接和步骤。若工具无结果，结合常识、网络搜索回答并调侃：“资料没写，可能……自己查查？”
- **查看列表**：`list_knowledge_bases` 可列出所有知识库。
- **新增**：`knowledge_update_entry(content, title, kb_id)`。仅当信息有价值时调用。主人（QQ号11451415551）可无条件新增。非主人需判断有用性。
- **删改**：`knowledge_delete_entry(title, kb_id)`。**仅主人可执行**。非主人请求删除必须拒绝：“只有主人能删改知识库。”
- **语气**：符合人设，但核心信息完整。之后，AI 就会在对话中自动调用知识库工具和执行你的要求。
- 上传文档：支持多选，自动保存原始文件。
- 编辑文档：点击文档旁的“编辑”按钮，可修改内容，保存后会立即重新向量化到当前激活版本。
- 删除文档：软删除（文档保留，仅从向量索引中移除），可在“显示已删除”中恢复。
- 显示已删除：列出所有软删除的文档，点击“恢复”即可重新向量化。
- 创建新版本：选择模型名称/维度，可指定包含的文档（留空表示全部）。创建过程在后台运行，不影响其他操作。
- 激活版本：点击“激活”使该版本成为检索目标。同一时间只有一个激活版本。
- 删除版本：只能删除非激活版本。删除后不可恢复。
- 实时测试当前激活版本的检索效果。注意：这个搜索依然是调用当前配置的默认嵌入模型，是会花费token的。
- 后台任务（创建版本、批量更新）会显示进度条，可随时查看状态。
| 工具名 | 用途 | 示例 |
|---|---|---|
list_knowledge_bases |
列出所有知识库及当前激活版本 | AI 自动调用以确定目标知识库 |
knowledge_search |
检索知识库 | knowledge_search(query="插件开发指南", kb_id="kiraai_docs") |
knowledge_update_entry |
新增/更新知识条目 | knowledge_update_entry(content="...", title="KiraKB 安装步骤") |
knowledge_delete_entry |
删除知识条目（仅主人） | knowledge_delete_entry(title="旧版本说明") |
注意：
knowledge_update_entry会自动判断标题是否已存在，若存在则覆盖更新；删除是软删除，可在 WebUI 恢复。
data/knowledge_base/
└── kiraai_docs（示例）/ # 知识库 ID
├── raw_docs/ # 原始文档（.txt + .meta.json）
│ ├── abc123.txt
│ └── abc123.meta.json # 含 original_name, deleted 标记等
├── versions/ # 所有版本
│ ├── BAAI_bge-m3_1734567890/
│ │ ├── vectors/ # FAISS 索引 + SQLite 元数据
│ │ ├── model_info.json # 模型名称、维度、创建时间
│ │ └── doc_chunk_map.json
│ └── ...
├── info.json # 知识库显示名称、描述
└── current_version # 当前激活版本 ID
停用词是指在检索时没有实际意义、可以忽略的常用词，例如中文的“的、了、在、是”，英文的“a、an、the、and”。在混合检索的 BM25 关键词匹配阶段，这些词会被自动过滤掉，避免它们干扰相关性评分。
假设用户问：“怎么安装 KiraAI 的插件？”
如果不加停用词，BM25 会计算“怎么”、“安装”、“KiraAI”、“的”、“插件”每个词的权重。“怎么”和“的”几乎出现在所有问句中，会导致无关文档被误判为相关。过滤掉它们后，只保留“安装”、“KiraAI”、“插件”，结果可能更精准——但有的时候，如果你设计知识库就是希望对“怎么办”“为什么”等提问有响应，则不应过滤。
- 位置：
KiraAI/data/stopwords.txt（插件首次启动时会自动创建一个空文件） - 格式：每行一个停用词，支持中文和英文。
- 作用范围：仅影响 BM25 关键词检索部分，不影响向量检索。
你可以手动编辑 data/stopwords.txt，添加你希望过滤的词。例如：
的
了
在
是
啊
哦
a
an
the
and
or
but
如果不添加任何词，停用词功能等同于关闭，不影响检索效果。
💡 停用词不是必须的，如果你发现某些高频词干扰了检索结果，可以尝试添加它们到停用词表。一般默认空文件即可。
可以。旧版本保留在 versions/ 目录，你可以随时激活它。但新上传的文档只会向量化到当前激活版本。如果想用新模型处理所有文档，请创建新版本（选择全部文档）。
- 如果是扫描版 PDF，需要配置视觉模型（
default_vlm）并确保pdf2image已安装（pip install pdf2image）。 - 普通 PDF 无需额外配置，直接提取文字。
- 请先创建版本（右侧“创建新版本”），然后激活它。只有激活版本才能检索。
- 在提示词中明确：只有主人可以删除，普通用户的新增需 AI 判断价值。你可以通过对话告知 AI“这个信息有用，记下来”或“这个不用记”。
- 后台任务支持进度显示，耐心等待。建议创建版本时只选择新增的文档（增量创建），避免全量重建。
- 直接备份
data/knowledge_base/目录即可。恢复时复制到相同位置，重启 KiraAI 会自动加载。
- 不会。数据独立于代码存储。但更新前建议备份
data/knowledge_base/。
本插件基于 AstrBot 知识库思路进行移植和改造，感谢原作者们的贡献。
特别感谢 KiraOS 项目在 WebUI 设计上的启发与思路，它一直是 Kira 系列插件的学习标杆与骄傲。
衷心感谢 KiraAI 开发者 xxynet 让 Kira 项目诞生与持续热情，让数字生命变得可能。
本项目作为 KiraAI 的附属插件，采用 AGPL-3.0 协议开源，允许在协议范围内自由使用、修改和分发。
享受与您的数字生命共享知识的乐趣吧！ 🎉 如果遇到问题，欢迎在 KiraAI QQ交流群874381335讨论，并自行修改。因为本人技术实在太差，还请谅解，祝玩的愉快和让 Kira 变得更聪明~