diff --git a/docs/roadmap.md b/docs/roadmap.md index 9d5ef90..6af1705 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -313,11 +313,24 @@ ROI 是业务入口能力,不是 Layout 的替代品。第一版只接受位 任意多边形、多个 ROI 合批和仅对已知 line crop 执行 recognition 可作为后续扩展,不阻塞本节点。 -### 5.4 图片方向与坐标 +### 5.4 检测-only 出口 + +detection 在 Core 中本就是独立 stage。此出口只把已有能力暴露为公共入口,不新增算法,也不改变 recognition 语义。它回答的是“文字在哪里”,而不是“文字是什么”: + +- 仅运行 detector,输出检测框(与 OCR `line.box` 相同的 `pageSpace` quad 契约),不触发 recognition; +- 可选返回每个区域的 PNG crop,与检测框 index 对齐,便于喂给下游模型、版面分析、计数或 redaction 流程; +- 与 ROI 互补且不重叠:ROI 是输入侧的区域约束(限制检测范围),detect-only 是输出侧的能力裁剪(只交付检测结果); +- 不是 Layout 的替代:只给出原始检测框,不附加 region label、阅读顺序或语义分类。 + +把它放在 N1 而非 N4 的原因:它零新增算法,且检测框正是未来 OCR `line` 与 Layout `region` 之间共享的中间产物。N4 Layout 在此基础上为同一批检测框附加分类与编排,不重复运行检测。因此 detect-only 同时是业务入口(只要位置的用户)和 N4 的前置基础设施。 + +CLI 与 Node API 第一版应至少提供“检测框输出”;crop 返回可作为同节点的可选开关。detect-only 结果同样受 `schemaVersion`、坐标契约和资源上限约束,stdout/stderr 分离和稳定 exit code 与 `recognize` 一致。 + +### 5.5 图片方向与坐标 v1 CLI 对 encoded JPEG 默认应用可验证的 EXIF orientation 修正,并把修正后的图片定义为 `pageSpace`;结果记录完整 `appliedTransforms`。raw-pixel API 继续由调用者负责方向,传入像素直接定义 `pageSpace`。底层 `OcrResult` 返回实际送入 Core 的 `pageSpace` 坐标,CLI envelope 记录它与 `sourceSpace` 的关系。 -### 5.5 Agent Skill +### 5.6 Agent Skill 仓库内增加 `.agents/skills/local-ocr/SKILL.md`,包含: @@ -330,7 +343,7 @@ v1 CLI 对 encoded JPEG 默认应用可验证的 EXIF orientation 修正,并 Skill 是 CLI 的薄工作流层。识别、坐标转换和 schema 逻辑必须留在产品代码中。验证稳定后,再把 Skill 打包为可安装 Plugin;本地文件 OCR 暂不需要 MCP server。 -### 5.6 验收与退出条件 +### 5.7 验收与退出条件 - Tier 1 平台的 Node.js 22/24 均通过 `npm install` 后 CLI smoke; - CJS、ESM、Node API 和 CLI 对同一输入返回语义一致的结果; @@ -341,7 +354,7 @@ Skill 是 CLI 的薄工作流层。识别、坐标转换和 schema 逻辑必须 - Agent eval 至少 18/20 通过,并且任何失败都不能把推断内容伪装成 OCR 原文; - 一个不熟悉内部架构的读者能只凭 README/SKILL 完成首次 OCR。 -### 5.7 G1 决策 +### 5.8 G1 决策 进入 N2/N3 前检查: @@ -567,9 +580,10 @@ CPU 是所有平台 Auto 的稳定最终候选、显式 backend,也是判断 G 1. 建立上述 stage timing 和 workload corpus,复现当前 cold/warm baseline; 2. 校准 detector/recognizer 的 intra-op、inter-op 线程和 execution mode,避免 Node worker/engine pool 与 ORT 线程过量竞争; -3. 评估 recognition batch、crop 调度、tensor/buffer 复用和 tiled 路径; -4. 分别给 tiny/small/medium 建议 latency 与 throughput profile,不让一个线程配置覆盖所有宿主; -5. 将确定性、质量、峰值内存、取消和关闭语义纳入每次优化 Gate。 +3. 评估模型 bundle 采用 ONNX Runtime ORT 格式(FlatBuffers 序列化、预优化图)对 session 创建成本的收益。从内存字节加载时按 magic 识别格式;对已预优化的 ORT 图跳过或降低 `GraphOptimizationLevel`,避免对已完成优化的图重复工作。这是 cold start、频繁重建 session 的容器/serverless 场景,以及 CLI 每次进程调用路径的主要收益来源,属无分发矩阵扩大的同类收益。引入前必须验证 ORT 格式 detector/recognizer 与现行 `.onnx` 路径的输出 parity,不放宽现有质量与确定性门禁;session 创建加速以可重放测量记录,不替代 warm 推理性能结论; +4. 评估 recognition batch、crop 调度、tensor/buffer 复用和 tiled 路径; +5. 分别给 tiny/small/medium 建议 latency 与 throughput profile,不让一个线程配置覆盖所有宿主; +6. 将确定性、质量、峰值内存、取消和关闭语义纳入每次优化 Gate。 Perf-1 的退出物不是一个“最快数字”,而是一份可重放 CPU baseline、默认配置依据,以及能指出瓶颈位于 decode、pre/postprocess、det、rec 还是调度的 profiler 记录。