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

> 对应规划方案的落地实施文档：一期详细设计（数据模型、API 契约、编排运行时、引擎适配、评测体系、MCP 与 AG-UI 工作台）、二三期方案、项目计划（里程碑、人力、资源、依赖）与实施风险，附里程碑交互图。

---

LLMS 索引： [llms.txt](/llms.txt)

---

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

## 一、建设原则 {#principles}

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

## 二、总体建设路线 {#roadmap}

| 期 | 主题 | 核心交付 | 出口标准（DoD） |
|---|---|---|---|
| 一期 | 骨架 | 统一结果模型、编排引擎、双引擎适配层（PaddleOCR-VL + VLM）、首个场景类型、REST API 与 **MCP Server**（应要求提前）、**AG-UI 识别工作台**（应要求提前，三出口成型）、golden 基线与评测门禁 | 首个消费方生产调用满 4 周；字段准确率基线建立并按周跟踪 |
| 二期 | 试点与扩展 | 智能体试点（MCP 与工作台已于一期实现）、工作台嵌入推广与调用方权限、批量异步接口、跨引擎投票、第二消费方 | MCP 对话式识别可用；关键字段双引擎互验准确率提升可度量 |
| 三期 | 闭环 | 训练流水线（标注→微调→评测→注册）、badcase 运营看板、模型灰度回滚 | 首个微调版本经回归门禁上线；badcase 闭环周期 ≤ 4 周 |

<iframe src="/ai/xingchen/15-idrp-milestones.html" title="识别平台建设里程碑" loading="lazy" style="width:100%;height:700px;border:1px solid #e5e7eb;border-radius:8px;"></iframe>

<a href="/ai/xingchen/15-idrp-milestones.html" target="_blank">全屏打开 ↗</a>

## 三、一期详细方案 {#phase1}

### 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`）：

