LPMM 知识库删除能力与自检脚本增强（附关键健壮性修复）

为 LPMM 新增安全可控的删除能力： KGManager.delete_paragraphs 支持按段落/实体哈希删除图节点及关联边，可选清理孤立实体，并从图中重建元数据统一删除脚本 scripts/delete_lpmm_items.py，支持按批次（OpenIE 文件）、哈希文件、原始文本段落、关键字搜索进行删除，内置 dry-run 和最大节点数保护新增自检与回归脚本： scripts/inspect_lpmm_batch.py / scripts/inspect_lpmm_global.py 用于批次级和全局状态检查 scripts/test_lpmm_retrieval.py 一键初始化 LPMM 并用固定问题测试检索效果。健壮性与性能保护：在 KGManager.kg_search 中对 ent_appear_cnt 缺失增加兜底，避免实体权重计算时的 KeyError。增加同义实体数量限制与 PPR 节点/关系阈值，必要时自动退回纯向量检索文档补充： docs-src/lpmm_user_guide.md：面向零基础用户的导入 / 删除 / 自检脚本使用指南 docs-src/lpmm_parameters_guide.md：[lpmm_knowledge] 关键参数说明与简单调参建议
2025-11-27 13:20:12 +08:00
parent fa4555197d
commit 1383caf249
9 changed files with 1376 additions and 5 deletions
--- a/docs-src/lpmm_parameters_guide.md
+++ b/docs-src/lpmm_parameters_guide.md
@@ -0,0 +1,154 @@
+# LPMM 关键参数调节指南（进阶版）
+
+> 本文是对 `config/bot_config.toml` 中 `[lpmm_knowledge]` 段的补充说明。  
+> 如果你只想使用默认配置，可以不改这些参数，脚本仍然可以正常工作。
+
+所有与 LPMM 相关的参数，都集中在：
+
+```toml
+[lpmm_knowledge] # lpmm知识库配置
+enable = true
+lpmm_mode = "agent"
+...
+```
+
+下面按功能将常用参数分为三组介绍。
+
+---
+
+## 一、检索相关参数（影响答案质量与风格）
+
+```toml
+qa_relation_search_top_k = 10      # 关系检索TopK
+qa_relation_threshold    = 0.5     # 关系阈值，相似度高于该值才认为“命中关系”
+qa_paragraph_search_top_k = 1000   # 段落检索TopK，越小可能影响召回
+qa_paragraph_node_weight = 0.05    # 段落节点权重，在图检索&PPR中的权重
+qa_ent_filter_top_k      = 10      # 实体过滤TopK
+qa_ppr_damping           = 0.8     # PPR阻尼系数
+qa_res_top_k             = 3       # 最终提供给问答模型的段落数
+```
+
+- `qa_relation_search_top_k`  
+  控制“最多考虑多少条关系向量候选”。  
+  - 数值大：召回更全面，但略慢；  
+  - 数值小：更快，可能遗漏部分隐含关系。
+
+- `qa_relation_threshold`  
+  关系相似度的阈值：  
+  - 数值高：只信任非常相关的关系，系统更可能退化为纯段落向量检索；  
+  - 数值低：图结构影响更大，适合实体关系较丰富的场景。
+
+- `qa_paragraph_search_top_k`  
+  控制“最多考虑多少段落候选”。  
+  - 太小：可能召回不全，导致答案缺失；  
+  - 太大：略微增加计算量，一般 1000 为安全默认。
+
+- `qa_paragraph_node_weight`  
+  文段节点在图检索中的权重：  
+  - 数值大：更依赖段落向量相似度（传统向量检索）；  
+  - 数值小：更依赖图结构和实体网络。
+
+- `qa_ppr_damping`  
+  Personalized PageRank 的阻尼系数：  
+  - 通常保持在 0.8 左右即可；  
+  - 越接近 1：偏向长路径探索，结果更发散；  
+  - 略低：更集中在与问题直接相关的节点附近。
+
+- `qa_res_top_k`  
+  LPMM 最终会把相关度最高的前 `qa_res_top_k` 条段落组合成“知识上下文”给问答模型。  
+  - 太多：增加模型负担、阅读更多文字；  
+  - 太少：信息不够充分，一般 3–5 比较平衡。
+
+> 调参建议：  
+> - 优先在 `qa_relation_threshold`、`qa_paragraph_node_weight` 上做小幅调整；  
+> - 每次调整后，用 `scripts/test_lpmm_retrieval.py` 跑一遍固定问题，感受回答变化。
+
+---
+
+## 二、性能与硬件相关参数
+
+```toml
+embedding_dimension   = 1024  # 嵌入向量维度,应与模型输出维度一致
+max_embedding_workers = 12    # 嵌入/抽取并发线程数
+embedding_chunk_size  = 16    # 每批嵌入的条数
+info_extraction_workers = 3   # 实体抽取同时执行线程数
+enable_ppr            = true  # 是否启用PPR，低配机器可关闭
+ppr_node_cap          = 8000  # 图节点数超过该值时自动跳过PPR
+ppr_relation_cap      = 50    # 命中关系数超过该值时自动跳过PPR
+```
+
+- `embedding_dimension`  
+  必须与所选嵌入模型的输出维度一致（比如 768、1024 等）。**不要随意修改，除非你知道你在做什么！！！**
+
+- `max_embedding_workers`  
+  决定导入/抽取阶段的并行线程数：  
+  - 机器配置好：可以适当调大，加快导入速度；  
+  - 机器配置弱：建议调低（如 2 或 4），避免 CPU 长时间 100%。
+
+- `embedding_chunk_size`  
+  每批发送给嵌入 API 的段落数量：  
+  - 数值大：请求次数少，但单次请求更“重”；  
+  - 数值小：请求次数多，但对网络和 API 的单次压力小。
+
+- `info_extraction_workers`  
+  `scripts/info_extraction.py` 中实体抽取的并行线程数：  
+  - 使用 Pro/贵价模型时建议不要太大，避免并行费用过高；
+  - 一般 2–4 就能取得较好平衡。
+
+- `enable_ppr`  
+  是否启用个性化 PageRank（PPR）图检索：  
+  - `true`：检索会结合向量+知识图，效果更好，但略慢；  
+  - `false`：只用向量检索，牺牲一定效果，性能更稳定。
+
+- `ppr_node_cap` / `ppr_relation_cap`  
+  安全阈值：当图节点数或命中关系数超过阈值时自动跳过 PPR，以避免“大图”导致卡顿。
+
+> 调参建议：  
+> - 若导入/检索阶段机器明显“顶不住”（>=1MB的大文本，且分配配置<4C），优先调低：  
+>   - `max_embedding_workers`  
+>   - `embedding_chunk_size`  
+>   - `info_extraction_workers`  
+>   - 或暂时将 `enable_ppr = false`  （除非真的出现问题，否则不建议禁用此项，大幅影响检索效果）
+> - 调整后重新执行导入或检索，观察日志与系统资源占用。
+
+---
+
+## 三、开启/关闭 LPMM 与模式说明
+
+```toml
+enable    = true       # 是否开启lpmm知识库
+lpmm_mode = "agent"    # 可选 classic / agent
+```
+
+- `enable`  
+  - `true`：LPMM 知识库启用，检索和问答会使用知识库；  
+  - `false`：LPMM 完全关闭，脚本仍可导入/删除数据，但对聊天问答不生效。
+
+- `lpmm_mode`  
+  - `classic`：传统模式，仅使用 LPMM 知识库本身；  
+  - `agent`：与新的记忆系统联动，用于更复杂的记忆+知识混合场景。
+
+> 修改 `enable` 或 `lpmm_mode` 后，需要重启主程序，让配置生效。
+
+---
+
+## 四、推荐的调参流程
+
+1. **保持默认配置，先跑一轮完整流程**
+   - 导入 → `inspect_lpmm_global.py` → `test_lpmm_retrieval.py`；
+   - 记录当前“答案风格”和“响应速度”。
+
+2. **每次只调整一到两个参数**
+   - 例如先调 `qa_relation_threshold`、`qa_paragraph_node_weight`；  
+   - 或在性能不佳时调整 `max_embedding_workers`、`enable_ppr`。
+
+3. **调整后重复同一组测试问题**
+   - 使用 `scripts/test_lpmm_retrieval.py`；  
+   - 对比不同配置下的答案，选择更符合需求的组合。
+
+4. **出现“怎么调都不对”时**
+   - 将 `[lpmm_knowledge]` 段恢复为仓库中的默认配置；  
+   - 重启主程序，即可回到“出厂设置”。
+
+通过本指南中的参数调节，你可以在“检索质量”“响应速度”“系统资源占用”之间找到适合自己麦麦和机器的平衡点！
+
--- a/docs-src/lpmm_user_guide.md
+++ b/docs-src/lpmm_user_guide.md
@@ -0,0 +1,395 @@
+# LPMM 知识库脚本使用指南（零基础用户版）
+
+本指南面向不熟悉命令行和代码的 C 端用户，帮助你完成：
+
+- LPMM 知识库的初始部署（从本地 txt 到可检索知识库）
+- 安全删除知识（按批次、按原文、按哈希、按关键字）
+- 导入 / 删除后的自检与检索效果验证
+
+> 说明：本文默认你已经完成 MaiBot 的基础安装，并能在项目根目录打开命令行终端。
+
+---
+
+## 一、需要用到的脚本一览
+
+在项目根目录（`MaiBot-dev`）下，这些脚本是 LPMM 相关的“工具箱”：
+
+- 导入相关：
+  - `scripts/raw_data_preprocessor.py`  
+    从 `data/lpmm_raw_data` 目录读取 `.txt` 文件，按空行拆分为一个个段落，并做去重。
+  - `scripts/info_extraction.py`  
+    调用大模型，从每个段落里抽取实体和三元组，生成中间的 OpenIE JSON 文件。
+  - `scripts/import_openie.py`  
+    把 `data/openie` 目录中的 OpenIE JSON 文件导入到 LPMM 知识库（向量库 + 知识图）。
+
+- 删除相关：
+  - `scripts/delete_lpmm_items.py`  
+    LPMM 知识库删除入口，支持按批次、按原始文本段落、按哈希列表、按关键字模糊搜索删除。
+
+- 自检相关：
+  - `scripts/inspect_lpmm_global.py`  
+    查看整个知识库的当前状态：段落/实体/关系条数、知识图节点/边数量、示例内容等。
+  - `scripts/inspect_lpmm_batch.py`  
+    针对某个 OpenIE JSON 批次，检查它在向量库和知识图中的“残留情况”（导入与删除前后对比）。
+  - `scripts/test_lpmm_retrieval.py`  
+    使用几条预设问题测试 LPMM 检索能力，帮助你判断知识库是否正常工作。
+
+> 注意：所有命令示例都假设你已经在虚拟环境中，命令行前缀类似 `(.venv)`，并且当前目录是项目根目录。
+
+---
+
+## 二、LPMM 知识库的初始部署
+
+### 2.1 准备原始 txt 文本
+
+1. 把要导入的知识文档放到：
+
+   ```text
+   data/lpmm_raw_data
+   ```
+
+2. 文件要求：
+
+   - 必须是 `.txt` 文件，建议使用 UTF-8 编码；
+   - 用**空行**分隔段落：一段话后空一行，即视为一条独立知识。
+
+示例文件：
+
+- `data/lpmm_raw_data/lpmm_large_sample.txt`：仓库内已经提供了一份大样本测试文本，可以直接用来练习。
+
+### 2.2 第一步：预处理原始文本（拆段 + 去重）
+
+在项目根目录执行：
+
+```bash
+.\.venv\Scripts\python.exe scripts/raw_data_preprocessor.py
+```
+
+成功时通常会看到日志类似：
+
+- 正在处理文件: `lpmm_large_sample.txt`
+- 共读取到 XX 条数据
+
+这一步不会调用大模型，仅做拆段和去重。
+
+### 2.3 第二步：进行信息抽取（生成 OpenIE JSON）
+
+执行：
+
+```bash
+.\.venv\Scripts\python.exe scripts/info_extraction.py
+```
+
+你会看到一个“重要操作确认”提示，说明：
+
+- 信息抽取会调用大模型，消耗 API 费用和时间；
+- 如果确认无误，输入 `y` 回车继续。
+
+提取过程中可能出现：
+
+- 类似“模型 ... 网络错误(可重试)”这样的日志；  
+  这表示脚本在遇到网络问题时自动重试，一般无需手动干预。
+
+运行结束后，会有类似提示：
+
+```text
+信息提取结果已保存到: data/openie/11-27-10-06-openie.json
+```
+
+- 请记住这个文件名，比如：`11-27-10-06-openie.json`  
+  接下来我们会用 `<OPENIE>` 来代指这类文件。
+
+### 2.4 第三步：导入 OpenIE 数据到 LPMM 知识库
+
+执行：
+
+```bash
+.\.venv\Scripts\python.exe scripts/import_openie.py
+```
+
+这个脚本会：
+
+- 从 `data/openie` 目录读取所有 `*.json` 文件，并合并导入；
+- 将新段落的嵌入向量写入 `data/embedding`；
+- 将三元组构建为知识图写入 `data/rag`。
+
+> 提示：如果你希望“只导入某几批数据”，可以暂时把不需要的 JSON 文件移出 `data/openie`，导入结束后再移回。
+
+### 2.5 第四步：全局自检（确认导入成功）
+
+执行：
+
+```bash
+.\.venv\Scripts\python.exe scripts/inspect_lpmm_global.py
+```
+
+你会看到类似输出：
+
+- 段落向量条数: `52`
+- 实体向量条数: `260`
+- 关系向量条数: `299`
+- KG 节点总数 / 边总数 / 段落节点数 / 实体节点数
+- 若干条示例段落与实体内容预览
+
+只要这些数字大于 0，就表示 LPMM 知识库已经有可用的数据了。
+
+### 2.6 第五步：用脚本测试 LPMM 检索效果（可选但推荐）
+
+执行：
+
+```bash
+.\.venv\Scripts\python.exe scripts/test_lpmm_retrieval.py
+```
+
+脚本会：
+
+- 自动初始化 LPMM（加载向量库与知识图）；
+- 用几条预设问题查询 LPMM；
+- 打印原始检索结果和关键词命中情况。
+
+你可以通过观察“RAW RESULT”里的内容，粗略判断：
+
+- 能否命中与问题高度相关的知识；
+- 删除或导入新知识后，回答内容是否发生变化。
+
+---
+
+## 三、安全删除知识的几种方式
+
+> 强烈建议：删除前先备份以下目录，以便“回档”：
+>
+> - `data/embedding`（向量库）
+> - `data/rag`（知识图）
+
+所有删除操作使用同一个脚本：
+
+```bash
+.\.venv\Scripts\python.exe scripts/delete_lpmm_items.py [参数...]
+```
+
+脚本特点：
+
+- 删除前会打印“待删除段落数量 / 实体数量 / 关系数量 / 预计删除节点数”等摘要；
+- 需要你输入大写 `YES` 确认才会真正执行；
+- 支持多种删除策略，可灵活组合。
+
+### 3.1 按批次删除（推荐：整批回滚）
+
+适用场景：某次导入的整批知识有问题，希望整体回滚。
+
+1. 删除前，先检查该批次状态：
+
+   ```bash
+   .\.venv\Scripts\python.exe scripts/inspect_lpmm_batch.py ^
+     --openie-file data/openie/<OPENIE>.json
+   ```
+
+   你会看到该批次：
+
+   - 段落：总计多少条、向量库剩余多少、KG 中剩余多少；
+   - 实体、关系的类似统计；
+   - 少量示例段落/实体内容预览。
+
+2. 确认无误后，按批次删除：
+
+   ```bash
+   .\.venv\Scripts\python.exe scripts/delete_lpmm_items.py ^
+     --openie-file data/openie/<OPENIE>.json ^
+     --delete-entities --delete-relations --remove-orphan-entities
+   ```
+
+   参数含义：
+
+   - `--delete-entities`：删除该批次涉及的实体向量；
+   - `--delete-relations`：删除该批次涉及的关系向量；
+   - `--remove-orphan-entities`：顺带清理删除后不再参与任何边的“孤立实体”节点。
+
+3. 删除后再检查：
+
+   ```bash
+   .\.venv\Scripts\python.exe scripts/inspect_lpmm_batch.py ^
+     --openie-file data/openie/<OPENIE>.json
+
+   .\.venv\Scripts\python.exe scripts/inspect_lpmm_global.py
+   ```
+
+   若批次检查显示“向量库剩余 0 / KG 中剩余 0”，则说明该批次已被彻底删除。
+
+### 3.2 按原始文本段落删除（精确定位某一段）
+
+适用场景：某个原始 txt 的特定段落写错了，只想删这段对应的知识。
+
+命令示例：
+
+```bash
+.\.venv\Scripts\python.exe scripts/delete_lpmm_items.py ^
+  --raw-file data/lpmm_raw_data/lpmm_large_sample.txt ^
+  --raw-index 2
+```
+
+说明：
+
+- `--raw-index` 从 1 开始计数，可用逗号多选，例如：`1,3,5`；
+- 脚本会展示该段落的内容预览和哈希值，再请求你确认。
+
+### 3.3 按哈希列表删除（进阶用法）
+
+适用场景：你有一份“需要删除的段落哈希列表”（比如从其他系统导出）。
+
+示例哈希列表文件：
+
+- `data/openie/lpmm_delete_test_hashes.txt`
+
+命令：
+
+```bash
+.\.venv\Scripts\python.exe scripts/delete_lpmm_items.py ^
+  --hash-file data/openie/lpmm_delete_test_hashes.txt
+```
+
+说明：
+
+- 文件中每行一条，可以是 `paragraph-xxxx` 或纯哈希，脚本会自动识别；
+- 适合“精确控制删除哪些段落”，但准备哈希列表需要一定技术基础。
+
+### 3.4 按关键字模糊搜索删除（对非技术用户最友好）
+
+适用场景：只知道某段话里包含某个关键词，不知道它在哪个 txt 或批次里。
+
+示例 1：删除与“近义词扩展”相关的段落
+
+```bash
+.\.venv\Scripts\python.exe scripts/delete_lpmm_items.py   --search-text "近义词扩展"   --search-limit 5
+```
+
+示例 2：删除与“LPMM”强相关的一些段落
+
+```bash
+.\.venv\Scripts\python.exe scripts/delete_lpmm_items.py   --search-text "LPMM"   --search-limit 20
+
+```
+
+执行过程：
+
+1. 脚本在当前段落库中查找包含该关键字的段落；
+2. 列出前 N 条候选（`--search-limit` 决定数量）；
+3. 提示你输入要删除的序号列表，例如：`1,2,5`；
+4. 再次提示你输入 `YES` 确认，才会真正执行删除。
+
+> 建议：
+>
+> - 第一次使用时可以先加 `--dry-run` 看看效果：
+>   ```bash
+>   .\.venv\Scripts\python.exe scripts/delete_lpmm_items.py ^
+>     --search-text "LPMM" ^
+>     --search-limit 20 ^
+>     --dry-run
+>   ```
+> - 确认候选列表确实是你要删的内容后，再去掉 `--dry-run` 正式执行。
+
+---
+
+## 四、自检：如何确认导入 / 删除是否“生效”
+
+### 4.1 全局状态检查
+
+每次导入或删除之后，建议跑一次：
+
+```bash
+.\.venv\Scripts\python.exe scripts/inspect_lpmm_global.py
+```
+
+你可以在这里看到：
+
+- 段落向量条数、实体向量条数、关系向量条数；
+- 知识图的节点总数、边总数、段落节点和实体节点数量；
+- 若干条“剩余段落示例”和“剩余实体示例”。
+
+观察方式：
+
+- 导入后：数字应该明显上升（说明新增数据生效）；
+- 删除后：数字应该明显下降（说明删除操作生效）。
+
+### 4.2 某个批次的局部状态
+
+如果你想确认“某一个 OpenIE 文件对应的那一批知识”是否存在，可以使用：
+
+```bash
+.\.venv\Scripts\python.exe scripts/inspect_lpmm_batch.py   --openie-file data/openie/<OPENIE>.json
+```
+
+输出中会包含：
+
+- 该批次的段落 / 实体 / 关系的总数；
+- 在向量库中还剩多少条，在 KG 中还剩多少条；
+- 若干条仍存在的段落/实体示例。
+
+典型用法：
+
+- 导入后立刻检查一次：确认这一批已经“写入”；
+- 删除后再检查一次：确认这一批是否已经“清空”。
+
+### 4.3 检索效果回归测试
+
+每次做完导入或删除，你都可以用这条命令快速验证检索效果：
+
+```bash
+.\.venv\Scripts\python.exe scripts/test_lpmm_retrieval.py
+```
+
+它会：
+
+- 初始化 LPMM（加载当前向量库和知识图）；
+- 用几条预设问题（包括与 LPMM 和配置相关的问题）进行检索；
+- 打印检索结果以及命中关键词情况。
+
+通过对比不同时间点的输出，你可以判断：
+
+- 某些知识是否已经被成功删除（不再出现在回答中）；
+- 新增的知识是否已经能被检索到。
+
+---
+
+## 五、常见提示与注意事项
+
+1. **看到“网络错误(可重试)”需要担心吗？**
+
+   - 不需要。  
+   - 这些日志说明脚本在自动处理网络抖动，多数情况下会在重试后成功返回结果。
+   - 只要脚本最后没有报“重试耗尽并退出”，一般导入/提取结果是有效的。
+
+2. **删除操作会不会“一删全没”？**
+
+   - 不会直接“一删全没”：
+     - 每次删除会打印摘要信息；
+     - 必须输入 `YES` 才会真正执行；
+     - 大批次时还有 `--max-delete-nodes` 保护，超过阈值会警告。
+   - 但仍然建议：
+     - 在大规模删除前备份 `data/embedding` 和 `data/rag`；
+     - 先通过 `--dry-run` 看看待删列表。
+
+3. **可以多次导入吗？需要先清空吗？**
+
+   - 可以多次导入，系统会根据段落内容的哈希做去重；
+   - 不需要每次都清空，只要你希望老数据仍然保留即可；
+   - 如果你确实想“重来一遍”，可以：
+     - 先备份，然后删除 `data/embedding` 和 `data/rag`；
+     - 再重新跑导入流程。
+
+4. **LPMM 开关在哪里？**
+
+   - 配置文件：`config/bot_config.toml`；
+   - 小节：`[lpmm_knowledge]`；
+   - 其中有 `enable = true/false` 开关：
+     - 为 `true`：LPMM 知识库启用，问答时会使用；
+     - 为 `false`：LPMM 关闭，即使知识库有数据，也不会参与回答。
+   - 修改后需要重启主程序，让设置生效。
+
+---
+
+如果你是普通用户，只需要记住一句话：
+
+> “导入三步走：预处理 → 信息抽取 → 导入 OpenIE；  
+> 删除三步走：先检查 → 再删除 → 然后再检查。”
+
+照着本指南中的命令一步一步执行，就可以安全地管理你的 LPMM 知识库。***