智能文档识别平台规划方案

面向企业影像与文档智能场景的识别能力平台规划方案。平台以 OCR 与 VLM 双引擎为底座，通过 REST API、MCP 与可嵌入识别工作台（AG-UI）三种形态对外输出识别能力。本方案为从目标出发的全新设计，不绑定任何现有系统的实现；现有业务系统在方案中仅以"首个消费方"身份出现。文中七张图表均为交互式：支持缩放、语义视图、关系追踪与 PNG/SVG 导出。

一、背景与目标

1.1 建设动因

识别类能力目前散落在各业务系统中自建自用，存在三方面问题：

• 识别与业务规则耦合：抽取管线与校验规则交织在同一套代码里，换模型、调参数会波及业务逻辑，测试边界模糊；
• 能力无法复用：每个系统重复解决版面解析、手写识别、印章提取、裁片精读等同类问题，质量参差；
• 质量无闭环：识别错误依赖各系统自行发现，没有统一的 badcase 归集、评测与模型迭代机制。

1.2 平台目标

一句话定位：给一份文档，还你结构化与语义化的识别结果——OCR 负责结构与位置，VLM 负责语义与理解，双引擎一个平台，REST、MCP 与工作台三出口。

三条核心目标：

1. 识别与判断解耦：平台输出"事实"（字段、位置、置信度、证据），业务判断（合规校验、规则比对）完全留在消费方。判断类输出（一致/不一致、合规/违规）永远不出现在平台侧。
2. 识别能力服务化：企业内任何系统、任何智能体都可以通过标准契约消费识别能力，新场景上线是"新增一条类型配置"，不是"新写一套识别服务"。
3. 引擎可插拔可演进：OCR、CV、VLM 引擎都是可替换资源；接入第 N+1 个引擎只新增一个适配器，核心层零改动；模型可通过微调闭环持续变准。

1.3 设计原则

1.4 成功度量

二、业务架构

2.1 消费方

平台服务四类消费方，对应三种接入形态：

• 业务系统（REST API）：消费识别字段做业务处理。典型如结算凭证核验系统——平台读出大小写金额与印章位置，系统侧做一致性校验；
• 智能体（MCP）：对话式消费识别能力。柜员或审计在智能助手里"把这张凭证的金额读出来"，助手调 MCP 工具完成识别并组织回答；
• 终端操作者（可嵌入识别工作台 · AG-UI）：业务系统把平台提供的识别工作台嵌入自身页面，操作人员以对话方式完成上传、识别与人工复核——界面交互走 AG-UI 协议（第三出口），权威数据仍凭 log_id 走 REST/MCP 获取；
• 平台运营方：管理文档类型、评测集、引擎版本与调用配额。

2.2 能力分层

划分标准：“怎么读准"进平台文档类型，“读出来的对不对"留在消费方。版式先验（如票据金额栏位置）属于"怎么读准”，沉淀为平台文档类型，全行复用；合规规则属于业务立场，不得进入平台。

2.3 质量闭环

业务架构的灵魂是 badcase 闭环：消费方复核标记 → 平台归集台账 → 人工标注修正 → 沉淀 golden 评测集 → 驱动文档类型调优与引擎微调 → 评测通过后灰度上线 → 通知消费方。闭环转起来，平台从成本中心变成越用越准的资产。

全屏打开 ↗

三、应用架构

3.1 应用组件

3.2 统一结果模型（契约核心）

所有引擎输出归一到同一对象模型，这是 API 与 MCP 共享的地基：

{
  "document_id": "doc_8f3a",
  "pages": [
    {"page_no": 1, "blocks": [
      {"bbox": [0.12, 0.31, 0.68, 0.36], "type": "handwriting",
       "text": "青岛市北区……", "confidence": 0.71, "source_engine": "paddleocr-vl"}
    ]}
  ],
  "fields": [
    {"name": "merchant_name", "value": "……", "confidence": 0.64,
     "needs_review": true, "evidence_block_ids": ["blk_12"]}
  ],
  "meta": {"log_id": "…", "doc_type": "voucher-v1", "engines_used": […],
           "artifacts_uri": "minio://…", "latency_ms": 4200}
}