```sql
-- 文档域
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 契约（一期）

| 端点 | 方法 | 说明 |
|---|---|---|
| `/v1/documents` | POST | 上传文档（multipart），返回 `doc_id` |
| `/v1/documents/{doc_id}` | GET | 文档状态与页信息 |
| `/v1/recognize` | POST | 识别（`doc_id` + `doc_type`），同步返回统一结果 |
| `/v1/recognize/{log_id}` | GET | 历史结果查询（含证据链引用） |
| `/v1/doc-types` / `/{id}/schema` | GET | 类型清单与字段 Schema 下发 |
| `/admin/v1/doc-types` | POST/PATCH | 类型草稿、发布（触发评测门禁） |

错误码体系：`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`）。

<iframe src="/ai/xingchen/16-idrp-agui-runtime.html" title="识别工作台 AG-UI 运行逻辑" loading="lazy" style="width:100%;height:700px;border:1px solid #e5e7eb;border-radius:8px;"></iframe>

<a href="/ai/xingchen/16-idrp-agui-runtime.html" target="_blank">全屏打开 ↗</a>

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

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

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

**功能模块（按优先级）**：

| 模块 | 一期能力 | 优先级 |
|---|---|---|
| 类型管理 | 草稿编辑（字段定义/提示词模板/版式先验/路由）、Schema 即时校验、版本历史与 diff、**发布门禁流程**（草稿→触发评测→查看对比→发布/驳回）、一键回滚历史版本 | P0（必须有界面） |
| 评测管理 | golden 样本上传与期望标注、评测运行记录、新旧版本准确率对比视图 | P0 |
| 审计检索 | 识别请求按调用方/时间/类型检索，log_id 详情含证据裁片回放 | P0 |
| 调用方管理 | 接入凭证签发、配额设置、启停 | P1（可先 API） |
| 引擎注册表 | 能力/版本/健康状态查看、启停 | P1（可先 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 一期部署清单

| 项 | 规格 | 说明 |
|---|---|---|
| 平台服务 | 2 副本 × 2C4G | K8s，HPA 上限 4 |
| PaddleOCR-VL 引擎 | 已部署服务 | 复用现有部署、适配器直连接入；容量与扩容按生产量另行评估 |
| VLM 引擎 | 大模型平台 | 平台不自建推理算力，仅申请通道与配额（W2 提交） |
| PostgreSQL | 共享实例独立 schema | 一期预估 < 50GB/年 |
| MinIO | 共享集群独立桶 | `idrp-raw` / `idrp-artifacts` 两桶 |
| 管理台前端 | 静态托管 | 随平台服务 Pod 发布，`/admin` 路径隔离 |
| 识别工作台前端 | 静态托管 | 与平台服务同域发布（SSE 代理需关闭缓冲），业务系统 iframe 嵌入 |

### 3.13 一期验收标准

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

## 四、二期详细方案 {#phase2}

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

## 五、三期详细方案 {#phase3}

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

## 六、项目计划 {#plan}

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

| 里程碑 | 周期 | 内容 | 前置 |
|---|---|---|---|
| M1 契约定版 | W1–W3 | 结果模型 Schema、golden 评测口径、API 草案评审定版 | — |
| M2 引擎就绪 | W3–W6 | 编排引擎、双引擎适配器（PaddleOCR-VL + VLM，含 conformance test）、提示词渲染器、预处理链 | M1 |
| M3 一期上线 | W6–W12 | 首类型、管理端、评测门禁 CI、首个消费方联调与生产接入 | M2 |
| M4 智能体试点 | W13–W18 | MCP 试点接入星辰助手、OAuth 鉴权与调用方权限、工作台嵌入推广、批量接口 | M3 |
| M5 质量升级 | W17–W20 | 跨引擎投票、第二消费方接入 | M3 |
| M6 闭环运营 | W21–W30 | 训练流水线、badcase 看板、首个微调版本上线 | M4/M5 |

### 6.2 人力配置

| 角色 | 人数 | 职责 | 投入 |
|---|---|---|---|
| 平台负责人 | 1 | 架构把关、契约裁决、对外协调 | 全程 |
| 后端工程师 | 2 | 网关/编排/适配器/管理端 | 一二期全职，三期 1 人 |
| 算法工程师 | 1 | 引擎调优、评测体系、三期微调 | 全程 |
| 测试工程师 | 1（兼） | golden 集建设、门禁验证、消费方联调 | 一二期 50% |
| 运维 | 1（兼） | 环境搭建、流水线、监控告警 | 各期 20% |

### 6.3 外部依赖与协调

| 依赖方 | 事项 | 协调时点 |
|---|---|---|
| 首个消费方 | 场景确认、联调窗口、生产切换 | M1 定场景，M3 联调 |
| ESB / 网关团队 | 域名、路由、鉴权接入；REST 服务注册 | W2 启动，W10 完成 |
| 大模型平台 | VLM 通道、配额、模型版本升级通知 | W2 提交申请，W6 前可用（一期即依赖） |
| 运维/K8s | 命名空间、监控接入、引擎容量评估（引擎已部署） | W1 提交 |

## 七、实施风险与应对 {#risks}

| 风险 | 概率 | 应对 |
|---|---|---|
| 契约定版反复导致一期延期 | 高 | M1 设评审硬闸：消费方+平台联合评审，定版后变更走大版本流程 |
| 首场景含手写字段，依赖 VLM 精读 | 中 | 一期即接入 VLM 与提示词渲染器；若 VLM 通道审批延迟，先以印刷体字段上线，手写字段标记 `needs_review` 待通道就绪后补齐 |
| 现有引擎并发容量不足 | 低 | 接入前压测定容量；扩容按生产量另行申请 |
| 消费方联调窗口错配 | 中 | M1 即锁定联调窗口并写入双方计划；API 草案 W3 即提供 mock |
| 单人依赖（算法/契约裁决） | 中 | 契约与适配器设计文档化、评审留痕；M2 起后端工程师交叉熟悉适配层 |

## 八、度量与验收汇总 {#metrics}

| 维度 | 一期出口 | 二期出口 | 三期出口 |
|---|---|---|---|
| 可用性 | ≥ 99.5%，p95 ≤ 8s；MCP 工具集与 AG-UI 工作台可用（智能体与嵌入接入就绪） | 同左 + MCP 试点落地 | 同左 |
| 质量 | 准确率基线 + 周跟踪 | 关键字段双引擎互验提升可度量 | 微调版本准确率提升 ≥ 3pp |
| 复用 | 1 个消费方 | 2 个消费方 + 接入手册 | 接入周期 ≤ 2 周/新场景 |
| 运营 | 评测门禁生效 | — | badcase 闭环周期 ≤ 4 周 |

---

反链：

- [星辰智能](/docs/ai/xingchen-intelligence/)