知识库独立导出与导入方案

项目地址：https://github.com/WiSiW/AI-RAG

摘要

在现有按 kb_id 隔离 PostgreSQL 数据、Milvus 集合、Whoosh 目录和 MinIO 文档的基础上，新增知识库级可移植包。支持“文档包”和“携带索引的完整包”两种导出模式，导入时创建全新知识库并重映射全部 ID，不影响现有知识库。

包格式与数据边界

  • 导出为 ZIP，manifest.json 记录包版本、导出时间、源知识库配置、模型描述、文档/Chunk 数量、索引版本、Embedding 维度和文件 SHA-256。
  • 包结构固定为：
    • manifest.json
    • documents.jsonl：文档记录、标签、元数据、chunk 配置
    • chunks.jsonl：L1/L2/L3、摘要、关键词、QA 对、上下文前缀和父子关系
    • originals/{document_id}/{filename}：MinIO 原始文件
    • index/milvus_vectors.jsonl：完整包才有，包含表示行、问题索引和向量
    • index/bm25_documents.jsonl：完整包才有，包含可重建 BM25 的字段
    • checksums.sha256
  • “文档包”不包含向量和 BM25，但保留原始文件、文档元数据、chunk、增强字段和 QA；导入时只需重新生成 Embedding/索引，不重新解析、分块或调用增强模型。
  • “完整包”额外包含可移植向量与 BM25 快照；导入时重建 Milvus/Whoosh，而不是复制原始数据库二进制。
  • 不导出模型 API Key、对话、评估历史、发布接口或其他知识库数据。
  • ZIP 使用 manifest SHA-256 做完整性校验；通过 HTTPS 下载，不额外做内置密码加密。
  • 导入前禁止路径穿越、超限解压、未知 schema、重复条目和校验和不匹配。

导出与一致性

  • 新增异步导出任务；导出期间通过活动 transfer job 给知识库加写锁，拒绝上传、删除、重索引、知识库设置修改和其他导入写入。
  • 任务读取一致的知识库快照，流式打包原始文件、JSONL 和可选索引，不把整个包放入内存；成品上传到 MinIO 的独立导出前缀。
  • Milvus 按主键分页读取指定知识库 v2 集合的全部表示行和向量；记录 schema/collection 版本及 Embedding 描述。
  • Whoosh 导出规范化 BM25 文档字段，导入时重建索引目录。
  • 任务结束或失败后自动释放写锁；异常记录到任务错误中，保留已生成临时文件供诊断但不允许下载未完成包。
  • 导出包由管理员手动删除；下载接口只允许访问已完成且属于当前管理员的 transfer job。

导入与索引恢复

  • 导入默认创建新知识库，并生成新 kb_id、document_id、chunk_id，建立完整旧 ID → 新 ID 映射，修复 L1 的 parent_chunk_ids、L3 的 parent_chunk_id、QA 和向量引用。
  • 名称冲突时自动生成“原名（导入 2）”等唯一名称。
  • 导入请求必须选择目标 Embedding、Enrichment 模型；Rerank 和默认 LLM 可选。模型 API Key 不随包迁移。
  • 完整包默认采用严格索引恢复：目标 Embedding 的 provider/model_name/dimensions 必须与 manifest 一致，此时直接重映射并写入导出向量。
  • 用户可选择 index_policy=rebuild：即使模型不同，也基于包内 chunk 和 QA 重新生成全部表示向量；文档包始终使用该策略。
  • 严格模式下模型不匹配返回明确错误，不自动混用不同向量空间。
  • 原始文件重新上传到目标 MinIO 新对象键；文档和 chunk 按 manifest 恢复，最终状态设为 ready。
  • 导入任务失败时删除新建知识库、文档、chunk、对象存储文件、Milvus 集合和 Whoosh 目录，保证失败不留下半成品。
  • 导入完成后新知识库使用 index_version=v2，可立即检索、问答和继续上传文档。

API 与页面

  • POST /api/v1/knowledge-bases/{id}/exports：创建导出任务，参数 mode=documents|full。
  • GET /api/v1/knowledge-base-transfers/{job_id}：查询导出/导入进度、计数和错误。
  • GET /api/v1/knowledge-base-transfers/{job_id}/download：下载已完成导出包。
  • POST /api/v1/knowledge-base-imports/inspect：上传 ZIP 并返回 manifest 摘要、模型要求和校验结果，不创建知识库。
  • POST /api/v1/knowledge-base-imports：上传包并创建新知识库，参数包括 name、模型映射和 index_policy=strict|rebuild。
  • DELETE /api/v1/knowledge-base-transfers/{job_id}：删除历史任务及导出对象。
  • 新增 knowledge_base_transfer_jobs：类型、KB ID、模式、状态、进度、对象键、manifest、错误和时间戳。
  • 知识库详情页增加“导出知识库”，可选择文档包或完整包并展示进度。
  • 知识库列表增加“导入知识库”向导：上传、预检、名称/模型映射、选择严格恢复或重新建索引、执行导入。
  • 两种任务均按 queued/running/completed/failed 轮询，完成后提供下载或跳转新知识库。

测试与验收

  • 文档包导出后导入空实例，验证文档、标签、元数据、L1/L2/L3、QA、父子关系和原始文件完整。
  • 完整包在兼容 Embedding 环境下严格导入，验证无需重新调用 Embedding 即可检索。
  • 模型签名不匹配时严格模式失败；rebuild 模式成功重新嵌入并重建索引。
  • 验证旧 ID → 新 ID 映射、对象键重写、QA/父子引用和名称自动去重。
  • 验证导出写锁阻止上传、删除、重索引和设置修改，任务结束后恢复。
  • 验证异常中断、校验失败、路径穿越和模型缺失均触发完整回滚。
  • 验证大文件流式打包、ZIP 解压限制和下载鉴权。
  • 前端验证双模式导出、导入预检、模型映射、进度轮询和完成后跳转，并通过生产构建。

假设与默认值

  • 一次只处理一个知识库包；不支持合并到已有知识库。
  • 完整包默认使用 index_policy=strict，由导入请求显式切换为 rebuild。
  • 模型配置不随包复制，导入时必须映射目标环境现有模型。
  • 不包含对话、评估、发布接口和用户权限数据。
  • 包为带 SHA-256 校验的普通 ZIP，依赖 HTTPS 和管理员鉴权保护传输安全。
  • Milvus/Whoosh 导入采用可移植数据快照并重建索引，不直接复制实例内部文件。

最后更新： 2026年11月03日 15:01