feat: add async worker queues and retry controls

2026-04-29 11:48:09 +08:00
parent e738398eb6
commit f3b83c9979
16 changed files with 1316 additions and 96 deletions
@@ -0,0 +1,149 @@
+# LeAudit 并发与重试参数说明
+
+这份文档记录当前 `leaudit-platform` 已经落地的并发与重试参数，避免后面再忘。
+
+---
+
+## 1. 为什么没有用 `RETRY_BACKOFF_SECONDS = [1, 2, 4]`
+
+这次我没有把退避时间设计成数组，而是改成了：
+
+- `*_RETRY_MAX_ATTEMPTS`
+- `*_RETRY_BACKOFF_BASE_SECONDS`
+
+原因很简单：
+
+- 配置更短，更容易看懂
+- 不用每次都手写 `[1, 2, 4]`
+- 代码统一按“指数退避”算等待时间
+
+计算方式：
+
+```text
+第 1 次重试等待 = base
+第 2 次重试等待 = base * 2
+第 3 次重试等待 = base * 4
+...
+```
+
+例如：
+
+```toml
+LLM_RETRY_MAX_ATTEMPTS = 3
+LLM_RETRY_BACKOFF_BASE_SECONDS = 1
+```
+
+表示：
+
+- 第 1 次请求失败后，等 `1s`
+- 第 2 次再失败后，等 `2s`
+- 总共最多尝试 `3` 次
+
+---
+
+## 2. 当前已正式化的参数
+
+当前 `app.toml` 中已启用：
+
+```toml
+[LEAUDIT]
+LLM_MAX_CONCURRENCY = 5
+VLM_MAX_CONCURRENCY = 3
+
+LLM_REQUEST_TIMEOUT = 120
+LLM_RETRY_MAX_ATTEMPTS = 3
+LLM_RETRY_BACKOFF_BASE_SECONDS = 1
+
+VLM_REQUEST_TIMEOUT = 45
+VLM_RETRY_MAX_ATTEMPTS = 2
+VLM_RETRY_BACKOFF_BASE_SECONDS = 1
+
+OCR_VLM_CONCURRENCY = 32
+OCR_RETRY_MAX_ATTEMPTS = 3
+OCR_RETRY_BACKOFF_BASE_SECONDS = 1
+
+SIGNATURE_PROBE_CONCURRENCY = 2
+SIGNATURE_PROBE_TIMEOUT = 20
+SIGNATURE_PROBE_RETRY_MAX_ATTEMPTS = 2
+SIGNATURE_PROBE_RETRY_BACKOFF_BASE_SECONDS = 0.5
+```
+
+---
+
+## 3. 各链路当前策略
+
+### 3.1 LLM
+
+- 客户端：`ResilientOpenAICompatibleClient`
+- 超时：`LLM_REQUEST_TIMEOUT`
+- 最大尝试次数：`LLM_RETRY_MAX_ATTEMPTS`
+- 退避基数：`LLM_RETRY_BACKOFF_BASE_SECONDS`
+- 重试条件：
+  - 超时
+  - 连接错误
+  - `5xx`
+  - `408`
+  - `429`
+
+### 3.2 VLM
+
+- 客户端：`ResilientQwenVLMClient`
+- 超时：`VLM_REQUEST_TIMEOUT`
+- 最大尝试次数：`VLM_RETRY_MAX_ATTEMPTS`
+- 退避基数：`VLM_RETRY_BACKOFF_BASE_SECONDS`
+- 重试条件：
+  - 超时
+  - 连接错误
+  - `5xx`
+  - `408`
+  - `429`
+
+### 3.3 OCR
+
+- 客户端：`ResilientChandraOCRClient`
+- OCR HTTP 超时：沿用 `[OCR].TIMEOUT`
+- 最大尝试次数：`OCR_RETRY_MAX_ATTEMPTS`
+- 退避基数：`OCR_RETRY_BACKOFF_BASE_SECONDS`
+- 重试条件：
+  - 超时
+  - 连接错误
+  - `5xx`
+  - `408`
+  - `429`
+
+### 3.4 Signature Probe
+
+这是 DOCX 签名候选补识别，不是主 OCR。
+
+- 并发：`SIGNATURE_PROBE_CONCURRENCY`
+- 单次超时：`SIGNATURE_PROBE_TIMEOUT`
+- 最大尝试次数：`SIGNATURE_PROBE_RETRY_MAX_ATTEMPTS`
+- 退避基数：`SIGNATURE_PROBE_RETRY_BACKOFF_BASE_SECONDS`
+- 第 1 次失败后，会用 fresh VLM client 再试
+
+---
+
+## 4. 为什么把 signature probe 调小
+
+之前这里容易长时间卡住，根因是：
+
+- 它是补探测
+- 但单次超时太长
+- 且失败后还会再试一次
+
+所以现在把它收成：
+
+- `SIGNATURE_PROBE_CONCURRENCY = 2`
+- `SIGNATURE_PROBE_TIMEOUT = 20`
+
+这样它仍然能补识别，但不会把整条 OCR 长尾拖得太夸张。
+
+---
+
+## 5. 当前代码位置
+
+- 配置定义：`fastapi_admin/config/_settings.py`
+- 客户端工厂：`fastapi_modules/fastapi_leaudit/leaudit_bridge/client_factory.py`
+- 重试封装：`fastapi_modules/fastapi_leaudit/leaudit_bridge/resilient_clients.py`
+- signature probe：`fastapi_modules/fastapi_leaudit/leaudit_bridge/ocr_bridge.py`
+