feat:为 LPMM 流水线脚本添加非交互模式
为 info_extraction.py、import_openie.py、delete_lpmm_items.py 以及新增的 lpmm_manager.py 引入统一的 --non-interactive 参数，使其能够在 CI 和自动化场景下实现完全脚本化、无交互运行。新增了一个功能完整的命令行管理脚本（lpmm_manager.py）以及一份详细的用户指南（lpmm_pipelines_guide.md）。同时，更新了 test_lpmm_retrieval.py，以支持通过 CLI 自定义测试用例，并改进了整个流水线中的错误处理和用户提示。最后，从文档和代码中移除了 ppr_relation_cap 参数。
This commit is contained in:
陈曦
@@ -76,7 +76,6 @@ embedding_chunk_size = 16 # 每批嵌入的条数
|
||||
info_extraction_workers = 3 # 实体抽取同时执行线程数
|
||||
enable_ppr = true # 是否启用PPR，低配机器可关闭
|
||||
ppr_node_cap = 8000 # 图节点数超过该值时自动跳过PPR
|
||||
ppr_relation_cap = 50 # 命中关系数超过该值时自动跳过PPR
|
||||
```
|
||||
|
||||
- `embedding_dimension`
|
||||
@@ -97,13 +96,13 @@ ppr_relation_cap = 50 # 命中关系数超过该值时自动跳过PPR
|
||||
- 使用 Pro/贵价模型时建议不要太大，避免并行费用过高；
|
||||
- 一般 2–4 就能取得较好平衡。
|
||||
|
||||
- `enable_ppr`
|
||||
- `enable_ppr`
|
||||
是否启用个性化 PageRank（PPR）图检索：
|
||||
- `true`：检索会结合向量+知识图，效果更好，但略慢；
|
||||
- `false`：只用向量检索，牺牲一定效果，性能更稳定。
|
||||
|
||||
- `ppr_node_cap` / `ppr_relation_cap`
|
||||
安全阈值：当图节点数或命中关系数超过阈值时自动跳过 PPR，以避免“大图”导致卡顿。
|
||||
- `ppr_node_cap`
|
||||
安全阈值：当图节点数超过阈值时自动跳过 PPR，以避免“大图”导致卡顿。
|
||||
|
||||
> 调参建议：
|
||||
> - 若导入/检索阶段机器明显“顶不住”（>=1MB的大文本，且分配配置<4C），优先调低：
|
||||
|
||||
326
docs-src/lpmm_pipelines_guide.md
Normal file
326
docs-src/lpmm_pipelines_guide.md
Normal file
@@ -0,0 +1,326 @@
|
||||
## LPMM 知识库流水线使用指南（命令行版）
|
||||
|
||||
本文档介绍如何使用 `scripts/lpmm_manager.py` 及相关子脚本，完成 **导入 / 删除 / 自检 / 刷新 / 回归测试** 等常见流水线操作，并说明各参数在交互式与非交互（脚本化）场景下的用法。
|
||||
|
||||
所有命令均假设在项目根目录 `MaiBot/` 下执行：
|
||||
|
||||
```bash
|
||||
cd MaiBot
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 1. 管理脚本总览：`scripts/lpmm_manager.py`
|
||||
|
||||
### 1.1 基本用法
|
||||
|
||||
```bash
|
||||
python scripts/lpmm_manager.py [--interactive] [-a ACTION] [--non-interactive] [-- ...子脚本参数...]
|
||||
```
|
||||
|
||||
- `--interactive` / `-i`：进入交互式菜单模式（推荐人工运维时使用）。
|
||||
- `--action` / `-a`：直接执行指定操作（非交互入口），可选值：
|
||||
- `prepare_raw`：预处理 `data/lpmm_raw_data/*.txt`。
|
||||
- `info_extract`：信息抽取，生成 OpenIE JSON 批次。
|
||||
- `import_openie`：导入 OpenIE 批次到向量库与知识图。
|
||||
- `delete`：删除/回滚知识（封装 `delete_lpmm_items.py`）。
|
||||
- `batch_inspect`：检查指定 OpenIE 批次的存在情况。
|
||||
- `global_inspect`：全库状态统计。
|
||||
- `refresh`：刷新 LPMM 磁盘数据到内存。
|
||||
- `test`：检索效果回归测试。
|
||||
- `full_import`：一键执行「预处理原始语料 → 信息抽取 → 导入 → 刷新」。
|
||||
- `--non-interactive`：
|
||||
- 启用 **非交互模式**：`lpmm_manager` 自身不会再调用 `input()` 询问确认；
|
||||
- 同时自动向子脚本透传 `--non-interactive`（若子脚本支持），用于在 CI / 定时任务中实现无人值守。
|
||||
- `--` 之后的内容会原样传递给对应子脚本的 `main()`，用于设置更细粒度参数。
|
||||
|
||||
> 注意：`--interactive` 与 `--non-interactive` 互斥，不能同时使用。
|
||||
|
||||
---
|
||||
|
||||
## 2. 典型流水线一：全量导入（从原始 txt 到可用 LPMM）
|
||||
|
||||
### 2.1 前置条件
|
||||
|
||||
- 将待导入的原始文本放入：
|
||||
|
||||
```text
|
||||
data/lpmm_raw_data/*.txt
|
||||
```
|
||||
|
||||
- 文本按「空行分段」，每个段落为一条候选知识。
|
||||
|
||||
### 2.2 一键全流程（交互式）
|
||||
|
||||
```bash
|
||||
python scripts/lpmm_manager.py --interactive
|
||||
```
|
||||
|
||||
菜单中依次：
|
||||
|
||||
1. 选择 `9. full_import`（预处理 → 信息抽取 → 导入 → 刷新）。
|
||||
2. 按提示确认可能的费用与时间消耗。
|
||||
3. 等待脚本执行完成。
|
||||
|
||||
### 2.3 一键全流程（非交互 / CI 友好）
|
||||
|
||||
```bash
|
||||
python scripts/lpmm_manager.py -a full_import --non-interactive
|
||||
```
|
||||
|
||||
执行顺序：
|
||||
|
||||
1. `prepare_raw`：调用 `raw_data_preprocessor.load_raw_data()`，统计段落与去重哈希数。
|
||||
2. `info_extract`：调用 `info_extraction.main(--non-interactive)`，从 `data/lpmm_raw_data` 读取段落，生成 OpenIE JSON 并写入 `data/openie/`。
|
||||
3. `import_openie`：调用 `import_openie.main(--non-interactive)`，导入 OpenIE 批次到嵌入库与 KG。
|
||||
4. `refresh`：调用 `refresh_lpmm_knowledge.main()`，刷新 LPMM 知识库到内存。
|
||||
|
||||
在 `--non-interactive` 模式下：
|
||||
|
||||
- 若 `data/lpmm_raw_data` 中没有 `.txt` 文件，或 `data/openie` 中没有 `.json` 文件，将直接报错退出，并在日志中说明缺少的目录/文件。
|
||||
- 若 OpenIE 批次中存在非法文段，导入脚本会 **直接报错退出**，不会卡在交互确认上。
|
||||
|
||||
---
|
||||
|
||||
## 3. 典型流水线二：分步导入
|
||||
|
||||
若需要逐步调试或只执行部分步骤，可以分开调用：
|
||||
|
||||
### 3.1 预处理原始语料：`prepare_raw`
|
||||
|
||||
```bash
|
||||
python scripts/lpmm_manager.py -a prepare_raw
|
||||
```
|
||||
|
||||
行为：
|
||||
- 使用 `raw_data_preprocessor.load_raw_data()` 读取 `data/lpmm_raw_data/*.txt`；
|
||||
- 输出段落总数与去重后的哈希数，供人工检查原始数据质量。
|
||||
|
||||
### 3.2 信息抽取：`info_extract`
|
||||
|
||||
#### 交互式（带费用提示）
|
||||
|
||||
```bash
|
||||
python scripts/lpmm_manager.py -a info_extract
|
||||
```
|
||||
|
||||
脚本会：
|
||||
- 打印预计费用/时间提示；
|
||||
- 询问 `确认继续执行？(y/n)`；
|
||||
- 然后开始从 `data/lpmm_raw_data` 中读取段落，调用 LLM 提取实体与三元组，并生成 OpenIE JSON。
|
||||
|
||||
#### 非交互式（无人工确认）
|
||||
|
||||
```bash
|
||||
python scripts/lpmm_manager.py -a info_extract --non-interactive
|
||||
```
|
||||
|
||||
行为差异：
|
||||
- 跳过`确认继续执行`的交互提示，直接开始抽取；
|
||||
- 若 `data/lpmm_raw_data` 下没有 `.txt` 文件，会打印告警并以错误方式退出。
|
||||
|
||||
### 3.3 导入 OpenIE 批次：`import_openie`
|
||||
|
||||
#### 交互式
|
||||
|
||||
```bash
|
||||
python scripts/lpmm_manager.py -a import_openie
|
||||
```
|
||||
|
||||
脚本会：
|
||||
- 提示导入开销与资源占用情况；
|
||||
- 询问是否继续；
|
||||
- 调用 `OpenIE.load()` 加载批次，再将其导入嵌入库与 KG。
|
||||
|
||||
#### 非交互式
|
||||
|
||||
```bash
|
||||
python scripts/lpmm_manager.py -a import_openie --non-interactive
|
||||
```
|
||||
|
||||
- 跳过导入开销确认；
|
||||
- 若数据存在非法文段：
|
||||
- 在交互模式下会询问是否删除这些非法文段并继续；
|
||||
- 在非交互模式下，会直接 `logger.error` 并 `sys.exit(1)`，防止导入不完整数据。
|
||||
|
||||
> 提示：当前 `OpenIE.load()` 仍可能在内部要求你选择具体批次文件，若需完全无交互的导入，可后续扩展为显式指定文件路径。
|
||||
|
||||
### 3.4 刷新 LPMM 知识库：`refresh`
|
||||
|
||||
```bash
|
||||
python scripts/lpmm_manager.py -a refresh
|
||||
# 或
|
||||
python scripts/lpmm_manager.py -a refresh --non-interactive
|
||||
```
|
||||
|
||||
两者行为相同：
|
||||
- 调用 `refresh_lpmm_knowledge.main()`，内部执行 `lpmm_start_up()`；
|
||||
- 日志中输出当前向量与 KG 规模，验证导入是否成功。
|
||||
|
||||
---
|
||||
|
||||
## 4. 典型流水线三：删除 / 回滚
|
||||
|
||||
删除操作通过 `lpmm_manager.py -a delete` 封装 `scripts/delete_lpmm_items.py`。
|
||||
|
||||
### 4.1 交互式删除（推荐人工操作）
|
||||
|
||||
```bash
|
||||
python scripts/lpmm_manager.py --interactive
|
||||
```
|
||||
|
||||
菜单中选择：
|
||||
|
||||
1. `4. delete - 删除/回滚知识`
|
||||
2. 再选择删除方式：
|
||||
- 按哈希文件（`--hash-file`）
|
||||
- 按 OpenIE 批次（`--openie-file`）
|
||||
- 按原始语料 + 段落索引（`--raw-file + --raw-index`）
|
||||
- 按关键字搜索现有段落（`--search-text`）
|
||||
3. 管理脚本会根据你的选择自动拼好常用参数（是否删除实体/关系、是否删除孤立实体、是否 dry-run、是否自动确认等），最后调用 `delete_lpmm_items.py` 执行。
|
||||
|
||||
### 4.2 非交互删除（CI / 脚本场景）
|
||||
|
||||
#### 示例：按哈希文件删除（带完整保护参数）
|
||||
|
||||
```bash
|
||||
python scripts/lpmm_manager.py -a delete --non-interactive -- \
|
||||
--hash-file data/lpmm_delete_hashes.txt \
|
||||
--delete-entities \
|
||||
--delete-relations \
|
||||
--remove-orphan-entities \
|
||||
--max-delete-nodes 2000 \
|
||||
--yes
|
||||
```
|
||||
|
||||
- `--non-interactive`（manager）：禁止任何 `input()` 询问；
|
||||
- 子脚本 `delete_lpmm_items.py` 中：
|
||||
- `--hash-file`：指定待删段落哈希列表；
|
||||
- `--delete-entities` / `--delete-relations` / `--remove-orphan-entities`：同步清理实体与关系；
|
||||
- `--max-delete-nodes`：单次删除节点数上限，避免误删过大规模；
|
||||
- `--yes`：跳过终极确认，适合已验证的自动流水线。
|
||||
|
||||
#### 按 OpenIE 批次删除（常用于批次回滚）
|
||||
|
||||
```bash
|
||||
python scripts/lpmm_manager.py -a delete --non-interactive -- \
|
||||
--openie-file data/openie/2025-01-01-12-00-openie.json \
|
||||
--delete-entities \
|
||||
--delete-relations \
|
||||
--remove-orphan-entities \
|
||||
--yes
|
||||
```
|
||||
|
||||
### 4.3 非交互模式下的安全限制
|
||||
|
||||
在 `delete_lpmm_items.py` 中：
|
||||
|
||||
- 若使用 `--search-text`，需要用户通过输入序号选择要删条目；
|
||||
- 在 `--non-interactive` 模式下，这一步会直接报错退出，提示改用 `--hash-file / --openie-file / --raw-file` 等纯参数方式。
|
||||
- 若未指定 `--yes`：
|
||||
- 非交互模式下会报错退出，提示「非交互模式且未指定 --yes，出于安全考虑删除操作已被拒绝」。
|
||||
|
||||
---
|
||||
|
||||
## 5. 典型流水线四：自检与状态检查
|
||||
|
||||
### 5.1 检查指定 OpenIE 批次状态：`batch_inspect`
|
||||
|
||||
```bash
|
||||
python scripts/lpmm_manager.py -a batch_inspect -- --openie-file data/openie/xx.json
|
||||
```
|
||||
|
||||
输出该批次在当前库中的：
|
||||
- 段落向量数量 / KG 段落节点数量；
|
||||
- 实体向量数量 / KG 实体节点数量；
|
||||
- 关系向量数量；
|
||||
- 少量仍存在的样例内容。
|
||||
|
||||
常用于：
|
||||
- 导入后确认是否完全成功；
|
||||
- 删除后确认是否完全回滚。
|
||||
|
||||
### 5.2 查看整库状态：`global_inspect`
|
||||
|
||||
```bash
|
||||
python scripts/lpmm_manager.py -a global_inspect
|
||||
```
|
||||
|
||||
输出：
|
||||
- 段落 / 实体 / 关系向量条数；
|
||||
- KG 节点/边总数，段落节点数、实体节点数；
|
||||
- 实体计数表 `ent_appear_cnt` 的条目数；
|
||||
- 少量剩余段落/实体样例，便于快速 sanity check。
|
||||
|
||||
---
|
||||
|
||||
## 6. 典型流水线五：检索效果回归测试
|
||||
|
||||
### 6.1 使用默认测试用例
|
||||
|
||||
```bash
|
||||
python scripts/lpmm_manager.py -a test
|
||||
```
|
||||
|
||||
- 调用 `test_lpmm_retrieval.py` 内置的 `DEFAULT_TEST_CASES`；
|
||||
- 对每条用例输出：
|
||||
- 原始结果；
|
||||
- 状态（`PASS` / `WARN` / `NO_HIT` / `ERROR`）；
|
||||
- 期望关键字与命中关键字列表。
|
||||
|
||||
### 6.2 自定义测试问题与期望关键字
|
||||
|
||||
```bash
|
||||
python scripts/lpmm_manager.py -a test -- --query "LPMM 是什么？" \
|
||||
--expect-keyword 哈希列表 \
|
||||
--expect-keyword 删除脚本
|
||||
```
|
||||
|
||||
也可以直接调用子脚本：
|
||||
|
||||
```bash
|
||||
python scripts/test_lpmm_retrieval.py \
|
||||
--query "LPMM 是什么？" \
|
||||
--expect-keyword 哈希列表 \
|
||||
--expect-keyword 删除脚本
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. 推荐组合示例
|
||||
|
||||
### 7.1 导入 + 刷新 + 简单回归
|
||||
|
||||
```bash
|
||||
# 1. 执行全量导入（支持非交互）
|
||||
python scripts/lpmm_manager.py -a full_import --non-interactive
|
||||
|
||||
# 2. 使用内置用例做一次检索回归
|
||||
python scripts/lpmm_manager.py -a test
|
||||
```
|
||||
|
||||
### 7.2 批次回滚 + 自检
|
||||
|
||||
```bash
|
||||
TARGET_BATCH=data/openie/2025-01-01-12-00-openie.json
|
||||
|
||||
# 1. 按批次删除（非交互）
|
||||
python scripts/lpmm_manager.py -a delete --non-interactive -- \
|
||||
--openie-file "$TARGET_BATCH" \
|
||||
--delete-entities \
|
||||
--delete-relations \
|
||||
--remove-orphan-entities \
|
||||
--yes
|
||||
|
||||
# 2. 检查该批次是否彻底删除
|
||||
python scripts/lpmm_manager.py -a batch_inspect -- --openie-file "$TARGET_BATCH"
|
||||
|
||||
# 3. 查看全库状态
|
||||
python scripts/lpmm_manager.py -a global_inspect
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
如需扩展更多流水线（例如「导入特定批次后自动跑自定义测试用例」），可以在 `scripts/lpmm_manager.py` 中新增对应的 `ACTION_INFO` 条目和 `run_action` 分支，或直接在 CI / shell 脚本中串联上述命令。该管理脚本已支持参数化与非交互调用，适合作为二次封装的基础入口。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user