3.7 KiB
异步入库与失败恢复说明
范围
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 和恢复调度器。恢复调度器周期扫描:
- 尚未成功投递的
queuedJob; - 已到重试时间的
retryingJob; - Worker 丢失后租约已过期的
runningJob。
任务投递使用 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。
故障检查
- Job 长期为
queued:检查 RabbitMQ 连通性、恢复调度器以及ingestionqueue; - Job 长期为
running:检查 Worker,租约到期后恢复调度器会重新投递; - Job 为
retrying:等待next_run_at,客户端不应重新上传同一文件; - Job 为
failed且错误为retry cleanup failed:停止人工重试,先核对向量、关系数据与 BOS 派生对象的一致性; - 不得通过日志打印
RABBITMQ_URL、数据库 URL、BOS/模型凭据或原始 Provider 响应。