# 智能文档识别平台规划方案
> 基于 OCR + VLM 双引擎的企业级识别能力平台规划：目标、业务架构、应用架构、技术架构、技术栈选型、数据架构、部署架构、MCP×ESB 协同与 AG-UI 工作台，附七张交互式图表。
---
LLMS 索引： [llms.txt](/llms.txt)
---
面向企业影像与文档智能场景的**识别能力平台**规划方案。平台以 OCR 与 VLM 双引擎为底座，通过 REST API、MCP 与可嵌入识别工作台（AG-UI）三种形态对外输出识别能力。本方案为从目标出发的全新设计，不绑定任何现有系统的实现；现有业务系统在方案中仅以"首个消费方"身份出现。文中七张图表均为交互式：支持缩放、语义视图、关系追踪与 PNG/SVG 导出。
## 一、背景与目标 {#goals}
### 1.1 建设动因
识别类能力目前散落在各业务系统中自建自用，存在三方面问题：
- **识别与业务规则耦合**：抽取管线与校验规则交织在同一套代码里，换模型、调参数会波及业务逻辑，测试边界模糊；
- **能力无法复用**：每个系统重复解决版面解析、手写识别、印章提取、裁片精读等同类问题，质量参差；
- **质量无闭环**：识别错误依赖各系统自行发现，没有统一的 badcase 归集、评测与模型迭代机制。
### 1.2 平台目标
**一句话定位**：给一份文档，还你结构化与语义化的识别结果——OCR 负责结构与位置，VLM 负责语义与理解，双引擎一个平台，REST、MCP 与工作台三出口。
三条核心目标：
1. **识别与判断解耦**：平台输出"事实"（字段、位置、置信度、证据），业务判断（合规校验、规则比对）完全留在消费方。判断类输出（一致/不一致、合规/违规）永远不出现在平台侧。
2. **识别能力服务化**：企业内任何系统、任何智能体都可以通过标准契约消费识别能力，新场景上线是"新增一条类型配置"，不是"新写一套识别服务"。
3. **引擎可插拔可演进**：OCR、CV、VLM 引擎都是可替换资源；接入第 N+1 个引擎只新增一个适配器，核心层零改动；模型可通过微调闭环持续变准。
### 1.3 设计原则
| 原则 | 含义 |
|---|---|
| 感知与判断分离 | 平台只做忠实识别，输出证据与置信度；宁可标记不确定，不给可能有错的值 |
| 契约先行 | 统一结果模型最先设计、最先冻结；API 与 MCP 共享同一契约 |
| 引擎无关 | 编排层引用"能力"而非具体引擎；换引擎是配置变更 |
| 演进式建设 | 每期独立可交付，任何一期停住都不亏 |
### 1.4 成功度量
| 维度 | 指标 |
|---|---|
| 质量 | 关键字段准确率（按场景类型统计）、人工复核率（needs_review 占比） |
| 复用 | 接入业务方数量、沉淀场景类型数量、新场景接入周期 |
| 效率 | 单均识别时延、批量吞吐、VLM 调用成本（路由命中率） |
| 运营 | badcase 闭环周期（发现→标注→微调→上线） |
## 二、业务架构 {#business}
### 2.1 消费方
平台服务四类消费方，对应三种接入形态：
- **业务系统**（REST API）：消费识别字段做业务处理。典型如结算凭证核验系统——平台读出大小写金额与印章位置，系统侧做一致性校验；
- **智能体**（MCP）：对话式消费识别能力。柜员或审计在智能助手里"把这张凭证的金额读出来"，助手调 MCP 工具完成识别并组织回答；
- **终端操作者**（可嵌入识别工作台 · AG-UI）：业务系统把平台提供的识别工作台嵌入自身页面，操作人员以对话方式完成上传、识别与人工复核——界面交互走 AG-UI 协议（第三出口），权威数据仍凭 log_id 走 REST/MCP 获取；
- **平台运营方**：管理文档类型、评测集、引擎版本与调用配额。
### 2.2 能力分层
| 层 | 内容 | 归属 |
|---|---|---|
| L1 原子能力 | 版面解析、文本/手写识别、表格识别、印章检测、字段抽取、文档比对 | 平台 |
| L2 场景能力 | 票据识别、印章提取、函证抽取等 = 原子能力 + 场景类型（版式先验、提示词、后处理） | 平台 |
| L3 业务方案 | 凭证核验、函证比对、报表核对等业务规则与流程 | 消费方 |
划分标准：**"怎么读准"进平台文档类型，"读出来的对不对"留在消费方**。版式先验（如票据金额栏位置）属于"怎么读准"，沉淀为平台文档类型，全行复用；合规规则属于业务立场，不得进入平台。
### 2.3 质量闭环
业务架构的灵魂是 badcase 闭环：消费方复核标记 → 平台归集台账 → 人工标注修正 → 沉淀 golden 评测集 → 驱动文档类型调优与引擎微调 → 评测通过后灰度上线 → 通知消费方。闭环转起来，平台从成本中心变成越用越准的资产。
全屏打开 ↗
> [!NOTE]
> 三出口是同一编排层的三个壳：REST、MCP 与 AG-UI 工作台共享能力实现，绝不允许出现两套逻辑。智能体侧工具按粗粒度设计（识别文档、抽取字段、比对文档），不暴露引擎参数。
## 三、应用架构 {#application}
### 3.1 应用组件
| 组件 | 职责 |
|---|---|
| 能力网关 | 鉴权、限流、审计、日志追踪（logId 全链路串联），无业务语义 |
| MCP Server | MCP 协议薄壳：粗粒度工具、文档引用、结果资源化，复用编排层 |
| AG-UI 运行时 | 识别智能体后端：`POST /agent/run` 会话端点（规划器 + 工具调度 + SSE 事件流），复用编排层；配套可嵌入识别工作台前端 |
| 编排引擎 | 按文档类型组合能力：预处理 → 引擎调用 → 融合；引擎路由与降级决策 |
| 预处理服务 | DPI 栅格化、对比度增强、区域裁片、方向矫正 |
| 引擎适配层 | OCR / CV / VLM 三类引擎契约、注册表、结果归一 |
| 融合后处理 | 跨引擎投票、字符级对齐、置信度分层、坐标归一 |
| 结果与追溯 | 工件落对象存储、元数据入库、证据链检索 |
| 平台管理端 | 类型与字段 Schema 配置、评测发布门禁、引擎版本与配额管理 |
### 3.2 统一结果模型（契约核心）
所有引擎输出归一到同一对象模型，这是 API 与 MCP 共享的地基：
```json
{
"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 串联。
| 治理能力 | 归属 | 说明 |
|---|---|---|
| 服务目录与注册 | ESB | MCP `tools/list` 只是给大模型看的工具清单，不是企业服务目录 |
| 限流、熔断、灰度 | ESB | 完全不动 |
| 审计 | 两层各审 | MCP 层审智能体与用户身份，ESB 层审服务调用，ID 串联 |
| 协议与语义转换 | MCP Server | 面向 LLM 的粗粒度工具语义 ↔ ESB 上的服务契约 |
| 编排 | 部分转移 | 流程编排权从服务侧部分转移到智能体（运行时决定工具序列），但每次调用仍穿透 ESB |
全屏打开 ↗
> [!IMPORTANT]
> 三条管控红线：① MCP Server 的**跨系统**调用一律走 ESB，防止影子集成；② MCP Server 保持薄——只做协议适配与工具语义，业务编排放服务侧；③ 同一能力双协议暴露（REST 注册为 ESB 服务供传统系统，MCP 工具供智能体），能力实现只有一份。
### 3.6 文档类型化接入：按类型识别输出
识别接口按**文档类型（文档类型）**输出对应字段集——发票返回发票字段、询证函返回询证函字段，文档类型与输出字段在平台管理端可配置。这是编排层类型化的直接应用：**输出字段 = 文档类型中声明式定义的字段 Schema**。
**API 形态：按能力大类分端点，大类内按文档类型参数化。** 大类与文档类型是两个正交维度——大类区分任务形态（识别、比对、批量），文档类型区分票种（发票、询证函、凭证）：
```json
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 校验（命名规范、类型合法、必填约束自洽），脏配置进不了生产。文档类型配置模型示例：
```json
{
"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}
}
```
**配置化的深度与边界**：配置表达"结构与参数"，代码表达"算法与流程"——把逻辑塞进配置端会演化出没人敢改的"配置编程语言"，把结构参数写死代码又会让新场景接入周期失控。
| 管理端可配置（运营/接入人员） | 代码交付（开发迭代，走版本化发布） |
|---|---|
| 文档类型与字段定义（名称、类型、必填、枚举） | 复杂后处理算法（声明式规则表达不了的） |
| 字段提取方式（OCR 直出 / VLM 精读 / 跨引擎投票） | 新引擎适配器 |
| 版式先验（关键区域、裁片策略）与阈值 | 预处理管线变更 |
| 提示词模板、字典映射、正则校验等声明式后处理 | 统一结果模型变更 |
**两条配套约束**：① 类型变更与代码变更同级对待——管理端配置同样走"草稿 → golden 集评测通过 → 发布"，不允许直接改生产文档类型；② 配置出来的字段同样携带 `confidence / needs_review / evidence_block_ids`，配置化不绕过质量纪律。**自然扩展**（按需）：`doc_type: "auto"`——混合批次先经 CV 引擎文档分类再路由到对应文档类型，文档类型机制天然支持。
### 3.7 提示词管理：渲染产物与护栏
VLM 识别的提示词**不是独立维护的字符串，而是文档类型的渲染产物**：字段定义是数据，提示词模板是模板，最终发给 VLM 的提示词 = 渲染器（模板 + 字段定义 + Schema 约束）生成——与文档类型同版本、同生命周期。
| 层 | 内容 | 归属 |
|---|---|---|
| 提示词模板（骨架） | 角色指令、抽取原则、输出 JSON 格式约定、few-shot 示例 | 管理端按文档类型可配置 |
| 字段描述（数据） | 字段名称、语义说明、枚举值、格式要求 | 文档类型字段定义的一部分 |
| 渲染器（代码） | 拼 Schema、注入裁片上下文、控制语言 | 平台代码，管理端不可碰 |
关键机制是**渲染时注入**：模板引用受控变量插槽（`{{fields_schema}}` 等）而非硬编码字段清单——文档类型加字段，下次渲染自动带上，不存在"字段加了、提示词忘了同步"的不一致。由此买到三样东西：**一致性**（字段与提示词同源）、**可审计**（结果 ↔ 类型版本 ↔ 渲染后提示词绑定，历史可重放）、**缓存友好**（同版本渲染结果可缓存）。
**五条护栏**（缺一条，动态提示词就是事故源）：
1. **模板与数据分离**：字段清单永远经渲染注入，不写死在模板里；
2. **受控变量插槽**：模板只支持平台预定义变量（fields、schema、language、context），不允许任意表达式——配置端不能演化成编程语言；
3. **系统级指令不可配**：输出必须 JSON、不得编造等平台级纪律由代码持有，管理端模板覆盖不到；
4. **评测门禁覆盖提示词变更**：提示词有牵一发动全身的隐性风险（改一个字段描述可能让整页其他字段退化），正确工作流是草稿 → golden 集回归 → 新旧 A/B 对比 → 发布，不允许直接改生产；
5. **提示词版本 = 类型版本**：不存在独立的提示词版本，回滚文档类型即回滚提示词。
由此，提示词调优进入与模型迭代同一条质量闭环：badcase 台账发现字段系统性读错 → 定位字段描述歧义或模板问题 → 管理端改草稿 → golden 集验证提升且无回归 → 发布新类型版本。**提示词从代码里的字符串变成可运营、可度量、可回滚的资产**——这是文档类型化架构对 VLM 侧最大的红利。
## 四、技术架构 {#tech}
### 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` 走人工。
全屏打开 ↗
## 五、技术栈选型 {#stack}
选型独立于任何现有系统评估，按**扩展性、成熟度、开发效率、性能、运维成本、信创合规**六个维度论证。
### 5.1 选型决策表
| 决策点 | 选型 | 主要备选 | 决策理由 |
|---|---|---|---|
| 平台服务框架 | Python + FastAPI | Java Spring Boot、Go | 训练/推理/预处理/评测工具链原生 Python，跨语言会让模型迭代链路割裂；FastAPI 异步 IO + Pydantic + 自动 OpenAPI，开发效率与契约质量兼得。性能瓶颈在引擎侧而非编排侧，Go 的并发优势收益有限 |
| MCP 实现 | 官方 Python SDK（FastMCP） | TypeScript SDK | 与平台同语言同仓，直接复用编排层；MCP 协议语言无关 |
| 任务编排 | 一期进程内异步 + PG 状态表 | Celery、Temporal | 一期量级不需要分布式编排器；Temporal 运维与学习成本高。编排器接口抽象，保留演进空间 |
| 消息队列 | 一期不引入；二期按企业消息标准 | Kafka、RocketMQ | 少一个组件少一分运维；企业已有消息标准时遵从企业标准 |
| 对象存储 | MinIO | NFS、数据库 BLOB | S3 协议、版本化、生命周期策略、水平扩展；原始文档与工件是不可变对象，对象存储天然匹配 |
| 元数据库 | PostgreSQL | MySQL | 识别结果是半结构化，JSONB 原生存储引擎原始输出与字段证据；分区与全文检索成熟 |
| 缓存与锁 | Redis（二期引入） | 进程内信号量 + PG 计数 | 一期规模下进程内信号量与 PG 计数足够（分布式锁一期无真实需求——后台任务同进程执行）；二期批量异步与多副本全局限流产生刚需再引入，接口按可替换设计 |
| OCR 引擎 | PaddleOCR（PP-OCRv5 + PaddleOCR-VL） | Tesseract、商用 OCR | 全链路国产开源（训练-压缩-serving），微调闭环可行；多产线（版面/表格/印章）齐备；支持昇腾/昆仑芯，信创友好。Tesseract 中文弱且难微调；商用有成本与数据出域问题 |
| VLM 接入 | OpenAI 兼容协议 → 大模型平台 | 各家专有 SDK | 协议层抽象使 VLM 可替换（大模型平台模型升级、自部署模型均平滑切换），避免绑定 |
| 图像预处理 | PyMuPDF、OpenCV、Pillow | — | 事实标准 |
| 可观测 | Prometheus + Grafana + OpenTelemetry | ELK | K8s 生态标配；业务指标（准确率、复核率）以自定义指标暴露 |
| CI/CD | Jenkins + Harbor + ArgoCD | GitLab CI | 企业工程标准，复用现有流水线体系（环境事实而非技术偏好） |
| 消费方 SDK | OpenAPI 生成多语言 | 手写 SDK | 契约单一真相源，生成即同步 |
### 5.2 Python 与 Go：主体与边缘的分工
**决策：平台主体语言为 Python；Go 不作为平台语言，仅作为特定边缘组件的按需选项——按瓶颈引入，不按偏好引入。**
先看负载画像：处理一份文档的时间分布为——引擎推理（GPU，秒级）> VLM 调用（秒级）> 预处理（百毫秒级）> 编排逻辑（毫秒级）。**延迟大头在引擎、吞吐瓶颈在算力，编排层是 IO 密集的轻计算层**，FastAPI 的 asyncio 在凭证级调用量下余量充足；Go 的并发优势在高 RPS 网关场景才兑现，此处用不上。更关键的是语言分裂的代价：训练、微调、评测、预处理全在 Python 生态，编排层若用 Go，模型迭代链路被切成两半，每次调整都要跨语言维护两份实现——平台的核心竞争力（文档类型快速迭代 + 模型持续变准）都长在 Python 生态里。
公允对照 Go 的真实优势与平台需求：
| Go 的优势 | 平台是否需要 |
|---|---|
| 高并发网络边缘（海量长连接、SSE 流） | 当前调用量级用不上；MCP Streamable HTTP 的并发连接 asyncio 可承载 |
| 无 GIL 的多核计算 | 计算在 GPU 引擎与 OpenCV（C 实现、释放 GIL），不在编排层 |
| 单二进制部署、低内存 | K8s + 容器镜像体系下优势归零 |
| 强类型防大型代码库腐化 | Pydantic + mypy + 契约测试可覆盖平台规模需求 |
分层语言分工：
| 层 | 语言 | 说明 |
|---|---|---|
| 接入层 / 编排 / 能力 / MCP Server / SDK | Python | 与能力实现同仓同语言，迭代最快 |
| 预处理 | Python + 进程池 | PyMuPDF/OpenCV/Pillow 底层为 C，多进程绕 GIL |
| 训练流水线 / 评测 | Python（唯一现实选项） | PaddleOCR 训练链路 |
| 边缘组件（可选） | Go | 大文件传输网关、引擎反向代理/连接聚合器、批量任务分发器 |
**组件改写为 Go 的三条触发判据**（不满足任何一条则不引入，第二语言的维护成本是持续的）：
1. 实测瓶颈：压测显示 Python 组件在目标 SLA 下 p99 不可接受，且进程池、缓存等优化已到头；
2. 部署形态：组件需以单二进制下沉到无 Python 运行时的环境；
3. 纯网络转发：组件为无状态转发/聚合、无业务语义，用 Go 实现反而更简单。
补充选项：若企业平台工程规范倾向 Go 网关，可接受"Go 接入壳 + Python 编排核"的混合架构——Go 只做协议接入与流控，全部业务语义在 Python；前提是契约（OpenAPI）稳定且团队双语言人力齐备。
### 5.3 多智能体：不引入的架构决策
**决策：识别平台不引入自主智能体编排（含多智能体）；平台是工具/能力提供方——被智能体调用的那一端——自身不成为智能体。跨工具的动态编排属于消费方智能体平台的职责。**
| 理由 | 说明 |
|---|---|
| 任务形态闭合 | 识别任务是定义良好的固定流水线（预处理→引擎→融合→输出），路径在文档类型中预先确定；多智能体解决的是需运行时分解与反思的开放性任务，此处不存在 |
| 确定性与可审计 | 同输入必须同输出、结论可重放（证据链设计的前提）；自主决策路径不可复现，审计成本吞掉灵活性收益 |
| 延迟与成本 | 引擎调用已是秒级、VLM 昂贵，多智能体对话轮次成倍放大时延与 token 成本，与平台"成本路由、OCR 优先"的取向直接冲突 |
| 架构角色 | 智能体在消费方（经 MCP 调用工具）；平台内再长智能体等于把消费方职责搬进提供方，边界混乱 |
期望"智能体"带来的能力，平台已用**确定性等价物**覆盖：多读投票（应对幻觉）、`needs_review` 复核标记（自我校验）、降级链（自主恢复）、文档类型路由（自适应选择）——效果可度量、路径可复现。
**边界条件**：若未来出现开放式任务（如"审计整卷信贷档案"需运行时分解、交叉比对、汇总结论），正确做法是在消费方/业务方案层增设智能体编排——由它规划步骤并循环调用平台的 MCP 工具，识别平台继续作为被调用的工具集，分层不变。
### 5.4 维度小结
- **扩展性**：引擎适配层 + 注册表保证水平扩展（多引擎）与垂直扩展（多副本 HPA）两条路径都开放；
- **成熟度**：全部选型均为生产级验证过的主流组件，无实验性依赖；
- **开发效率**：单一语言（Python）覆盖业务编排到模型迭代，文档类型化让新场景以天级接入；
- **性能**：计算密度在引擎层（GPU），编排层 IO 密集（异步足够），分层各自优化互不拖累；
- **运维成本**：一期落地组件仅 3 个（平台服务、MinIO、PG；引擎复用已有部署），Redis 二期引入；
- **信创**：框架（PaddlePaddle）与芯片适配（昇腾/昆仑）均国产化可选。
## 六、数据架构 {#data}
### 6.1 存储分工
| 存储 | 承载 | 特征 |
|---|---|---|
| MinIO | 原始文档、标准栅格、裁片、引擎原始输出、可视化图 | 不可变对象、版本化、可回放 |
| PostgreSQL | 请求记录、统一结果、复核标记、badcase 台账、文档类型与注册表、评测记录 | 结构化 + JSONB 半结构化 |
| Redis（二期起） | 任务队列状态、热点结果缓存、分布式锁、限流计数 | 易失，可重建；一期由 PG 与进程内实现承接 |
### 6.2 核心数据模型（表清单）
| 域 | 表 | 说明 |
|---|---|---|
| 文档 | `documents` / `doc_pages` | 对象引用、页级栅格工件索引、校验和 |
| 识别 | `recognition_requests` / `recognition_results` | 请求上下文（文档类型、引擎、耗时）与统一结果 JSONB |
| 证据 | `result_blocks` / `evidence_refs` | 块级坐标与文本、字段→证据块引用链 |
| 运营 | `review_marks` / `badcase_ledger` / `annotations` | 复核标记、badcase 台账、人工标注 |
| 评测 | `golden_sets` / `eval_runs` | golden 样本集与每次回归评测结果 |
| 配置 | `doc_types` / `engine_registry` / `callers` | 类型版本、引擎注册画像、调用方与配额 |
### 6.3 证据链与数据反哺
- 每个字段的 `evidence_block_ids` 指向块级记录，块级记录指向对象存储中的裁片与引擎原始输出——任何结论可重放验证；
- 低置信字段与复核标记自动进入 badcase 台账，人工标注后沉淀 golden 集；golden 集同时服务引擎评测、类型回归与微调训练三类消费；
- 数据生命周期：原始文档与证据按监管留存期归档；引擎原始输出可按期降冷，统一结果永久在线。
全屏打开 ↗
## 七、部署架构 {#deployment}
### 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（业务验收 + 灰度验证）/ 生产（灰度发布 + 双版本并行）。生产网与研发网物理隔离，制品经镜像仓库摆渡。
全屏打开 ↗
> [!TIP]
> 服务网格、分布式追踪全家桶等重型设施暂不引入——一期以最小组件集达成目标，扩容与治理能力按真实负载演进。
## 八、演进路径 {#roadmap}
| 阶段 | 内容 | 出口标准 |
|---|---|---|
| 一期：骨架 | 统一结果模型 + 编排引擎 + 首个场景类型（结算凭证类）+ REST API + MCP Server（应要求提前）+ **AG-UI 识别工作台**（应要求提前，三出口骨架一期成型）；PaddleOCR-VL 与 VLM 双引擎接入适配层 | 首个消费方生产调用；golden 集与字段准确率基线建立；工作台可嵌入使用 |
| 二期：试点与扩展 | 智能体试点接入（MCP 与工作台已于一期实现）；工作台嵌入推广与身份权限细化（调用方 × 类型授权、用户/机构声明）；第二消费方接入；跨引擎投票（接 VLM）上线 | MCP 对话式识别可用；关键字段双引擎互验准确率提升可度量 |
| 三期：闭环 | 训练流水线（标注→微调→评测→注册）+ badcase 运营看板 + 批量异步接口 | 首个微调模型版本经回归门禁上线；闭环周期可度量 |
## 九、风险与对策 {#risks}
| 风险 | 对策 |
|---|---|
| 手写等低质量样本识别不稳定（模型幻觉） | 跨引擎投票 + 置信度分层 + needs_review 人工分流；微调闭环长期治理 |
| VLM 成本随调用量失控 | 成本路由（OCR 优先）、裁片精读（VLM 只看小图）、结果缓存三件套从一期内置 |
| 平台做成"两个平台"（OCR 一套、VLM 一套） | 统一结果模型与编排层单一实现，引擎只是可替换底座，架构评审守住 |
| 场景类型膨胀失控（每个场景一个特例） | 类型版本化 + 评测回归覆盖所有在线文档类型；无评测集的场景不上线 |
| 多消费方相互影响（流量/变更） | 按调用方配额限流；契约只增不改，破坏性变更走新版本号 |
| 识别平台越界做业务判断 | 架构红线：判断类输出不出现在平台契约；code review 与契约 schema 双重把关 |
---
反链：
- [星辰智能](/docs/ai/xingchen-intelligence/)