Knowledge Base Ingestion

将外部知识库（文档/笔记/共享文件等）提取内容并灌入向量数据库的标准流程。支持 ChromaDB、Pinecone、Weaviate 等多种向量库后端。包括预扫描目录、识别并排除无效文件、执行分批灌入、验证索引质量、失败恢复。

⚠️ 外部依赖声明：本 Skill 的核心脚本 scripts/knowledge-ingest.py 不包含在本目录中。 它是一个独立的 Python 工具，需从项目仓库单独获取或根据本 Skill 描述的接口自行实现。 默认向量库后端为 ChromaDB，如需 Pinecone/Weaviate 等，设置环境变量 VECTOR_DB。

知识库提取与向量索引灌入

通用知识库灌入流程，支持多种向量数据库后端

何时使用

将外部知识库（文档/笔记/共享文件等）的内容灌入向量数据库。

触发场景：

• 用户要求"把新文档灌入向量库"或"同步知识库"
• Cron 定时任务触发
• 新增知识库目录后首次灌入
• 灌入后检索质量下降，需要重建索引

不使用的场景：

• 仅需查询已有知识 → 使用对应的搜索工具
• 少量文件手动添加 → 使用针对单客户的灌入命令

快速流程图

text

预扫描 → 统计文件分布 → ⚠️ 识别无效文件 → 更新排除规则
  ↓
Checkpoint #1：向用户确认灌入范围
  ↓
执行灌入（分批处理，每批 ≤500 文件）
  ↓
Checkpoint #2：验证索引 → 检查数量和维度
  ↓
测试语义检索 → 抽查 3 条典型查询
  ↓
记录结果到当日 memory

支持的向量数据库后端

后端	适用场景	配置方式
ChromaDB	本地部署、小规模（<100K docs）	VECTOR_DB=chroma
Pinecone	云端、大规模、生产环境	VECTOR_DB=pinecone + API Key
Weaviate	云端/本地、中等规模	VECTOR_DB=weaviate + endpoint
Qdrant	本地/云端、高性能	VECTOR_DB=qdrant + endpoint
Milvus	大规模、分布式	VECTOR_DB=milvus + endpoint

默认使用 ChromaDB（本地免费），可通过环境变量切换。

核心资源

资源	说明
灌入脚本	scripts/knowledge-ingest.py — 主灌入脚本，支持分批/指定客户/状态恢复
知识库源目录	通过 KB_DIR 环境变量指定
向量库存储	根据 VECTOR_DB 配置自动选择
灌入状态文件	记录进度、错误、统计

执行步骤

Step 1: 预扫描目录

目标： 了解文件分布，识别并排除无效文件。

bash

# 1. 统计文件数量和类型分布
find $KB_DIR -type f | wc -l
find $KB_DIR -type f | sed 's/.*\.//' | sort | uniq -c | sort -rn

# 2. 检查是否有超大文件（>1MB，可能灌入失败）
find $KB_DIR -type f -size +1M -name "*.md"

# 3. 查看目录结构
ls -la $KB_DIR

无效文件识别规则（自动排除）：

文件类型	排除规则	原因
代码文件	.js, .ts, .py, .java, .go, .css, .html	无语义价值，污染检索结果
二进制文件	.pdf, .docx, .xlsx, .png, .zip	无法直接读取文本
系统文件	.DS_Store, .git, .svn, Thumbs.db	系统垃圾
构建产物	node_modules/, dist/, build/, __pycache__/	自动生成，无需灌入
空/过短文件	文本 < 100 字符	内容不足，无索引价值

Step 2: 更新排除规则

根据预扫描结果，如发现新的无效目录，更新脚本的排除规则。

Checkpoint #1: 用户确认灌入范围 ⚠️

在执行灌入前，向用户报告并确认：

text

📊 预扫描结果：
- 总文件数：X 个
- 有效文件：Y 个（.md 文本）
- 排除文件：Z 个（代码/二进制/系统）
- 向量库当前索引：M chunks
- 向量库后端：{VECTOR_DB}

请确认：是否开始灌入有效文件？(y/n)

• 用户确认后才执行 Step 3
• 如果文件量异常（>5000 新增），先分批确认

Step 3: 执行灌入（分批处理）

目标： 将有效文件分批灌入向量数据库，每批 ≤500 文件。

bash

# 方式 A：自动下一批（推荐，从断点续跑）
python3 scripts/knowledge-ingest.py

# 方式 B：指定单个客户（调试或重跑）
python3 scripts/knowledge-ingest.py --client <客户名>

# 方式 C：查看当前状态
python3 scripts/knowledge-ingest.py --status

