docs: add M3 OCR implementation plan and telemetry metric

2026-07-21 22:11:33 -04:00
parent dfc013e8ed
commit e51f0773ac
6 changed files with 263 additions and 3 deletions
@@ -0,0 +1,17 @@
+---
+type: metric
+node_id: metric:ocr-call-success
+title: "OCR 治理调用成功率与错误分类分布"
+date: 2026-07-21
+---
+
+# OCR 治理调用成功率与错误分类分布
+
+- **数据源**: `llm_calls` 表(复用,无新表;M3 设计 §7)。OCR 行特征: `provider="monkey"`、tokens=0、cost=NULL、ttft/inter=NULL、cache_hit=0;`messages` 为 `<ocr:text|layout image_bytes=N>` 占位(图像 bytes 绝不入库),`response` 为 text 截断 200 字 / `<elements n=X pages=Y>` 摘要。
+- **埋点位置**(唯一路径,禁止旁路): `src/polygateway/ocr.py` OcrClient 治理循环内经 `TelemetryEmitter.emit_attempt`(单 helper 铁律),每次尝试(成功/失败/取消)必录;写失败 warning 降级不冒泡。
+- **指标口径**:
+  - 调用成功率 = `error IS NULL` 行数 / 总行数(按 provider="monkey" 过滤,窗口按 run/日);
+  - 错误分类分布 = `error` 非空行按异常类名前缀(Transient/SourceDead/RequestRejected/ResultInvalid/CircuitOpen/AllSourcesExhausted)归组计数;
+  - 端点维度经 `messages` 占位前缀(`ocr:text` vs `ocr:layout`)区分;
+  - 延迟 = `latency_ms` 分位数(text 与 layout 分列——layout 含两段 HTTP,显著更慢)。
+- **评估基线**: 待 P7 OCR soak 首跑后建立(健康双真源池预期成功率 ≥98%,故障池口径阈值在 P7 计划冻结);单调用延迟基线以 integration 实测为初值(2026-07-21 手测: /ocr/text 约 3-5s,/parse 约 5-15s)。