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

6.1 KiB
Raw Blame History

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

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

1. 现状判断

能力 当前实现 结论
单文件上传 POST /api/v1/documents 接收一个 file,并在请求线程内同步完成解析、Chunk、Embedding 和索引 已实现,但不满足 V1 异步要求
批量上传 API 与 Admin Console 都只支持一个文件 未实现
失败补偿 上传元数据失败会删除源对象;解析元数据失败会删除本次解析产物;索引失败会删除当前 Document/Profile 的可能残留向量 已有局部补偿,不是自动重试
自动重试 没有持久化 Job、Attempt、调度器、退避策略或自动重新执行入口 未实现
重试前清理 影子索引重建能清理目标 Profile 的部分写入;正常上传流水线没有统一清理解析产物、Chunk、索引状态和向量的能力 未实现
MCP 已有 MCP 业务契约和可复用 Search Service/REST API,没有可运行 MCP Gateway 或 WorkBuddy 验证 未实现

因此,现有失败补偿只能降低一次执行留下半成品的概率,不能满足“失败后自动重新执行,并在重新执行前清理旧数据”。

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 历史不得被重试清理删除;
  • 任一清理步骤失败时禁止启动下一次尝试,并记录为终止失败,避免在未知脏状态上重复执行。

该 Task 只完成 Demo 入库所需的 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 MCP search_knowledge

DEMO-003 → DEMO-004 → DEMO-005 → DEMO-006
        └──→ DEMO-015 Async Job + Retry Cleanup
                         └──→ DEMO-016 Batch Async Upload + UI

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

  1. DEMO-012
  2. DEMO-015
  3. DEMO-016

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;
  • 并发或重复投递不会产生双重有效执行和重复派生数据。

DEMO-016

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

5. 非目标与 ADR 影响

  • 不把 RabbitMQ/Celery、Kubernetes、高可用或完整 Observability 纳入上述 Demo Task;具体执行器继续通过接口隔离,后续 V1 可替换。
  • 不改变 OceanBase/BOS canonical、向量索引可重建、原始文档不可变、Provider 抽象和 MCP 隐藏基础设施等 Accepted ADR。
  • 本次只是任务拆分、优先级和契约澄清,不需要新增或重开 Accepted ADR。