三个关键字段：confidence（字段级置信度）、needs_review（投票不一致即标记，宁缺勿错）、evidence_block_ids（每个字段可回溯到原图证据块，审计场景刚需）。

3.3 MCP 设计要点

• 工具粗粒度：upload_document（拿 doc_id）、recognize_document、extract_fields、compare_documents、query_result；文件走引用不传裸 base64；
• 结果作为 MCP resources 暴露，智能体可按 URI 二次取用；
• tool description 即给大模型的说明书，明确"何时该用、何时不该用”；
• 每次工具调用记调用方身份并进审计日志。

全屏打开 ↗

3.4 AG-UI 识别工作台：可嵌入的对话式识别界面

第三出口面向终端操作者：不是所有人都在智能助手里对话，更多时候是在业务系统页面里直接办事。AG-UI（Agent-User Interaction Protocol）是"智能体后端 ↔ 前端界面"的标准协议——平台实现该协议的会话端点，并交付一个可被任意业务系统嵌入的识别工作台前端，操作人员上传文档、看到流式识别过程、在界面上完成人工复核。

设计要点：

• 端点即协议：POST /agent/run 接收 RunAgentInput（会话 ID、消息历史、共享状态），以 SSE 事件流返回（RUN_* 生命周期、TEXT_MESSAGE_* 流式文本、TOOL_CALL_* 工具过程、STATE_SNAPSHOT 状态快照）——标准 AG-UI，前端实现可整体替换；
• 三出口单一实现：会话内的工具（列类型、抽取字段、查历史）直接调用与 REST/MCP 相同的业务层，工作台只是协议之上的第三个壳；
• 客户端权威状态：共享状态（doc_id、字段、复核标记）由前端持有、每轮全量上送，服务端无会话粘性——平台不成为有状态单体；
• 人在回路：needs_review 字段驱动复核表单，复核意见作为新消息进入下一轮会话，形成"识别 → 复核 → 确认"闭环；
• 嵌入契约：业务系统以 iframe 嵌入，URL 注入访问凭证；界面只管操作，权威结果凭 log_id 走 REST/MCP 获取（界面与数据解耦）；调用方/用户/机构级权限随调用方管理演进（凭证携带身份声明）。

全屏打开 ↗

3.5 MCP 与企业服务总线（ESB）的协同

企业已有传统 ESB，系统间接口调用统一经其转发。MCP 引入后的关系定位：两者不是替代关系，而是架构中两段不同的接线——ESB 管"系统之间怎么互相调用"（服务治理层），MCP 管"智能体怎么调用能力"（AI 接入层）。MCP Server 站在前面作为智能体接入层，它发起的跨系统服务调用仍然走 ESB，就像当年移动端渠道出现时，移动网关背后照样调 ESB 服务——智能体只是又一种前端。

MCP Server 的归属：跟着能力走，属于能力提供方系统。本平台的 MCP Server 是平台应用的组件之一，部署在平台命名空间、与 REST API 共享同一套编排实现；智能体平台只做消费方，不替提供方建工具适配，避免长出绕开治理的影子集成网。分工与 ESB 治理经验同构：工具语义（描述、参数 Schema、错误码）由能力提供方定义，鉴权/审计/限流等治理能力可集中——中期由 ESB/APIGW 原生托管 MCP 协议绑定时，这一分工不变。

调用边界：MCP Server 调用本平台内部能力（MCP → 编排层）属系统内调用，不经 ESB；跨系统调用（如经 ESB 到影像平台调阅影像、回写核心系统）一律走 ESB，纳入既有治理。两层审计各司其职：MCP 层记录"哪个智能体、代表哪个用户、调了什么工具"，ESB 层照旧记录服务调用，日志 ID 串联。

全屏打开 ↗

3.6 文档类型化接入：按类型识别输出

识别接口按**文档类型（文档类型）**输出对应字段集——发票返回发票字段、询证函返回询证函字段，文档类型与输出字段在平台管理端可配置。这是编排层类型化的直接应用：输出字段 = 文档类型中声明式定义的字段 Schema。

