智能文档识别平台建设实施计划与详细方案

本文是《智能文档识别平台规划方案》的落地实施文档：规划方案回答"建什么、为什么这样建"，本文回答怎么建、什么节奏、做到什么程度算完成。所有架构决策以规划方案为准，本文不重复论证，只做实施展开。

一、建设原则

• 契约先行：统一结果模型与评测口径最先定版（M1），其后所有工作以此为验收基准；
• 演进式交付：一期到三期每期独立可交付，任何一期结束后暂停都不产生半成品负债；
• 评测门禁从第一天生效：一期上线即带 golden 集回归，“无评测集的场景不上线"从一期就是纪律而非愿景；
• 消费方牵引：每期以真实消费方场景验收，不以技术组件完成为验收标准。

二、总体建设路线

全屏打开 ↗

三、一期详细方案

3.1 范围界定

做：统一结果模型定版；编排引擎与双引擎适配（PaddleOCR-VL + VLM，VLM 经大模型平台 OpenAI 兼容协议接入）；提示词渲染器（类型模板 + 字段描述渲染，规划方案 3.7 的护栏一期即生效）；首个场景类型（结算凭证类，含手写字段的 OCR 定位 + VLM 精读）；REST API 与能力网关；管理端最小集（类型 CRUD + 发布门禁）；golden 评测集与 CI 门禁；SIT/UAT 环境部署。

做（追加）：MCP Server（原计划二期，应要求提前——Streamable HTTP 四工具：upload_document / recognize_document / extract_fields / query_result，与 REST 共用 services 业务层，双出口单一实现）；AG-UI 识别工作台（原计划二期，应要求提前——POST /agent/run 会话端点 + 规划器 + 三工具 + 可嵌入 React 工作台前端，三出口成型，见 3.7）。

不做（但接口预留）：跨引擎投票与复杂路由（二期）、智能体试点接入与 OAuth 对接（二期）、批量异步（二期）、训练流水线（三期）、消息队列（按需）、Redis（二期引入——一期限流用 PG 计数、引擎并发用 asyncio 进程内信号量）。一期与二期的切分是**“多引擎接入 → 多引擎协同决策”**：一期双引擎各自可用、类型声明三种基础模式（OCR 直出 / VLM 全读 / OCR 定位+VLM 精读），二期才有跨引擎投票这类组合决策。预留方式：编排引擎的引擎调用走适配器接口而非直连；融合器接口预留投票扩展点；结果模型字段（engines_used、needs_review）一期即落库。

3.2 工程结构

后端单仓（Python 3.12+，uv 管理）+ 两个独立前端工程：

idrp-backend/
├── server/            # FastAPI 应用：网关、管理 API、编排入口
│   ├── services.py    # 公共业务层：REST / MCP / AG-UI 三出口单一实现
│   ├── mcp_server.py  # MCP Server 独立进程（:8001/mcp，Streamable HTTP）
│   ├── api/           # REST 路由（/v1、/admin/v1）与 AG-UI 端点
│   └── agent/         # AG-UI 运行时：events / tools / runtime / api
├── core/              # 领域层：结果模型、类型引擎、编排状态机、融合器
├── adapters/          # 引擎适配器（paddleocr_vl + vlm）+ 注册表
├── preproc/           # 预处理：栅格化
├── eval/              # golden 集管理、准确率计算、门禁脚本
└── tests/             # 契约与流程测试（离线假引擎）

idrp-frontend/         # 管理台前端（Vue 3 + Vite：类型编辑/评测/发布门禁）
idrp-workbench/        # 识别工作台前端（React 18 + TS + AntD 5，可嵌入，见 3.7）

3.3 数据库详细设计（核心表）

延续规划方案 6.2 的域划分，一期落 7 张核心表（PostgreSQL，均带 created_at/updated_at）：

-- 文档域
documents(id, doc_id UNIQUE, source_caller, original_uri,   -- MinIO 对象
          mime_type, page_count, checksum, status)           -- uploaded/parsed/failed

-- 识别域
recognition_requests(id, log_id UNIQUE, doc_id FK, doc_type,
          doc_type_version, status,                       -- 见 3.9 状态机
          engines_used JSONB, latency_ms, error_code)
recognition_results(id, request_id FK, unified JSONB,        -- 统一结果模型全文
          field_count, review_count)

-- 证据域
result_blocks(id, request_id FK, page_no, block_type,
          bbox_norm JSONB,                                   -- 归一化坐标 [0..1]
          text, confidence, source_engine, artifact_uri)

-- 配置域
doc_types(id, doc_type, version, status,                      -- draft/released/deprecated
          definition JSONB,                                  -- 字段/提示词/版式先验/路由
          released_at)
engine_registry(id, engine_id, version, capabilities JSONB,
          endpoint, cost_profile, health, enabled)
golden_sets(id, set_id, doc_type, doc_uri, expected JSONB)
eval_runs(id, doc_type, doc_type_version, accuracy JSONB,
          passed, ran_at, trigger)                           -- ci/release/manual

3.4 统一结果模型定版（一期冻结内容）

