From 42b7f0defc7451430c1918347e92d856104df094 Mon Sep 17 00:00:00 2001 From: iomgaa Date: Thu, 22 Oct 2026 00:07:54 -0400 Subject: [PATCH] docs: register parse_document in telemetry schema and alignment targets --- research-wiki/index.md | 2 +- research-wiki/log.md | 1 + research-wiki/metrics/call-telemetry-coverage.md | 2 +- research-wiki/metrics/ocr-call-success.md | 6 +++--- research-wiki/schemas/llm-calls.md | 2 +- tools/check_wiki_alignment.py | 1 + 6 files changed, 8 insertions(+), 6 deletions(-) diff --git a/research-wiki/index.md b/research-wiki/index.md index 1618647..1b681b6 100644 --- a/research-wiki/index.md +++ b/research-wiki/index.md @@ -1,6 +1,6 @@ # Research Wiki 索引 -> 自动生成，更新时间：2026-10-22 02:45 UTC +> 自动生成，更新时间：2026-10-22 04:02 UTC ## design (49) - [1.3.4 推理意图与测试证据设计](designs/2026-09-09-134-thinking-contracts-design.md) `design:2026-09-09-134-thinking-contracts-design` diff --git a/research-wiki/log.md b/research-wiki/log.md index eee39cc..629542e 100644 --- a/research-wiki/log.md +++ b/research-wiki/log.md @@ -174,3 +174,4 @@ - [2026-10-22 02:35 UTC] 重建索引: 123 篇页面 - [2026-10-22 02:45 UTC] 新增边: plan:2026-10-21-issue34-ocr-document --implements--> design:2026-10-21-issue34-ocr-document-design - [2026-10-22 02:45 UTC] 重建索引: 124 篇页面 +- [2026-10-22 04:02 UTC] 重建索引: 124 篇页面 diff --git a/research-wiki/metrics/call-telemetry-coverage.md b/research-wiki/metrics/call-telemetry-coverage.md index 1f814f0..0531e10 100644 --- a/research-wiki/metrics/call-telemetry-coverage.md +++ b/research-wiki/metrics/call-telemetry-coverage.md @@ -11,7 +11,7 @@ date: 2026-07-20 | 指标 | 确定性阈值／证据 | 实际 live 基线 | | --- | --- | --- | -| 三个无推理入口成败行档位 NULL | embed、recognize_text、parse_layout 真实 client→emitter→临时 SQLite，非空失败／成功计数与 NULL 全部成立，契约要求100% | 待首次实际运行，不填伪百分比 | +| 三个无推理入口成败行档位 NULL | embed、recognize_text、parse_layout、parse_document 真实 client→emitter→临时 SQLite，非空失败／成功计数与 NULL 全部成立，契约要求100% | 待首次实际运行，不填伪百分比 | | chat 阳性 | 糖失败 auto、显式意图失败、nearest 成功实际档均精确匹配，要求100%；防恒 NULL 假绿 | 待首次实际运行 | | 四种行来源 | 真实成功=applied；失败=effective；cache_hit／scope终态=本次请求级 | 排除缓存／失败后才可做实际档分析 | | live 覆盖 | 逐轮 PASS／FAIL／UNCOVERED、计划轮数与缺轮分别统计；必需单元不因 pytest exit 0 自动放行 | 未执行；UNKNOWN／缺轮／skip 不能记PASS | diff --git a/research-wiki/metrics/ocr-call-success.md b/research-wiki/metrics/ocr-call-success.md index b058f0c..4d575c1 100644 --- a/research-wiki/metrics/ocr-call-success.md +++ b/research-wiki/metrics/ocr-call-success.md @@ -7,11 +7,11 @@ date: 2026-07-21 # OCR 治理调用成功率与错误分类分布 -- **数据源**: `llm_calls` 表(复用,无新表;M3 设计 §7)。OCR 行特征: `provider="monkey"`、tokens=0、cost=NULL、ttft/inter=NULL、cache_hit=0;`messages` 为 `` 占位(图像 bytes 绝不入库),`response` 为 text 截断 200 字 / `` 摘要。 +- **数据源**: `llm_calls` 表(复用,无新表;M3 设计 §7)。OCR 行特征: `provider="monkey"`、tokens=0、cost=NULL、ttft/inter=NULL、cache_hit=0;`messages` 为 `` 占位(图像 bytes 绝不入库),`response` 为 text 截断 200 字 / `` 摘要。 - **埋点位置**(唯一路径,禁止旁路): `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,显著更慢)。 + - 端点维度经 `messages` 占位前缀(`ocr:text` / `ocr:layout` / `ocr:document`)区分,或直接用 `operation` 列(`recognize_text` / `parse_layout` / `parse_document`);文档行的 `response` 摘要为 ``,**不含正文**; + - 延迟 = `latency_ms` 分位数(text、layout、document 分列——后两者含两段 HTTP,显著更慢;document 随页数增长,约 1.5 s/页[2026-10-21 实测,n=3、无争用,非 SLA],不要与 layout 混算分位数)。 - **评估基线**: 待 P7 OCR soak 首跑后建立(健康双真源池预期成功率 ≥98%,故障池口径阈值在 P7 计划冻结);单调用延迟基线以 integration 实测为初值(2026-07-21 手测: /ocr/text 约 3-5s,/parse 约 5-15s)。 diff --git a/research-wiki/schemas/llm-calls.md b/research-wiki/schemas/llm-calls.md index 3645b96..1e3ad0f 100644 --- a/research-wiki/schemas/llm-calls.md +++ b/research-wiki/schemas/llm-calls.md @@ -32,7 +32,7 @@ date: 2026-07-20 | thinking_observation | TEXT | 本次推理是否真的发生的三态裁定(2026-08-25,issue #16/#17);`observed` / `absent` / `unknown`。见下方口径 | | reasoning_effort | TEXT | 按四种行来源记录的推理意图／实际编码档位(2026-09-09 澄清,issue #20/#26);八档 `Effort` 字面量之一,NULL = 调用方未表态(与 `none`「明确要求不推理」不可混同)。见下方口径 | | scope | TEXT | 池名(2026-09-09,issue #19/#23);Emitter 构造期注入,三类行都带,**不拿 `source_name` 顶替** | -| operation | TEXT | `chat` / `embed` / `recognize_text` / `parse_layout`,由调用点给定;与 `PolyGatewayError.operation` 是两个语义,链路上不得读后者填本列 | +| operation | TEXT | `chat` / `embed` / `recognize_text` / `parse_layout` / `parse_document`(2026-10-22,#34),由调用点给定;与 `PolyGatewayError.operation` 是两个语义,链路上不得读后者填本列 | | logical_call_id | TEXT | 一次逻辑调用一个 ID(重试／换源／重问／分批共享);上下文缺席落 NULL,**不造 ID** | | event_kind | TEXT | 三态 `attempt` / `cache_hit` / `terminal_failure`——三类行的唯一机械判据。见下方口径 | | http_status_code | INTEGER | 失败 attempt 行的实收状态码(中转改写过就记改写后的,**不猜回原值**);成功行与终态行恒 NULL,且 200 也可能是失败行(MonkeyOCR `success != true`) | diff --git a/tools/check_wiki_alignment.py b/tools/check_wiki_alignment.py index 11957ca..ceeb4eb 100644 --- a/tools/check_wiki_alignment.py +++ b/tools/check_wiki_alignment.py @@ -41,6 +41,7 @@ _SIGNATURE_TARGETS = [ ("EmbeddingClient.embed", EmbeddingClient.embed), ("OcrClient.from_env", OcrClient.from_env), ("OcrClient.recognize_text", OcrClient.recognize_text), + ("OcrClient.parse_document", OcrClient.parse_document), ("gather_bounded", polygateway.gather_bounded), ("register_provider", register_provider), ]