API 形态：按能力大类分端点，大类内按文档类型参数化。 大类与文档类型是两个正交维度——大类区分任务形态（识别、比对、批量），文档类型区分票种（发票、询证函、凭证）：

POST /v1/documents          // 文档接入：上传拿 doc_id、查询、状态（REST 资源型）
POST /v1/recognize          // 识别抽取大类：单文档进、字段集出
  { "file": "…", "doc_type": "invoice" }        // → 发票字段
  { "file": "…", "doc_type": "confirmation" }   // → 询证函字段
POST /v1/compare            // 比对大类：双文档进、差异结论出（doc_type 同样参数化）
POST /v1/batches            // 批量异步大类：文档集进、任务句柄出（引用文档类型）
GET  /v1/doc-types/{id}/schema  // 文档类型契约下发

划分判据：请求/响应骨架是否同构。 同构（单文档进、字段出）归入识别大类，用类型参数区分文档种类——发票、询证函、凭证互不开端点；不同构（双文档进差异出、批量任务句柄、文档资源管理）才开新大类。由此保留两个收益：新文档类型上线 = 管理端加类型，不发版；新任务形态出现才动 API 面。MCP 工具按大类映射（upload_document / extract_fields / compare_documents），保持粗粒度。印章提取等"输出为位置与图像证据"的能力首选纳入类型化配置（印章作为特殊字段类型，值 = 位置 + 裁片引用），仅当输出形态无法归入统一结果模型时才开专项端点，避免大类膨胀。

动态字段的契约机制（此设计成败的关键）：每个类型携带正式的字段 Schema 作为一等契约下发——GET /v1/doc-types/{id}/schema 随时可取，SDK 按文档类型生成强类型客户端；字段变更守纪律（加字段 = 文档类型小版本兼容升级；改字段语义/删字段 = 新大版本，消费方显式迁移）；管理端保存文档类型时即做 Schema 校验（命名规范、类型合法、必填约束自洽），脏配置进不了生产。文档类型配置模型示例：

{
  "id": "invoice", "version": "3.2",
  "fields": [
    {"name": "invoice_number", "type": "string", "required": true,
     "extraction": {"mode": "ocr_direct"},
     "post_rules": [{"type": "regex_validate", "pattern": "^[0-9]{8,20}$"}]},
    {"name": "amount", "type": "decimal", "required": true,
     "extraction": {"mode": "cross_engine_vote"}}
  ],
  "layout_priors": {"amount_region": "…"},
  "routing": {"preference": ["ocr", "vlm"], "fallback": true}
}

配置化的深度与边界：配置表达"结构与参数"，代码表达"算法与流程"——把逻辑塞进配置端会演化出没人敢改的"配置编程语言"，把结构参数写死代码又会让新场景接入周期失控。

两条配套约束：① 类型变更与代码变更同级对待——管理端配置同样走"草稿 → golden 集评测通过 → 发布"，不允许直接改生产文档类型；② 配置出来的字段同样携带 confidence / needs_review / evidence_block_ids，配置化不绕过质量纪律。自然扩展（按需）：doc_type: "auto"——混合批次先经 CV 引擎文档分类再路由到对应文档类型，文档类型机制天然支持。

3.7 提示词管理：渲染产物与护栏

VLM 识别的提示词不是独立维护的字符串，而是文档类型的渲染产物：字段定义是数据，提示词模板是模板，最终发给 VLM 的提示词 = 渲染器（模板 + 字段定义 + Schema 约束）生成——与文档类型同版本、同生命周期。

关键机制是渲染时注入：模板引用受控变量插槽（{{fields_schema}} 等）而非硬编码字段清单——文档类型加字段，下次渲染自动带上，不存在"字段加了、提示词忘了同步"的不一致。由此买到三样东西：一致性（字段与提示词同源）、可审计（结果 ↔ 类型版本 ↔ 渲染后提示词绑定，历史可重放）、缓存友好（同版本渲染结果可缓存）。

五条护栏（缺一条，动态提示词就是事故源）：