# 方式 D：重置进度（从头重跑，慎用！）
python3 scripts/knowledge-ingest.py --reset

灌入脚本行为说明：

• 自动从状态文件恢复进度，断点续跑
• 大文件（>4000 字符）自动按段落分割为 chunks，每 chunk ≤8000 字符
• 去重：基于文件路径 MD5 前 16 位，已存在的文件自动跳过
• 每批处理完自动保存状态

Step 4: 验证索引质量

目标： 确保灌入结果正确，索引数量和数据完整。

bash

# 1. 查看灌入状态和向量库统计
python3 scripts/knowledge-ingest.py --status

验证检查清单：

检查项	通过标准	失败处理
索引数量	chunks > 0	→ 见「失败恢复流程」
向量维度	每个 chunk 有 embedding	→ 见「失败恢复流程」
错误率	errors 数组长度 < 总文件数的 5%	超过阈值 → 检查具体错误，修复后重跑
客户覆盖	所有客户目录都有对应集合	缺少 → 手动指定客户重跑

Step 5: 测试语义检索准确性

目标： 端到端验证检索质量。

bash

# 使用搜索脚本做语义检索测试（选取 3 条典型查询）
python3 scripts/kg_search.py "你的测试查询1" --top 5
python3 scripts/kg_search.py "你的测试查询2" --top 5
python3 scripts/kg_search.py "你的测试查询3" --top 5

检索质量评估标准：

等级	标准
✅ 优秀	Top-3 结果与查询高度相关
⚠️ 可接受	Top-5 中有 2-3 条相关
❌ 不合格	Top-5 无明显相关结果 → 需排查

不合格排查步骤：

1. 检查向量库集合是否真的有数据：--status
2. 检查嵌入模型是否正常
3. 检查源文件内容质量：文件是否过短或乱码
4. 尝试精确关键词搜索 vs 语义搜索，判断是索引问题还是查询问题

Checkpoint #2: 灌入结果确认 ⚠️

完成后向用户报告：

text

✅ 灌入完成报告：
- 新增灌入：X 个文件，Y 个 chunks
- 跳过（已存在）：Z 个
- 错误：E 个（如有）
- 向量库总计：M chunks
- 检索测试：3/3 通过
- 状态文件：已更新

Step 6: 记录到当日 memory

将灌入结果追加到 memory/daily/YYYY-MM-DD.md。

失败恢复流程

场景 1：向量库连接失败

症状： 脚本报错，提示无法连接或创建集合。

恢复步骤：

bash

# 0. 检查磁盘空间（本地向量库持续增长可能写满磁盘）
df -h

# 1. 检查向量库存储目录/连接是否正常

# 2. 如果目录损坏，备份后重建

# 3. 重置灌入状态（从头重跑）
python3 scripts/knowledge-ingest.py --reset

# 4. 重新执行灌入
python3 scripts/knowledge-ingest.py

场景 2：灌入中途中断

症状： 脚本因内存不足/超时/网络断开中断。

恢复步骤：

bash

# 1. 查看当前状态（脚本自动保存进度）
python3 scripts/knowledge-ingest.py --status

# 2. 直接重新运行（自动从断点续跑）
python3 scripts/knowledge-ingest.py

# 3. 如果卡在某个客户，跳过该客户
python3 scripts/knowledge-ingest.py --client <下一个客户>

场景 3：灌入后检索质量差

症状： 检索返回不相关结果。

恢复步骤：

1. 确认数据量
2. 检查具体集合的数据
3. 如果是特定客户数据有问题，重置该客户状态后重跑

场景 4：嵌入模型异常

症状： chunks 写入成功但检索不到结果（可能 embedding 未正确生成）。

恢复步骤：

1. 确认嵌入模型已安装
2. 如果模型缺失，安装后重跑

注意事项

• 执行前确认当前系统状态，避免在已有操作进行中执行
• 配置类操作必须先备份再修改（脚本、状态文件、向量库目录）
• 如遇到未预料的问题，先记录到当日 memory 文件，再排查
• 大批量灌入（>5000 文件）建议分天完成，避免单次耗时过长
• 客户目录命名规范：目录名用于生成集合名，避免特殊字符
• KB_DIR 环境变量：可通过设置 KB_DIR 指向不同的源目录
• VECTOR_DB 环境变量：可通过设置 VECTOR_DB 切换向量库后端

版本历史

日期	版本	变更说明
2026-04-23	1.0	初始版本，基础流程
2026-06-01	2.0	Phase 2 优化：补充具体命令、失败恢复流程、用户确认检查点、检索质量评估标准
2026-07-04	3.0	通用化改造：去除 ChromaDB 硬依赖，支持多种向量数据库后端