knowledge-platform/docs/plans/ASYNC_INGESTION_MCP_PLAN.md
2026-09-02 20:42:52 +08:00

6.7 KiB
Raw Permalink Blame History

MCP 与异步批量入库优先级方案

Task: PLAN-001
Status: Accepted planning baseline
Date: 2026-09-02

1. 现状判断

能力 当前实现 结论
单文件上传 POST /api/v1/documents 持久化 Source/Document/Job 后返回 202,Worker 后台处理 DEMO-015 已实现
批量上传 批次 API、逐文件 Job 状态和 Admin Console 自动轮询 DEMO-016 已实现
失败补偿 阶段内补偿 + 重试前清理全部派生数据,保留不可变源和执行历史 DEMO-015 已实现
自动重试 OceanBase Job/Attempt + Celery/RabbitMQ + 有界退避 + Worker 租约恢复 DEMO-015 已实现
重试前清理 重试前删除向量、索引状态、Chunk、解析产物,保留源文件与历史 DEMO-015 已实现
MCP 独立 Gateway、认证边界、search_knowledge 与 WorkBuddy 协议级验收 DEMO-012 已实现

PLAN-001 的异步执行缺口已由 DEMO-015 补齐,批量提交与状态 UI 已由 DEMO-016 补齐。

2. Task 归并结论

DEMO-012:MCP search_knowledge(提升为最高优先级)

保留既有 Task ID,不新建重复任务。范围限定为:

  • 提供可运行的标准 MCP Gateway;
  • 只暴露 search_knowledge;
  • 复用现有 Search Service 或正式 /api/v1/search,不复制检索逻辑;
  • 建立 WorkBuddy 所需的 user/service identity 边界,不使用共享超级管理员凭据;
  • 完成协议契约、错误收敛、凭据脱敏和 WorkBuddy 兼容性验证。

该 Task 是 EKP-070、EKP-071、EKP-072 的最小垂直切片,不能据此把三个完整 V1 Task 标记为完成。

DEMO-015:异步入库 Job 与自动重试清理(新增)

从 EKP-017 和 EKP-023 抽取 Demo 所需的最小基础能力,并复用 DEMO-003~006 的处理服务:

  • 新增持久化 Ingestion Job/Attempt,记录阶段、状态、尝试次数、安全错误和时间戳;
  • 源文件成功写入 BOS 且 Document 已持久化后立即排队,API 不等待解析和索引;
  • 同一 Document 同时最多一个有效执行,任务投递和消费具备幂等保护;
  • 对可重试的瞬时错误自动执行有界重试和退避;Demo 默认最多 3 次总尝试,允许通过非敏感配置调整;
  • 格式不支持、文件为空、无可提取内容等确定性错误直接失败,不进行无意义重试;
  • 每次重新执行前,按顺序清理该 Document 的向量行、ChunkIndexState、Chunk 和解析产物,再从不可变原始文件重新处理;
  • 原始文件、Document 标识和审计所需的 Job/Attempt 历史不得被重试清理删除;
  • 任一清理步骤失败时禁止启动下一次尝试,并记录为终止失败,避免在未知脏状态上重复执行。
  • 通过执行器抽象接入 Celery/RabbitMQ,使 API 和 Worker 可独立部署;业务应用服务不得直接 依赖 Celery API,确保执行器仍可替换;
  • Worker 重启、消息重复投递和确认超时必须保持持久化 Job 状态一致,不能产生双重有效 Attempt 或重复派生数据。

该 Task 只完成公共知识库入库所需的 Job/Retry 与队列基线,不扩展到完整审计系统、 Compilation、OCR、跨区域高可用或通用企业级 Job 平台。

DEMO-016:批量异步上传与状态展示(已完成)

建立在 DEMO-015 之上,不与 Job 基础合并:

  • 新增批量上传 API,一次接收多个 Demo 支持类型文件;
  • 每个文件独立生成 Document 和 Ingestion Job,单个文件失败不回滚已成功接收的其他文件;
  • 返回批次 ID、逐文件 Document ID、Job ID 和接收状态,不等待后台处理完成;
  • 提供批次/Job 查询能力,并在 Admin Console 展示逐文件阶段、重试次数和最终结果;
  • 文件数量、单文件大小和请求总大小均受可配置限制;
  • 不在本 Task 引入目录上传、压缩包解包、断点续传或跨批次去重。

该 Task 对应 EKP-021 的批量异步扩展及 EKP-080/EKP-081 的最小状态 UI 切片,不能据此把完整 V1 Task 标记为完成。

3. 实施顺序与依赖

DEMO-009 + ARCH-006 → DEMO-012(已完成)

PLAN-002(已完成)
  └──→ DEMO-003 → DEMO-004 → DEMO-005 → DEMO-006
             └──→ DEMO-015 Async Job + Celery/RabbitMQ + Retry Cleanup
                              └──→ DEMO-016 Batch Async Upload + UI
                                       └──→ DEPLOY-001 → DEPLOY-002 → DEPLOY-003

推荐严格按以下顺序执行并逐项闭环:

  1. PLAN-002(已完成)
  2. DEMO-015(已完成)
  3. DEMO-016(已完成)
  4. DEPLOY-001
  5. DEPLOY-002
  6. DEPLOY-003

MCP 与异步入库没有代码级前置依赖,因此提高 MCP 优先级不会阻塞后续批量上传。DEMO-016 必须等待 DEMO-015,否则会把同步流水线简单并发放大,缺少可靠的状态、隔离和恢复边界。

4. 验收边界

DEMO-012

  • MCP Inspector/标准客户端能发现并调用 search_knowledge;
  • WorkBuddy 使用已映射的 user/service identity 完成一次端到端检索;
  • REST 与 MCP 对同一查询复用同一业务逻辑并返回一致的来源字段;
  • 响应与日志不泄露 OceanBase、BOS、模型名、Endpoint 或凭据。

DEMO-015

  • 上传接口在源文件和 Job 持久化后返回 202,后台完成现有全流水线;
  • 注入一次可重试故障后可观察到自动重试,并最终成功;
  • 第二次尝试开始前,旧解析产物、Chunk、索引状态和向量均已清理,原始源文件仍存在;
  • 永久错误不重试,达到次数上限后稳定进入 failed;
  • 并发或重复投递不会产生双重有效执行和重复派生数据。
  • RabbitMQ 消息确认超时或 Worker 重启后,Job 可恢复到终态且不会重复生成派生数据。

DEMO-016

  • 一次提交多个文件后立即得到逐文件 Document/Job 标识;
  • 批次内成功、处理中、重试中和失败状态互不影响且可查询;
  • Admin Console 无需刷新即可轮询展示逐文件进度和最终状态;
  • 批次边界、大小限制、部分失败和重试清理均有集成测试。

5. 非目标与 ADR 影响

  • PLAN-002 已把 Celery/RabbitMQ 纳入 DEMO-015,并以独立 DEPLOY-* Task 纳入最小 Kubernetes、多副本和滚动升级能力;跨区域容灾、自动云资源编排和完整 Observability 仍为非目标。
  • 不改变 OceanBase/BOS canonical、向量索引可重建、原始文档不可变、Provider 抽象和 MCP 隐藏基础设施等 Accepted ADR。
  • 公共知识库只是阶段性单一可见域;ADR-007 保持 Accepted,用户/ACL 实现后置且不得用全局 Top-K 后过滤替代。
  • 本次任务拆分和交付边界不需要新增或重开 Accepted ADR。