172 lines
17 KiB
Markdown
172 lines
17 KiB
Markdown
# M3 OCR 端口族设计
|
|
|
|
- **日期**: 2026-07-21;**状态**: 待人类审批(公共 API,强制人类门)
|
|
- **范围拍板**(用户 2026-07-21): ROADMAP §4 既定范围 + G1 销账;GLM OCR 按 D9 继续预留;OCR 纳入 soak 压测体系;验收打真实 MonkeyOCR 服务
|
|
- **上游依据**: ARCHITECTURE §7.10(端口族冻结面)、D9(端口族而非单接口)、ROADMAP §4(内部顺序与验收出口)、migrations/video-tree-trm5.md §9-R9/R10、migrations/chsanalyzer.md G1/R6
|
|
|
|
## 1. 需求与实况取证
|
|
|
|
### 1.1 两个蓝本(需求来源)
|
|
|
|
| 蓝本 | 端点 | 用途 | 治理现状 |
|
|
|---|---|---|---|
|
|
| `reference/Video-Tree-TRM5/adapters/ocr.py`(128 行) | `POST /ocr/text` → JSON `{content}` | 帧文字硬证据注入 VLM 提示词 | **裸调**(同步 requests、双端点轮询、单帧失败跳过)→ 迁移后免费升级全治理 |
|
|
| `reference/CHSAnalyzer/app/providers/invokers.py:408-552` | `POST /parse` → JSON(download_url)→ GET ZIP → `_middle.json` | 定位护理记录表格 bbox | 已全治理(governance.run 泛型核心) |
|
|
|
|
### 1.2 真实服务协议取证(2026-07-21,10.77.0.20:7866/7867 实测双活)
|
|
|
|
用 `data/soak/chs_images/` 真实语料打真实服务,得到以下**协议事实**(样本已存,将二次构造为测试 fixtures):
|
|
|
|
| 事实 | 内容 | 设计影响 |
|
|
|---|---|---|
|
|
| `/health` | 200 + `{"status":"healthy","model_loaded":true}` | check_health 只判 2xx,不假设 body 结构 |
|
|
| `/ocr/text` | `{"success":true,"task_type":"text","content":"...","message":"..."}` | content 为多行纯文本 |
|
|
| `/parse` | `{"success":true,"message":"...","output_dir":"...","files":[...],"download_url":"/static/xxx.zip"}` | **download_url 是相对路径**,必须相对 base_url 解析(CHS 靠 httpx base_url 隐式做到;库需显式处理,兼容绝对 URL) |
|
|
| `_middle.json` | `pdf_info: [page]`;page 含 `page_idx`/`page_size:[w,h]`/`para_blocks`/`tables`/`images`/`interline_equations`/`preproc_blocks` 等 | 见下 |
|
|
| **元素结构关系**(4 样本核实) | `para_blocks` 是统一带类型元素列表(type ∈ table/image/text/...,各含 bbox);`tables` 列表与其中 type=table 的块 **bbox 完全一致**(如 chs_0001 两处均为 [41,48,218,282]) | `elements` 从 `para_blocks` 统一提取即无损覆盖 CHS 首表路径;`tables` 不必单独建模 |
|
|
|
|
## 2. 备选方案对比
|
|
|
|
| 方案 | 做法 | 权衡 |
|
|
|---|---|---|
|
|
| **A. 独立治理循环 OcrClient(推荐)** | 仿 `EmbeddingClient`(M2 §7 方案 G2 先例): 独立精简治理循环,**复用算法件**——`QuotaGate`/`BreakerGate`/`backoff_delay`/`SourceCooldownMemo`/`_failure_reason`/错误四分类/`TelemetryEmitter`/选源器(含 OutcomeAwareSelector 喂数);新增 `OcrTransport` 端口 + `transports/monkey_ocr.py` | 有限重复第三份选源等待循环(chat/embed/ocr),但 OCR 不需要 chat 循环的 429 免预算、AIMD、流式看门狗、缓存、结构化重问——强行合一才是复制(M2 §7.1 已裁决过一次同类问题);风险最小,不触碰 M2.5 刚验收的 472 行 retry.py |
|
|
| B. 泛化治理核心 | 把 RetryMW 重构为模态无关的 `governance.run(call)`(CHS 形态),chat/embed/ocr 三入口共用 | 算法真正一份,但需重构 M2.5 六机制刚验收的核心(AIMD/降权/429 免预算全是 chat 特有,泛化后要开关化),回归风险大、收益低;**否决** |
|
|
| C. OCR 伪装 ChatRequest 走既有洋葱 | 图像塞 messages,复用全部中间件 | 类型语义崩坏(cache/structured 中间件需空转旁路)、违背"显式优于隐式";**否决** |
|
|
|
|
方案 A 与 CHS 自身现状同构(CHS 的 VLM/OCR 共用泛型核心,是因为它们的循环需求完全一致;本库 chat 循环已长出 OCR 不需要的六机制,同构前提不再成立)。
|
|
|
|
## 3. 公共 API(冻结面,人类门审这里)
|
|
|
|
### 3.1 类型(types.py 新增,全部 frozen dataclass)
|
|
|
|
| 类型 | 字段 | 说明 |
|
|
|---|---|---|
|
|
| `OcrLayoutElement` | `type: str`、`bbox: tuple[float,float,float,float]`、`page_index: int` | type 开放字符串(实测 table/image/text,不枚举锁死——零业务假设);bbox 为 OCR 原生页面坐标(x1,y1,x2,y2) |
|
|
| `OcrTextResult` | `text: str` + 溯源: `source_name`、`usage: Usage`(0 token)、`latency_ms: int`、`call_id: str`、`raw: dict` | text 空串 = 合法"无文字";行过滤/去重/拼帧留业务侧(VT 迁移 §3 适配器) |
|
|
| `OcrLayoutResult` | `elements: list[OcrLayoutElement]`、`page_sizes: list[tuple[float,float]]`(按 page_index 索引)+ 同上溯源五件 | elements 空 = 合法"无元素";CHS 首表 = 首个 type=="table" 元素(迁移 shim 一行) |
|
|
| `OcrTextTransportResult` / `OcrLayoutTransportResult` | 上述业务字段 + `raw`(无溯源件) | transport → OcrClient 内部产物,治理字段由 OcrClient 补齐(与 EmbeddingTransportResult 先例同构) |
|
|
|
|
### 3.2 端口(ports.py 新增,均 @runtime_checkable)
|
|
|
|
```python
|
|
class OcrTextPort(Protocol): # 对应 POST /ocr/text
|
|
async def recognize_text(self, image: bytes) -> OcrTextResult: ...
|
|
|
|
class OcrLayoutPort(Protocol): # 对应 POST /parse → GET ZIP
|
|
async def parse_layout(self, image: bytes) -> OcrLayoutResult: ...
|
|
|
|
class OcrTransport(Protocol): # 协议细节;不含治理
|
|
async def recognize_text(self, *, image: bytes, source: SourceConfig, call_id: str) -> OcrTextTransportResult: ...
|
|
async def parse_layout(self, *, image: bytes, source: SourceConfig, call_id: str) -> OcrLayoutTransportResult: ...
|
|
async def check_health(self, *, source: SourceConfig) -> bool: ...
|
|
```
|
|
|
|
输入统一 `bytes`(D9: 路径读取/批量拼帧留业务侧;多后端图片形态差异封装在 transport 内)。
|
|
|
|
### 3.3 OcrClient(embedding.py 同级新文件 ocr.py)
|
|
|
|
一个 `OcrClient` 同时实现两端口(两端点打同一服务实例池,共享同一 scope 的限流/熔断/选源状态),另暴露健康预检:
|
|
|
|
| 成员 | 签名 | 说明 |
|
|
|---|---|---|
|
|
| 构造 | 与 EmbeddingClient 对称: scope/sources/selector/limiter/breaker/transport(OcrTransport)/retry/backpressure/quota_full/telemetry + now/sleep/rng 注入 | 无 pricing(OCR 无计费)、无 batch/normalize/expected_dim |
|
|
| `recognize_text(image, *, session_id=None, parent_call_id=None)` | → `OcrTextResult` | 治理循环见 §5 |
|
|
| `parse_layout(image, *, session_id=None, parent_call_id=None)` | → `OcrLayoutResult` | 同上 |
|
|
| `check_health()` | → `dict[str, bool]`(源名 → 是否健康) | **R10 销账**。逐源 GET /health(5s 超时,2xx=True),并发执行,异常=False 不上抛(预检是探测不是调用);业务 `all(r.values())` 即得 VT 启动门布尔。**注**: ARCH §7.10 原文 "check_health() -> bool 逐源健康预检" 存在签名与语义的含糊(bool 无法承载"逐源"),本设计取 dict 形态并将修订 §7.10 措辞——被否决的备选: 返回 bool(全通过才 True)信息量不足,业务无法定位坏源打日志 |
|
|
| `from_env(scope="OCR") / from_settings(OcrSettings)` | 与 EmbeddingClient 对称;显式传入 limiter/breaker 实例即共享 | |
|
|
| `aclose() / async with` | 幂等释放 transport 连接池与遥测 | |
|
|
|
|
### 3.4 配置(config.py 新增 OcrSettings)
|
|
|
|
`OcrSettings` 仿 `EmbeddingSettings`: 内含 `gateway: GatewaySettings`(复用 `{SCOPE}__{PROVIDER}__{N}__{FIELD}` 多源键、per-scope 韧性键),**无 OCR 专用键**(cache/structured/pricing 键对 OCR 无意义,装配时忽略)。CHS 键名 `OCR__MONKEY__1__BASE_URL/API_KEY/MODEL/...` 原样可用(api_key 填 "none" 惯例——MonkeyOCR 无鉴权,SourceConfig 非空校验用占位;CHS .env 同款);TPM 闸不启用(tpm=0),看门狗键不配(非流式)。
|
|
|
|
## 4. MonkeyOcrTransport(transports/monkey_ocr.py)
|
|
|
|
| 关切 | 决策 | 蓝本出处 |
|
|
|---|---|---|
|
|
| HTTP 客户端 | per-source `httpx.AsyncClient`(惰性建,keyed by source.name),`trust_env=source.trust_env`、`timeout=source.timeout_s` | **R9 销账**: SourceConfig.trust_env + `TRUST_ENV` 配置键 M1 已落地,openai_compat.py:203 已尊重,本 transport 同款;VT LAN 直连绕代理场景配 `OCR__MONKEY__N__TRUST_ENV=false` |
|
|
| multipart 上传 | `files={"file": ("image.jpg", image, "image/jpeg")}` 固定名(CHS invokers.py:496 原样;服务按内容处理,4 样本实测通过) | CHS |
|
|
| `/ocr/text` 解析 | 2xx + JSON + `content` 必须为 str,缺失/非 str → `ResultInvalidError`;空串合法 | VT(`.get("content","")` 的静默兜底**有意替换**为显式校验——P5 严禁默认值掩盖错误) |
|
|
| `/parse` 两段协议 | POST `/parse` → 校验 `success is True` + `download_url` 非空 str → GET(相对路径 urljoin base_url,绝对 URL 原样)→ ZIP | CHS invokers.py:489-530 逐段保真;相对路径显式化(取证 §1.2) |
|
|
| `_middle.json` 校验 | ZIP 内首个 `*_middle.json`;`pdf_info` 必须 list;每页: dict、`page_size` 为 2 正有限数、`para_blocks` 缺省按空列表、每块 type 为 str、bbox 为 4 有限数且 x2>x1、y2>y1 且整数化后不退化 | CHS `_finite_number`/`_parse_table_result`(invokers.py:427-479)数值防御**全量下沉**,提取面从"首表"泛化为"全元素"(取证 §1.2 证明无损) |
|
|
| 错误翻译 | 连接/超时 → `TransientError`(network_error/timeout);5xx/429 → Transient;401/403 → `SourceDeadError`;其余 4xx 与 `success!=true` → `RequestRejectedError`;响应 JSON 坏/download_url 缺 → Transient;ZIP/`_middle.json` 坏 → **`ResultInvalidError`**(坏图 ≠ 坏服务) | CHS `_translate_http_errors` + OcrResultInvalid 语义;与库四分类逐条对应 |
|
|
| `check_health` | GET `{base_url}/health`,5s 固定超时,2xx → True;任何异常 → False(不翻译不上抛) | VT ocr.py:50-62(raise 语义**有意替换**为 bool——探测不是调用,由消费方决定成败) |
|
|
|
|
## 5. OcrClient 治理循环
|
|
|
|
与 `EmbeddingClient._embed_batch` 逐段同构(第三份有限重复,理由 §2.A;行为口径完全一致):
|
|
|
|
选源(cooldown memo → try_acquire → gate try_enter)→ 调 transport → 成功: gate 记成功 + mark_progress + settle(0);`ResultInvalidError`/`RequestRejectedError`(带 status_code): gate 记成功 `count_attempt=False` 后**直接上抛**(不重试不换源,消耗调用方预算——CHS governance.py:237-239 语义);`SourceDeadError`/`TransientError`: gate 记失败 + 喂 OutcomeAwareSelector + 计 fails,达 max_attempts 抛 `AllSourcesExhausted(retry_exhausted)`,否则退避换源;无可运行源: 全 gate 拒 → `CircuitOpenError`,quota_full=fail_fast → `AllSourcesExhausted(quota_exhausted)`,双条件 stall(本地超窗 AND progress_age 超窗)→ `AllSourcesExhausted(stalled)`;取消: 探针归还 + `CancelledError` 穿透。
|
|
|
|
与 embedding 循环的**有意差异**仅三处: ① settle 恒为 0(无 token,失败也不按 est 保守结算——OCR 无计费无 TPM 闸);② 无批处理外循环;③ 喂 OutcomeAwareSelector(embedding 未接健康选源,OCR 接——多实例 LAN 服务单机可挂,M2.5 健康选源正是为此设计;喂数口径同 RetryMW: 真实成败喂、ResultInvalid/健康拒绝不喂)。
|
|
|
|
**不做清单(YAGNI,有意放弃)**: AIMD pacer(无 429 语义;并发保护走限流 max_concurrency 闸)、429 免预算(同前)、流式看门狗(非流式,总超时由 httpx timeout 承担)、响应缓存(两蓝本均无此需求;多模态缓存 key 需图像摘要,待真实需求出现再议)、结构化策略(不适用)。
|
|
|
|
## 6. G1 销账(核实结论,非新工作)
|
|
|
|
迁移文档 G1 所要求的结构化字段**在 M1/M2 已全部落地**: `GatewayUnavailableError` 携带 `scope/reason/retry_after_s/per_source_reasons`(errors.py:74-105),`CircuitOpenError`/`AllSourcesExhausted` 为其子类;retry.py 与 embedding.py 的全部抛出点均已填充(retry_after_s 读熔断后端最早恢复时刻)。M3 行动: ① OcrClient 同口径抛出(§5 已含);② 迁移文档 G1 行改"已闭"并注明 CHS 侧仅剩 10 行翻译 shim(库异常 → ProviderUnavailableError)或 tracking.py 直接 except 库异常;③ 契约测试补一条"OCR 循环抛出的 scope 级异常携带非空 per_source_reasons 与 retry_after_s"钉住。
|
|
|
|
## 7. 遥测
|
|
|
|
复用 `TelemetryEmitter` 单 helper 与 llm_calls 18 字段表(embedding 先例,无新表): `messages` = `[{"role":"user","content":"<ocr:text|layout image_bytes=N>"}]` 占位(图像 bytes 绝不入库);`response` = text 截断 200 字 / `<elements n=X pages=Y>` 摘要;tokens=0、cost=None、ttft/inter=None、cache_hit=False;失败记 error。每次调用(含失败)必录,写失败降级不冒泡。structured-logging skill 在设计批准后走一遍完成 wiki 注册(复用 schema,无新实体,预计只补 metric)。
|
|
|
|
## 8. Soak 扩展(P7 OCR 场景,验收随实现交付)
|
|
|
|
| 项 | 设计 |
|
|
|---|---|
|
|
| 源池 | 源1=7866(真)、源2=7867(真)、源3=黑洞 10.255.255.1(超时)、源4=同机坏端口(连接拒绝)——保持"故障池"精神,坏源不删 |
|
|
| 语料 | `data/soak/chs_images/` 真实图像(约 300 张,已在本机) |
|
|
| 负载 | text/parse 混合(比例计划定),harness 复用 tools/soak 既有骨架(记分板按 OCR 口径裁剪: 无 429/缓存列) |
|
|
| 不变量(草案,阈值在 plan 冻结) | 成功率(双真源在池应 ≥98%)、坏源吸流压制(尝试占比阈值)、熔断开路/恢复行为、全程 RSS 有界、取消穿透抽查 |
|
|
|
|
## 9. 非功能维度(逐条)
|
|
|
|
| 维度 | 回答 |
|
|
|---|---|
|
|
| 并发与取消 | OcrClient 无共享可变状态(cooldown memo 每实例私有,与 embedding 同);`CancelledError` 穿透: 退避 sleep/限流等待/两段 HTTP(POST 与 GET 之间取消同样穿透)全部可取消,permit 在 finally settle+release,探针在取消时归还 |
|
|
| 降级方向 | 限流/熔断后端故障 → `GovernanceBackendError` 报错不放行(铁律);遥测写失败 → warning 降级;记账侧写回失败 → `_record_quietly` 同口径降级 |
|
|
| 幂等与重复 | OCR 调用天然只读幂等,重放安全;/parse 服务端临时产物由服务自清理(实测 output_dir 在服务容器内),库不管理 |
|
|
| 持久化与原子性 | 库内无持久化;ZIP 解包在内存(BytesIO,CHS 同款),不落盘 |
|
|
|
|
## 10. 旧版行为审计(逐条裁决)
|
|
|
|
### 10.1 VT adapters/ocr.py(全 13 项行为,migrations/video-tree-trm5.md §8-13 对齐)
|
|
|
|
| 行为 | 裁决 |
|
|
|---|---|
|
|
| 同步 requests + 线程局部 Session | **替换**: httpx.AsyncClient(纯 asyncio 铁律) |
|
|
| trust_env=False 绕代理 | **保留**(per-source 配置键,§4;R9) |
|
|
| 双端点加锁轮询 | **替换**: 多源选源策略(升级) |
|
|
| 单帧失败跳过返回空 / 行级过滤(len≤1)/ 帧内去重 / "帧N:" 拼接 | **业务侧保留**(迁移文档 §3 适配器,库不做——零业务假设) |
|
|
| `.get("content","")` 静默兜底 | **有意替换**: 显式校验,缺失 → ResultInvalid(§4) |
|
|
| check_health 预检、任一不可达抛 RuntimeError | **保留能力、替换形态**: 逐源 dict[str,bool](§3.3;R10) |
|
|
| `_TIMEOUT_S=300` 硬编码 | **替换**: source.timeout_s 配置驱动 |
|
|
|
|
### 10.2 CHS invokers.py:408-552(全部行为)
|
|
|
|
| 行为 | 裁决 |
|
|
|---|---|
|
|
| 两段协议(POST /parse → GET download_url → ZIP) | **保留**(逐段保真;相对路径解析显式化) |
|
|
| `success is not True` → RequestRejected;download_url 缺 → Transient;JSON 坏 → Transient | **保留**(§4 错误翻译逐条对应) |
|
|
| `_finite_number`/page_size 正数/bbox 有限性/顺序/整数化退化校验 | **保留全量下沉**(§4) |
|
|
| 首表提取(`tables[0]`)、int bbox、OcrTableMatch/OcrParseOutcome 类型 | **替换**: 全元素列表 + float 原生 bbox(ARCH §7.10 "elements 全量";取证证明 para_blocks 无损覆盖);CHS 侧 shim: 取首个 type=="table" 元素 + int() 四元组,约 5 行 |
|
|
| 无表格页跳过继续找、全页无表 → None | **语义承接**: elements 中无 table 元素 = 合法"无表",不抛异常 |
|
|
| OcrResultInvalid → 熔断记成功、不换源、耗任务预算 | **保留**(ResultInvalidError + count_attempt=False,§5) |
|
|
| Usage(total_tokens=0, elapsed_s) | **保留语义**: usage 0 token + latency_ms 溯源字段(库 Usage 无 elapsed,latency_ms 独立承载) |
|
|
| governance.run 泛型核心接入 | **替换**: OcrClient 独立循环(§2 裁决) |
|
|
|
|
## 11. 错误处理与测试策略
|
|
|
|
失败分类归宿见 §4 翻译表与 §5 循环;测试四层:
|
|
|
|
| 层 | 内容 |
|
|
|---|---|
|
|
| unit | transport 协议解析: 用本日取证的真实响应二次构造 fixtures(`/ocr/text` JSON、`/parse` JSON、真实 `_middle.json`、坏 ZIP/坏 JSON/非有限 bbox 变体);错误翻译逐分类;相对/绝对 download_url |
|
|
| unit | OcrClient 循环: 桩 transport 注入,覆盖换源/退避/ResultInvalid 直抛(gate 记成功 count_attempt=False)/探针取消归还/stall 双条件/G1 字段非空 |
|
|
| integration | 真实服务双端点(10.77.0.20)各打通一次 + check_health;真实 Redis 后端组合(与既有 integration 同款参数化) |
|
|
| soak | P7 场景(§8),验收出口: ROADMAP §4(双端点集成测试通过 + 两项目替换路径可行) |
|
|
|
|
## 12. 落地时需同步的文档
|
|
|
|
ARCH §7.10(check_health 签名细化 + download_url 相对路径事实)、migrations/chsanalyzer.md(G1 改已闭、§4 表 OcrLayoutPort 消费 shim 更新)、migrations/video-tree-trm5.md(R9/R10 改已闭)、ROADMAP(M3 状态)、.env.example(OCR scope 样例段)。
|