1. 模板与数据分离：字段清单永远经渲染注入，不写死在模板里；
2. 受控变量插槽：模板只支持平台预定义变量（fields、schema、language、context），不允许任意表达式——配置端不能演化成编程语言；
3. 系统级指令不可配：输出必须 JSON、不得编造等平台级纪律由代码持有，管理端模板覆盖不到；
4. 评测门禁覆盖提示词变更：提示词有牵一发动全身的隐性风险（改一个字段描述可能让整页其他字段退化），正确工作流是草稿 → golden 集回归 → 新旧 A/B 对比 → 发布，不允许直接改生产；
5. 提示词版本 = 类型版本：不存在独立的提示词版本，回滚文档类型即回滚提示词。

由此，提示词调优进入与模型迭代同一条质量闭环：badcase 台账发现字段系统性读错 → 定位字段描述歧义或模板问题 → 管理端改草稿 → golden 集验证提升且无回归 → 发布新类型版本。提示词从代码里的字符串变成可运营、可度量、可回滚的资产——这是文档类型化架构对 VLM 侧最大的红利。

四、技术架构

4.1 分层结构

自上而下四层 + 一条旁路 + 一个横切面：

• 接入层：REST 网关与 MCP Server，只做协议、鉴权与流控；
• 编排层：类型引擎（场景 = 配置而非代码）、引擎路由（按精度/成本/健康度选引擎）、投票融合与降级决策；
• 能力与适配层：对上暴露稳定的能力契约，对下吸收引擎差异——坐标归一（统一像素系）、置信度标定（引擎分数可比化）、块类型映射（统一版面词表）；
• 引擎层：可插拔资源，多版本灰度共存；
• 训练流水线（旁路）：标注集管理 → 微调训练 → golden 集评测 → 版本注册，产出新引擎版本进入引擎层；
• 横切治理：鉴权、审计、配额、监控在接入层统一实施。

4.2 双引擎协作模式

编排层固化的三种文档类型模式：

1. OCR 直出：印刷体、清晰扫描，一步到位——多数页面走这条，成本最低；
2. OCR 定位 + VLM 精读：OCR 出版面与 bbox，定位目标区域裁片增强后交 VLM 读字段——手写、印章、模糊区域走这条；
3. VLM 全读：无版式规律的语义理解与文档比对，整图交 VLM。

4.3 路由、投票与降级

• 成本路由：OCR 能解决的字段不过 VLM；冲突或低置信才升级，控制推理成本；
• 跨引擎投票：不同架构的模型错误模式不相关，关键字段（金额、户名）双引擎互验远比同模型多读可靠；
• 降级链：引擎超时/异常 → 重试 → 备用引擎 → 整图直读兜底；仍失败返回明确错误码；投票不一致字段标 needs_review 走人工。

全屏打开 ↗

五、技术栈选型

选型独立于任何现有系统评估，按扩展性、成熟度、开发效率、性能、运维成本、信创合规六个维度论证。

5.1 选型决策表

5.2 Python 与 Go：主体与边缘的分工

决策：平台主体语言为 Python；Go 不作为平台语言，仅作为特定边缘组件的按需选项——按瓶颈引入，不按偏好引入。

先看负载画像：处理一份文档的时间分布为——引擎推理（GPU，秒级）> VLM 调用（秒级）> 预处理（百毫秒级）> 编排逻辑（毫秒级）。延迟大头在引擎、吞吐瓶颈在算力，编排层是 IO 密集的轻计算层，FastAPI 的 asyncio 在凭证级调用量下余量充足；Go 的并发优势在高 RPS 网关场景才兑现，此处用不上。更关键的是语言分裂的代价：训练、微调、评测、预处理全在 Python 生态，编排层若用 Go，模型迭代链路被切成两半，每次调整都要跨语言维护两份实现——平台的核心竞争力（文档类型快速迭代 + 模型持续变准）都长在 Python 生态里。

公允对照 Go 的真实优势与平台需求：

分层语言分工：

组件改写为 Go 的三条触发判据（不满足任何一条则不引入，第二语言的维护成本是持续的）：

