单证识别运维

本页回答“单证识别上线后，日常到底怎么维护”，重点是作业是否可提取、review seed 是否靠谱、人工修正后状态是否收敛。

产品面分工

demo-frontend：主操作面，负责上传、预览、bbox 联动、字段修正与复核
admin-frontend：控制面，负责概览、队列、筛选、状态查看和详情跳转；现在也会把 Fusion runs 一并投影到 Document Recognition 历史里

当前 demo-frontend 的主操作面已采用 AI Docs Workspace 风格布局：

顶部工作台导航与状态条
工作台摘要卡片（agent、run 状态、review 队列、source preview）
左侧源文档预览与 bbox 联动
右侧字段审核与修正表单
底部文档级动作条与作业记录区

补充说明：

Outlook Index 现在直接通过 Fusion run API 创建识别任务，Document Recognition 负责把这些 run 历史投影成可 review、可持久化的单证识别记录
canonical /document-recognition/runs* route 当前直接公开提供，不再维护额外的前缀别名
如果打开的是历史投影且对象存储中的原始源文件已经不存在，左侧会明确提示源文件不可恢复，而不是假装仍可预览 bbox

日常操作

创建或选择单证识别 Agent
提交提取作业并确认源文件类型可被接受
查看 summary、issues 和字段审核种子结果
逐字段接受、修正或标记问题
确认作业级审核状态是否从 pending/flagged 收敛到可交付状态

上传前检查

先确认 3 件事：

目标 Fusion run 已经持久化了可用的 source input 与 structured output
source object key、MIME type、文件名在 Fusion inputs 中完整可读
调用方知道 review 结果是主产物，不是只拿一段模型原文

提取失败时先看什么

1. 先看源文件归一化有没有成功

如果源文件连 PDF 标准化都没过，后面 graph 不会稳定。

重点看：

MIME type 是否被识别正确
图片是否能转 RGB PDF
源文件本身是否损坏

2. 再看结构化提取是否退化到了 fallback

当前抽取链路不是“只调一次 structured output”：

优先走 structured output
失败时退到 JSON parsing
节点内部与整条 PDF 流程都有 retry

所以如果结果质量突然下降，可能不是 graph 完全失败，而是进入了 fallback 路径。

3. 最后看 review seed 是否把问题标出来了

系统当前会基于：

字段缺失
低于 LOW_CONFIDENCE_THRESHOLD
validation follow-up

自动生成：

field review payload
summary payload
issue list

如果前端看起来“什么都没错但结果明显不对”，要怀疑 review seed 投影规则是否漏报。

常见症状与动作

上传成功但没有进入可 review 状态

先看：

是否完成 PDF 归一化
graph 是否成功跑完 pdf_reporter
是否成功生成 summary payload 和 field review payload list

字段很多，但都没有被标红

先看：

estimate_field_confidence() 是否给了过高 fallback confidence
validation errors 是否覆盖到对应字段
低置信阈值是否与当前文档类型不匹配

字段被频繁误标 `missing_value`

先看：

模型抽取 text 是否为空字符串
字段 schema 是否允许空值表达
OCR/图片质量是否太差导致 text 丢失

summary 看起来正常，但 issue list 很吵

这是服务层的聚合逻辑问题，优先看：

build_document_summary_payload()
build_issue_list()
validation 错误是否过于宽泛

前端 bbox 联动异常

先看 field review payload 里的：

page_number
bbox
field_key

如果这些字段不完整，问题往往不在前端，而在 extraction schema 或服务层投影。

人工 review 的正确心智模型

人工 review 不是“给模型结果擦屁股”的附加页，而是正式运行面的最后一层控制。

当前系统的设计是：

graph 负责产出结构化候选
服务层负责把候选转成 review seed
前端负责把 seed 收敛为最终可接受结果

所以运维上不要只盯模型输出，还要盯 review seed 质量。

代码入口

路径	作用
`ai_service/document_recognition/application/projections.py`	源文件归一化、summary / issue / review seed 构建
`ai_service/document_recognition/interfaces/http/router.py`	单证识别应用 HTTP 入口
`ai_service/agents/document_extraction/graph.py`	文档抽取图主链路
`ai_service/agents/document_extraction/nodes.py`	PDF 处理、抽取、校验、报告节点
`ai_service/agents/document_extraction/schemas.py`	结构化字段与 detection schema
`demo-frontend` 文档识别页面	上传、预览、bbox 联动、字段修正
`admin-frontend` 控制面列表	队列、状态过滤、详情入口

运维侧最值得长期观察的指标

每批次上传里被拒绝的 MIME type 比例
fallback JSON parsing 的占比
FLAGGED 字段比例
缺失值与低置信问题的主要字段分布
人工修正后的最终接受率