NIM 知识库批量导入

使用流水线处理历史客服聊天导出：预切分 → 批量提取 → 批量入库 → 推送。

临时文件说明

客户处理过程中的临时文件说明：

路径	说明
customers/{客户名}.txt	Phase A 拆分结果，Phase B 读取
extracts/{客户名}.json	Phase B 提取结果，Phase C 读取
progress.json	各阶段进度状态，由脚本维护
extractsHistory/	清理前的归档备份，不参与流程

首次使用检查（仅需配置一次）

该仓库为公开仓库，拉取（clone/pull）无需认证。但批量录入后需要 push 写入，须提前配置：

# 配置凭证缓存，避免每次 push 输入密码
git config --global credential.helper store

首次 push 时按提示输入 GitHub 用户名和 Personal Access Token（不能用密码），之后自动免密。

Personal Access Token 获取：登录 github.com → 右上角头像 → Settings → Developer settings → Personal access tokens → Tokens (classic) → Generate new token，勾选 repo 权限。

知识库远程地址：https://github.com/19967431260/rags.git

---

工作流程

阶段 A - 预切分

⚠️ 必须运行脚本，禁止自行实现

python /scripts/phase_a_split.py path/to/export.xlsx

输出示例：

✅ 切分完成：共 247 个客户
   文件：/tem/nim-kb-batch/customers/
   进度：/tem/nim-kb-batch/progress.json

阶段 B - 批量提取（使用子代理）

子代理批量处理

告诉 AI："启动子代理批量提取，每批 10 个客户"

子代理任务（每个子代理独立执行以下流程）：

# B-1 原子领取 10 个客户（文件锁保护，并发安全，自动标记为 in_progress）
python /scripts/phase_b_status.py claim 10
# 输出 JSON 名单，例：["客户A", "客户B", ...]
# 若输出 [] 表示无剩余客户，停止执行

# B-2 对名单中每个客户执行：
#   获取聊天记录文件路径
python /scripts/phase_b_status.py file "{客户名}"
#   读取上述路径的文件内容
#   按 /references/extraction-prompt.md 提取条目
#   保存到 /nim-kb-batch/extracts/{客户名}.json

# B-3 标记状态
python /scripts/phase_b_status.py extracted "客户名"
# 无有效条目时：
python /scripts/phase_b_status.py skipped "客户名"

⚠️ 子代理崩溃时，用 reset 恢复卡住的客户：

python /scripts/phase_b_status.py reset "客户名"

阶段 C - 批量入库（推荐使用子代理）

⚠️ Phase C 必须串行执行，不支持并行子代理。 去重判断依赖"当前知识库文件内容"，并发读写会导致重复录入或数据覆盖。

串行批量处理

告诉 AI："启动串行批量入库，每次处理 10 个客户"

AI 逐个执行，每个客户完成后再处理下一个：

# 重复执行直到 next-c 提示"全部条目已入库"

# C-1 获取下一个待入库客户
python /scripts/phase_b_status.py next-c

# C-2 读取提取结果
# 读取 ~/nim-knowledge-base/tem/nim-kb-batch/extracts/{客户名}.json
# 文件小于100字节则跳过处理下个客户

# C-3 去重合并（按 references/kb-management.md 录入规范 > 去重判断规则执行）

# C-4 写入知识库（目录结构和内容必须符合references/kb-management.md要求，注意不要遗漏YAML frontmatter字段）

# C-5 提交
cd ~/nim-knowledge-base/rags/knowledge
git add .
git commit -m "feat(知识库): 批量录入 [{客户名}] - {新建数} 条"

# C-6 标记完成，回到 tem 目录继续下一个
cd ~/nim-knowledge-base/tem
python /scripts/phase_b_status.py done "{客户名}"

阶段 D - 清理临时文件

所有客户全部处理完成后，开始对nm-kb-batch下的临时文件做清理操作，需要清理的文件有:

路径	说明
customers/{客户名}.txt	Phase A 拆分结果，Phase B 读取
extracts/{客户名}.json	Phase B 提取结果，Phase C 读取
progress.json	各阶段进度状态，由脚本维护

详细文档

• extraction-prompt.md - 提取规则
• kb-management.md - 知识库管理规范

常见问题

Q: 子代理处理失败怎么办？ A: progress.json 记录了每个客户的状态，重新启动子代理会自动跳过已完成的。

Q: 如何调整批次大小？ A: 提取阶段建议 10 个/批，入库阶段建议 20 个/批（提取更耗时）。

Q: 如何查看整体进度？

python /scripts/batch_helper.py stats