1. 实测瓶颈：压测显示 Python 组件在目标 SLA 下 p99 不可接受，且进程池、缓存等优化已到头；
2. 部署形态：组件需以单二进制下沉到无 Python 运行时的环境；
3. 纯网络转发：组件为无状态转发/聚合、无业务语义，用 Go 实现反而更简单。

补充选项：若企业平台工程规范倾向 Go 网关，可接受"Go 接入壳 + Python 编排核"的混合架构——Go 只做协议接入与流控，全部业务语义在 Python；前提是契约（OpenAPI）稳定且团队双语言人力齐备。

5.3 多智能体：不引入的架构决策

决策：识别平台不引入自主智能体编排（含多智能体）；平台是工具/能力提供方——被智能体调用的那一端——自身不成为智能体。跨工具的动态编排属于消费方智能体平台的职责。

期望"智能体"带来的能力，平台已用确定性等价物覆盖：多读投票（应对幻觉）、needs_review 复核标记（自我校验）、降级链（自主恢复）、文档类型路由（自适应选择）——效果可度量、路径可复现。

边界条件：若未来出现开放式任务（如"审计整卷信贷档案"需运行时分解、交叉比对、汇总结论），正确做法是在消费方/业务方案层增设智能体编排——由它规划步骤并循环调用平台的 MCP 工具，识别平台继续作为被调用的工具集，分层不变。

5.4 维度小结

• 扩展性：引擎适配层 + 注册表保证水平扩展（多引擎）与垂直扩展（多副本 HPA）两条路径都开放；
• 成熟度：全部选型均为生产级验证过的主流组件，无实验性依赖；
• 开发效率：单一语言（Python）覆盖业务编排到模型迭代，文档类型化让新场景以天级接入；
• 性能：计算密度在引擎层（GPU），编排层 IO 密集（异步足够），分层各自优化互不拖累；
• 运维成本：一期落地组件仅 3 个（平台服务、MinIO、PG；引擎复用已有部署），Redis 二期引入；
• 信创：框架（PaddlePaddle）与芯片适配（昇腾/昆仑）均国产化可选。

六、数据架构

6.1 存储分工

6.2 核心数据模型（表清单）

6.3 证据链与数据反哺

• 每个字段的 evidence_block_ids 指向块级记录，块级记录指向对象存储中的裁片与引擎原始输出——任何结论可重放验证；
• 低置信字段与复核标记自动进入 badcase 台账，人工标注后沉淀 golden 集；golden 集同时服务引擎评测、类型回归与微调训练三类消费；
• 数据生命周期：原始文档与证据按监管留存期归档；引擎原始输出可按期降冷，统一结果永久在线。

全屏打开 ↗

七、部署架构

7.1 K8s 拓扑

• 平台命名空间：统一接入（Ingress/TLS）+ 平台服务（API/MCP/编排，无状态多副本 + HPA）+ 存储组件（MinIO/PG/Redis，或接共享实例）；
• GPU 节点池：PaddleOCR-VL 等重推理产线，按负载独立扩缩容，容器独占卡（PaddleOCR-VL 已有部署，直接接入复用）；
• CPU 节点池：CV 任务与轻量 OCR；
• VLM：走大模型平台统一算力，平台不重复建设推理资源。

7.2 版本化与发布

• 模型版本 = 不可变镜像 tag：训练流水线产出带版本号的 serving 镜像，Harbor 承载，回滚即镜像回滚；
• 发布门禁：新引擎版本必须先在评测环境跑 golden 集回归，字段准确率不退化方可灰度；灰度通过端点 model_version 参数路由，默认 stable；
• 流水线：Jenkins 构建镜像 → Harbor → ArgoCD 声明式同步，发布与回滚均为 Git 变更，全程可审计。

7.3 环境规划

SIT（联调，黄金集回归常驻）/ UAT（业务验收 + 灰度验证）/ 生产（灰度发布 + 双版本并行）。生产网与研发网物理隔离，制品经镜像仓库摆渡。

全屏打开 ↗

八、演进路径

九、风险与对策