98 lines
3.7 KiB
Markdown
98 lines
3.7 KiB
Markdown
# 异步入库与失败恢复说明
|
||
|
||
## 范围
|
||
|
||
DEMO-015 将单文件上传从 API 请求线程迁移到独立 Celery Worker,DEMO-016 在其上增加逐文件
|
||
隔离的批量接收和状态聚合。OceanBase 中的
|
||
`ingestion_jobs` 和 `ingestion_attempts` 是执行状态事实源;RabbitMQ 消息只携带 Job ID,
|
||
不携带文件内容、Provider 凭据或业务状态。
|
||
|
||
批次只聚合接收与 Job 状态,不改变每个文件的独立执行和重试边界。
|
||
|
||
## 运行时配置
|
||
|
||
以下值必须通过环境变量或部署 Secret 注入,不得提交真实值:
|
||
|
||
```text
|
||
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 的最小权限。
|
||
|
||
## 启动顺序
|
||
|
||
```bash
|
||
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 创建前严格执行:
|
||
|
||
```text
|
||
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`。查询:
|
||
|
||
```text
|
||
GET /api/v1/jobs/{job_id}
|
||
```
|
||
|
||
Job 状态为 `queued | running | retrying | succeeded | failed | cancelled`;阶段为
|
||
`parsing | cleaning | chunking | embedding | indexing`。公开错误只返回固定安全摘要,不保存或
|
||
返回 Broker/Provider 异常正文。活动 Job 的 Document 暂不允许删除,API 返回 `409`。
|
||
|
||
批量提交与查询:
|
||
|
||
```text
|
||
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 响应。
|