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

3.7 KiB
Raw Blame History

异步入库与失败恢复说明

范围

DEMO-015 将单文件上传从 API 请求线程迁移到独立 Celery Worker,DEMO-016 在其上增加逐文件 隔离的批量接收和状态聚合。OceanBase 中的 ingestion_jobs 和 ingestion_attempts 是执行状态事实源;RabbitMQ 消息只携带 Job ID, 不携带文件内容、Provider 凭据或业务状态。

批次只聚合接收与 Job 状态,不改变每个文件的独立执行和重试边界。

运行时配置

以下值必须通过环境变量或部署 Secret 注入,不得提交真实值:

RABBITMQ_URL=amqp://<user>:<password>@<host>:5672/<vhost>
INGESTION_MAX_ATTEMPTS=3
INGESTION_RETRY_BACKOFF_SECONDS=2
INGESTION_RETRY_BACKOFF_MAX_SECONDS=60
INGESTION_WORKER_LEASE_SECONDS=300
INGESTION_RECOVERY_INTERVAL_SECONDS=30
BATCH_MAX_FILES=20
BATCH_MAX_TOTAL_BYTES=209715200

Worker 与 API 还需要相同的 OceanBase、BOS、Embedding、VectorStore 和 Index Profile 配置。 RabbitMQ 用户应只具备指定 vhost/queue 的最小权限。

启动顺序

uv run alembic upgrade head
make run-worker
make run

make run-worker 在当前 Demo 中同时启动 Worker 和恢复调度器。恢复调度器周期扫描:

  • 尚未成功投递的 queued Job;
  • 已到重试时间的 retrying Job;
  • Worker 丢失后租约已过期的 running Job。

任务投递使用 late acknowledgement、worker-lost reject 和单任务 prefetch。重复消息会先锁定 Job 行;有效租约内不会创建第二个 Attempt。租约过期后,旧 Attempt 以安全错误关闭,再按重试 规则恢复。

重试与清理

确定性的内容错误(无法解析、清洗后为空、无 Chunk、派生数据身份不一致)直接进入 failed。 其余运行时/Provider 错误按指数退避重试,默认最多三次总 Attempt。

第二次及后续 Attempt 创建前严格执行:

OceanBase Vector rows
→ ChunkIndexState
→ Chunk
→ parsed JSON object
→ reset Document processing state

不可变源文件、Document、Job 和已结束 Attempt 始终保留。任一清理步骤失败时不创建新 Attempt, Job 直接以 retry cleanup failed 终止,禁止在未知脏状态继续执行。

API 状态

POST /api/v1/documents 成功返回 202 和 job_id。查询:

GET /api/v1/jobs/{job_id}

Job 状态为 queued | running | retrying | succeeded | failed | cancelled;阶段为 parsing | cleaning | chunking | embedding | indexing。公开错误只返回固定安全摘要,不保存或 返回 Broker/Provider 异常正文。活动 Job 的 Document 暂不允许删除,API 返回 409。

批量提交与查询:

POST /api/v1/ingestion-batches   # multipart 字段 files,可重复
GET  /api/v1/ingestion-batches/{batch_id}

批次创建后逐文件返回 accepted 或 rejected;已接收文件继续通过上述 Job 状态异步推进。 批次聚合状态为 processing | completed | partial_failure | failed。请求文件数超过 BATCH_MAX_FILES 时整体返回 413;单文件或共享总字节预算超限只拒绝当前文件,不删除此前 已接收文件。默认总预算 200 MiB,且配置不得小于单文件 MAX_UPLOAD_BYTES。

故障检查

  1. Job 长期为 queued:检查 RabbitMQ 连通性、恢复调度器以及 ingestion queue;
  2. Job 长期为 running:检查 Worker,租约到期后恢复调度器会重新投递;
  3. Job 为 retrying:等待 next_run_at,客户端不应重新上传同一文件;
  4. Job 为 failed 且错误为 retry cleanup failed:停止人工重试,先核对向量、关系数据与 BOS 派生对象的一致性;
  5. 不得通过日志打印 RABBITMQ_URL、数据库 URL、BOS/模型凭据或原始 Provider 响应。