以规划方案 3.2 的 JSON 为基线，一期补充冻结四点：坐标一律归一化到 [0,1]（相对页宽高，保留 4 位小数）；confidence 取值 [0,1]，未标定引擎给保守默认 0.5 并在 meta 标注 calibrated: false；block_type 词表一期含 text / handwriting / table / seal / figure / signature；fields[].value 统一字符串承载，数值与日期格式由类型 Schema 校验。定版后任何变更走大版本。

3.5 REST API 契约（一期）

错误码体系：4xx 消费方错误（INVALID_FILE、RECIPE_NOT_FOUND、QUOTA_EXCEEDED），5xx 平台错误（ENGINE_TIMEOUT、ENGINE_UNAVAILABLE、INTERNAL）；所有响应带 log_id；限流按调用方配额（一期以 PG 计数实现，二期 Redis 全局化）。

3.6 MCP Server（提前实现）

独立进程 server/mcp_server.py（uv run python -m server.mcp_server，默认 :8001，端点 /mcp），官方 MCP Python SDK（2.x MCPServer）+ Streamable HTTP 传输：

• 四个粗粒度工具：upload_document（base64 内容 → doc_id）、recognize_document（统一结果全文）、extract_fields（字段轻量视图）、query_result（历史查询）；
• 与 REST 共用 server/services.py 业务层——双出口单一实现，工具层只做协议适配不写业务；
• 工具 docstring 即 LLM 说明书（何时该用、参数含义、needs_review 提示），参数 schema 由类型注解自动生成；
• 错误契约与 REST 同构（error_code/error_msg 结构化返回，不抛协议错误）；
• 调用方鉴权与网关接入（OAuth 2.1 资源服务器语义）随二期智能体试点完善。

3.7 AG-UI 识别工作台（提前实现）

第三出口：面向终端操作者的对话式识别界面（规划方案 3.4）。后端 server/agent/ 四模块 + 独立前端工程 idrp-workbench。

后端（AG-UI 运行时）：

• 事件层 events.py：AG-UI 协议事件构造——RUN_STARTED/FINISHED/ERROR（生命周期）、TEXT_MESSAGE_START/CONTENT/END（流式文本，按块拆分）、TOOL_CALL_START/END（工具过程）、STATE_SNAPSHOT（状态快照），SSE data: 帧下发；
• 端点 /agent/run（agent/api.py）：接收 RunAgentInput（threadId、runId、messages、state），流式返回事件；X-Agent-Token 头做嵌入鉴权（骨架期全局 token，随调用方管理演进为按调用方签发的 JWT，携带用户/机构声明）；
• 规划器 runtime.py：默认规则规划器（离线可测：上传 → 选类型 → 识别 → 复核的会话状态机，类型词优先、上传通知重置残留状态、单轮动作数上限防失控），IDRP_AGENT_PLANNER=qwen 可切 LLM 函数调用规划（复用 VLM 通道）；
• 工具层 tools.py：list_doc_types / extract_fields / query_result 三工具——与 REST、MCP 调同一 services 业务层（三出口单一实现）；工具错误以结构化契约返回并转成可见文本事件；
• 交互细节：长耗时识别先发"正在识别"文本事件再执行工具（多页文档 1–2 分钟期间界面不失联）；每次识别的 fields/log_id 经 STATE_SNAPSHOT 下发驱动界面。

前端（idrp-workbench）：

• React 18 + TypeScript + Vite + Ant Design 5；自研 ~150 行 AG-UI 事件客户端（协议本身轻量，规避组件库 API 快速演进风险；后端是标准 AG-UI，可随时换 CopilotKit 等框架接入）；
• 会话界面：上传区（REST 拿 doc_id 进共享状态）→ 对话气泡（流式）→ 工具执行卡（进行中/耗时）→ 字段表（needs_review 高亮）→ 人工复核表单（复核意见作为新消息回传）→ 会话内识别记录（点击回看）；
• 嵌入契约：/workbench?token=… 注入凭证（localStorage + X-Agent-Token 头）；生产与平台服务同域部署，SSE 经代理需关闭缓冲（nginx proxy_buffering off）。

全屏打开 ↗

分期演进：二期补 postMessage 结果回传、按调用方/用户/机构的权限过滤（list_doc_types 只返回授权类型）、嵌入方自助接入；比对能力（compare_documents）落地后增设比对视图（同工程分流，见规划方案 3.4 视图拆分原则）。

3.8 管理端详细设计（一期最小集）

管理端服务平台运营方与接入人员，是文档类型化架构（规划方案 3.6）的运营界面。一期定位"最小但完整”：类型发布门禁的完整流程必须有界面，其余能力 API 优先、界面跟进。

功能模块（按优先级）：

管理 API（/admin/v1/*，与能力 API 隔离部署路径，独立管理鉴权）：

/admin/v1/doc-types          GET/POST/PATCH   类型草稿 CRUD
/admin/v1/doc-types/{id}/release   POST       发布（内部先触发评测门禁，未通过则 409）
/admin/v1/doc-types/{id}/rollback  POST       回滚至历史版本
/admin/v1/golden-sets      GET/POST         样本与期望标注管理
/admin/v1/eval-runs        GET/POST         评测触发与记录查询
/admin/v1/engines          GET/PATCH        注册表查看与启停
/admin/v1/callers          GET/POST/PATCH   凭证与配额
/admin/v1/requests         GET              审计检索（log_id / 调用方 / 类型 / 时间）

权限与留痕：角色三级——平台管理员（全部）/ 运营（类型 + 评测 + 审计）/ 只读；所有管理操作进审计日志（操作者、对象、前后版本）。发布即版本：每次发布生成不可变类型版本（含渲染后提示词快照），回滚 = 指向历史版本。

分期演进：二期增批量任务监控、MCP 调用审计、消费方自助接入流程（申请→审批→联调状态）；三期增 badcase 工作台（triage/分配/解决/验证）、训练流水线触发与灰度规则配置。

3.9 编排引擎运行时

请求状态机：pending → preprocessing → engine_calling → fusing → completed；异常路径 engine_calling --超时/重试耗尽--> degraded（降级为整图直读，结果标注 degraded: true）或 failed。异步执行用 FastAPI 后台任务 + PG 状态表（量级见规划方案 5.1，不引入分布式编排器），引擎并发用 asyncio 进程内信号量限流（多副本下为近似总量，一期规模可接受；二期引入 Redis 后全局精确）。needs_review 是字段级状态（投票不一致/低置信），不是请求级。

3.10 引擎适配器（PaddleOCR-VL 与 VLM）

PaddleOCR-VL 适配器三件事：能力声明（注册表登记 layout/text/handwriting 能力与成本画像）；协议适配（/layout-parsing 契约、参数透传——低阈值与关闭版面检测的手写召回参数封装为预处理策略）；结果归一（服务栅格坐标 → 归一化坐标；版面块标签 → 统一词表；无置信度时的保守默认与标注）。

VLM 适配器：OpenAI 兼容协议接入大模型平台；提示词由类型渲染器生成（模板与字段描述同版本，系统级指令由代码持有）；返回 JSON 修复与类型 Schema 校验；VLM 无原生置信度，融合器按"多次读取一致性"策略赋值（一期可先保守默认并标注 calibrated: false）。

两个适配器都必须通过 conformance test（标准样张进 → 统一结果模型 schema 校验 + 坐标/字段抽检）方可注册。

3.11 评测体系

• golden 集格式：每样本 = 文档对象 + 期望字段 JSON + 关键区块标注；一期每类型 ≥ 50 样本，覆盖典型/边界/低质量三类；
• 准确率口径：字段级完全匹配率为主指标，关键字段（金额、户名）辅以字符级差异率；needs_review 率单列；
• CI 门禁：类型发布与引擎版本变更必须触发 eval_runs，主指标不退化且无字段下降超阈值方可通过；门禁脚本进 CI 流水线。

3.12 一期部署清单

3.13 一期验收标准

① 首个消费方生产调用稳定运行 4 周（可用性 ≥ 99.5%，p95 ≤ 8s/单文档）；② golden 基线建立，准确率与复核率按周出数；③ 评测门禁在 CI 生效并拦截过至少一次违规发布（或演练验证）；④ 全部结果可经 log_id 回溯到证据裁片。

四、二期详细方案

• 智能体试点：MCP Server 已于一期实现（见 3.6），二期工作为试点接入星辰助手一个对话场景（凭证要素查询）、鉴权完善（OAuth 2.1 资源服务器语义）、网关/ESB 路由接入，以及 compare_documents 工具随比对大类补齐；
• 批量异步：/v1/batches（文档集 + 类型）→ 任务句柄 + 进度查询；PG 状态表 + 后台 worker，逐文档复用同步链路；
• 跨引擎投票：类型声明投票字段与引擎组合（如 PaddleOCR-VL + VLM）；投票算法首版先用字符级对齐取多数，不一致即 needs_review——宁可标记不裁断；触发条件由路由策略控制（关键字段或低置信字段）；
• 第二消费方接入：走标准 onboarding（申请凭证 → 选类型 → OpenAPI 联调 → 灰度 → 生产），沉淀接入手册。

五、三期详细方案

• 训练流水线：K8s Job 化——标注导出（badcase 台账 → 训练集）→ PaddleOCR 微调训练 → golden 全量评测 → 镜像构建（带版本 tag）→ 注册表更新；全程 Jenkins/ArgoCD 承载；
• badcase 运营：状态机 reported → triaged(定位: 数据/提示词/模型) → assigned → resolved(类型修复 | 微调排期) → verified；看板指标：闭环周期、badcase 存量、按类型分布；
• 灰度与回滚：新引擎版本按 model_version 参数灰度（5% → 50% → 100%），评测指标异常自动冻结灰度；回滚 = 注册表切回旧版本（镜像不可变）。

六、项目计划

6.1 里程碑时间线（相对周）

6.2 人力配置

6.3 外部依赖与协调

七、实施风险与应对

八、度量与验收汇总