Windows Device 加速技术方案

状态：Windows x64/D3D12 产品实现与 AMD Radeon 780M 真实设备 Provider Gate 已完成（164/164）；已审阅报告和产物哈希已绑定 production lock

更新时间：2026-07-19

范围：当前交付目标是 Windows x64；Windows arm64 及 Qualcomm NPU 属于后续平台决策

1. 结论

Windows 没有一个可以等同于 Apple ANE 的统一硬件和统一精度路径，但这不能转化成用户安装多个厂商 runtime 的负担。Windows 方案新增以下一级约束：

用户始终只安装 @arcships/light-ocr。模型、native addon、ONNX Runtime/Windows ML、DirectML 或已发布的厂商 EP 必须由 npm release set 自带；不得要求用户另装 CUDA、TensorRT、OpenVINO、VitisAI、QNN SDK 或编译工具链。正常 GPU/NPU driver 是唯一允许的系统前置条件。

“OS 无关 package”指一个稳定的 facade、API 和安装入口；native payload 继续由 npm 按 os/cpu 自动选择。Windows x64 的通用加速主线确定为 Native ONNX Runtime WebGPU EP，通过 Dawn 优先使用 D3D12，并把固定 runtime/plugin 隐藏在 Windows native package 内：

WebGPU 是 Windows x64 的通用 GPU 默认方向。 0.3.0 发布锁定的 FP32 ONNX profile，严格检查算子、shape、placement、CPU 释放、驱动和端到端收益；D112 Auto 顺序为 webgpu → cpu 并使用 FP32。WebGPU FP16 不进入本版本公共能力。
DirectML 降为 Windows 专用兼容性备选。 它仍可覆盖多代 DX12 GPU，但已进入 maintenance/legacy；只有 WebGPU 对目标设备/workload 不成立且 DirectML 的独立收益足够时才启动 Spike。
Intel/OpenVINO、NVIDIA/TensorRT RTX、AMD/MIGraphX/VitisAI 是专用后端。 只有通用 WebGPU 路径未覆盖目标范围，或用户加权收益足以覆盖额外包体和维护成本时才启动，并各自通过 PG。
Qualcomm QNN 暂不进入当前实现。 HTP NPU 路径主要面向 Windows arm64 Snapdragon X，而该平台仍是 deferred target。
CPU 是 Auto 的稳定最终候选，也是可显式选择的 backend。 显式 provider=webgpu|cpu|… 只尝试指定 backend；跨 backend 回退只发生于 D112 定义的 Auto 创建期。

稳定默认产品不使用 Windows ML 在首次运行时自动下载 EP，也不搜索用户机器上偶然安装的 SDK。推荐的用户可见和内部拓扑是：

user: npm install @arcships/light-ocr
  └── npm automatically selects @arcships/light-ocr-win32-x64
      ├── light_ocr_node.node
      ├── pinned self-contained ORT + Native WebGPU/Dawn runtime
      ├── bundled CPU final candidate
      ├── accepted Windows-specific EPs, only after their launch/package Gates
      ├── provider-specific model/profile/cache artifacts
      └── explicit device selection and observable D112 selection

npm 只能按 OS、CPU 和 libc 选择 optional dependency，不能按 Intel/NVIDIA/AMD GPU vendor 选择。因此通用 release set 先自带 WebGPU + CPU，而不是把所有厂商 runtime 塞入默认包。DirectML 和厂商 EP 只有通过专用后端启动 Gate、独立 PG 与包体审查后，才可进入同一个 Windows platform package 或受控内部 shard。Windows ML 动态 catalog 只保留为未来宿主显式授权的联网增强，不是稳定运行前提。

flowchart TD
    Create["Engine creation: D112 Auto or explicit provider"] --> Candidate["Atomically create detector + recognizer candidate"]
    Candidate -->|"success"| Freeze["Freeze selected backend"]
    Candidate -->|"Auto skippable creation reason"| Destroy["Destroy all partial candidate state"]
    Candidate -->|"explicit or fatal failure"| Fail["Return structured creation error"]
    Destroy --> CPUCreate["Atomically create complete ORT CPU candidate"]
    CPUCreate -->|"success"| FreezeCPU["Freeze CPU backend"]
    CPUCreate -->|"failure"| Exhausted["Record fatal; return creation error with full trace"]

    Freeze --> Input["Run: decoded page pixels"]
    FreezeCPU --> Input
    Input --> CPUPre["CPU preprocess / resize / crop"]
    CPUPre --> Inference["Frozen backend inference: CPU, WebGPU, or accepted specialized provider"]
    Inference --> CPUPost["CPU DB postprocess / CTC decode / assemble"]

只有 provider=auto 可以沿创建期的 skippable 边进入 CPU 候选。显式 provider=webgpu|directml|… 创建失败直接返回；任一候选的 detector/recognizer 必须原子创建。图不表示所有专用 provider 已获准进入 Auto，它们仍需独立 Gate 和版本化策略决策。

1.1 `0.3.0` Windows 真机结论

AMD Radeon 780M / Dawn D3D12 报告通过 164/164 Gate。14 个 fixture 的 WebGPU FP32 输出与 CPU FP32 baseline 字节级一致；CPU P50 总和为 6,500.853 ms，WebGPU P50 总和为 2,669.160 ms，聚合加速 2.436×，单 fixture 范围 1.277×–2.982×。所有 fixture 均更快。

Cold start、单次内存、native C++、Auto selection、真实 placement、strict rejection 与 lifecycle 全部通过。Warmup-aware lifecycle 结束时比预热后基线低 22.9 MiB。性能数字只适用于这台 AMD 780M 与记录驱动；其他 D3D12 设备不继承该倍数。

2. 目标与非目标

2.1 目标

保持一个 OS 无关安装入口。 用户只依赖 @arcships/light-ocr；facade 自动解析匹配的 native platform package 和固定模型。
实现零外部 runtime 安装。 每个 native package 必须携带运行所需的 runtime、EP、动态库、许可、SBOM 和 compatibility manifest；不能要求用户配置 PATH、CUDA_HOME 或 SDK 目录。
释放 CPU 给用户前台负载。 与 Apple 路径相同，交互式 profile 首先看 OCR process CPU-s，而不是只看 GPU/NPU 利用率。
覆盖当前 Windows x64 用户。 先资格验证 WebGPU 跨厂商 GPU 主线，再依据专用后端启动 Gate 投资 DirectML 或厂商 NPU/GPU provider。
保持一套 OCR 语义。 Provider 只替换 inference backend，不能复制 preprocess、postprocess、几何、decode 和结果契约。
保持离线、固定版本和可复现。 稳定包不在首次运行时下载 Windows ML runtime、EP、模型或编译器。
显式选择并证明实际 placement。 Provider 名称、device、precision、graph partition、cache 和 D112 selection trace 都必须可诊断。
限制包体积、冷编译和驱动矩阵。 厂商 EP 的收益必须覆盖约数十到数百 MB 的额外分发成本和持续维护成本；未通过 Gate 就不进入默认 package。

2.2 非目标

不把 DirectML 称为统一 NPU API 或统一 INT8 加速方案。
不把 Windows ML 的 MAX_PERFORMANCE、MAX_EFFICIENCY 等自动策略直接作为稳定默认。
不承诺默认 Windows native package 同时携带全部厂商 EP；只携带通过用户加权收益与包体积 Gate 的 provider。
不默认调用 EnsureReadyAsync() 或 EnsureAndRegisterCertifiedAsync() 下载 EP。
不要求最终用户安装、升级或配置任何厂商 runtime/SDK，也不读取系统 SDK 安装目录拼装运行环境。
不使用 install/postinstall 脚本按 GPU vendor 下载二进制；硬件探测发生在本地 engine 创建阶段，只能选择 package 已包含的能力。
不因 Task Manager 显示 GPU/NPU 活动就宣称完整 graph placement。
不让不同 ORT runtime 或不同 provider addon 在同一进程中无约束共存。
不在第一阶段实现 GPU preprocess/postprocess、外部 D3D12/CUDA context 共享或零拷贝公共 API。
不用无界 page、crop 或 multi-engine 并发换取吞吐数字。

3. 当前官方能力与项目边界

3.1 Windows ML 2.x

截至 2026-07，Windows ML 是 Windows 维护的 ONNX Runtime 分发，支持 x64/arm64、相同的 ORT API、CPU/DirectML 内置 backend，以及通过 EP ABI 注册厂商 provider。

与 light-ocr 直接相关的事实：

Windows ML 2.x 当前稳定包 2.1.74 对应 ORT 1.24.6；2.3.10-preview 对应 ORT 1.27.0，但不能作为稳定依赖。
C/C++ 可以使用 self-contained 部署，runtime、ORT 和 DirectML 总增量约 41 MB，不自动更新，符合严格版本控制方向。
Self-contained 并不统一要求 Windows 11：Microsoft.Windows.AI.MachineLearning 可面向 Windows 10 Build 18362+；需要 RegFree WinRT 时，Microsoft.WindowsAppSDK.ML 可面向 Build 17763+。
Framework-dependent runtime 会由 Windows App SDK servicing 更新，不适合作为第一版可复现 provider 包。
Vendor EP 不包含在约 41 MB runtime 内，需要通过 Windows Update catalog 获取或由应用自行携带。
通过 ExecutionProviderCatalog 动态取得 vendor EP 需要 Windows 11 24H2 Build 26100+；DirectML 和 CPU 是内置例外。BYO EP 不继承这条统一门槛，而是遵守对应厂商 EP、driver 和 OS 要求。
Windows ML 官方建议先显式选择 EP/device，再考虑自动 Device Policy；动态更新和 driver 变化会使设备列表发生变化。

官方依据：

Windows ML 的 C++ 文档要求 C++20，而 light-ocr Core 当前保持 C++17。第一阶段必须验证能否通过 C API 或独立 Windows provider bridge 隔离这一要求，不能为一个 provider 静默提高全部 Core 的语言版本。

3.2 Dynamic catalog 与 Bring Your Own

Windows ML 官方提供两种 vendor EP 获取方式：

方式	优点	与 light-ocr 的冲突/代价	当前定位
Windows ML EP catalog	系统共享、包体积小、自动更新、Windows 认证	首次可能联网下载；受 Windows Update/IT 策略影响；版本和设备列表会动态变化	未来宿主显式授权功能，不作为稳定默认
Bring Your Own EP	精确版本、可离线、企业环境可控	每个 EP 约增加 80 MB 或更多；light-ocr release set 负责升级、许可和兼容	稳定 provider 首选候选，必须随 npm package 交付
使用系统已安装的厂商 SDK/runtime	不增加 npm payload	环境不可复现；用户需要安装和配置依赖；不同 SDK 可能污染进程 DLL 搜索	明确禁止作为产品路径，只可用于开发 benchmark

官方说明 EnsureReadyAsync()/EnsureAndRegisterCertifiedAsync() 会在 EP 不存在时触发下载，首次可能耗时数秒到数分钟。因此 stable runtime 不调用这些 API；可选 catalog 集成必须由宿主在 OCR engine 创建前显式授权，并且不能改变默认离线行为。

依据：

3.3 DirectML

DirectML/ORT DML EP 的优势是 DirectX 12 GPU 广覆盖；它可以覆盖 Intel、AMD、NVIDIA 和 Qualcomm GPU，并可使用系统组件或固定 DirectML redistributable。

限制同样明确：

DirectML 已进入 maintenance mode，Windows ML 文档将它标记为 legacy；没有计划继续增加新功能。
ORT DML EP 要求关闭 memory pattern，并使用 ORT_SEQUENTIAL。
同一个 DirectML session 不允许多线程并发调用 Run；不同 session 才能并发。
输入 shape 在 session 创建时已知时表现最好，固定维度或 free-dimension override 有利于减少 copy/stall 和提高 graph 优化。

因此 DirectML 只保留为 Windows 专用兼容性备选：若专用后端启动 Gate 满足，先用当前 FP32 ONNX 验证兼容性和 offload，再决定是否研究 FP16；它不再承担通用默认基线。

依据：ONNX Runtime DirectML EP、DirectML repository status。

3.4 上游现成实现审计

这里必须区分四层“支持”：模型存在、runtime/EP 能加载、OCR 上游已有接入、以及 light-ocr 当前锁定模型已经通过产品资格审查。前面三层中的任意一层成立，都不能自动推出第四层。

上游	已经存在	不能直接视为可交付的原因	可复用部分
PaddleOCR	官方 PP-OCRv6 ONNX、Paddle/ONNX Runtime/TensorRT/OpenVINO 路线；新统一 ONNX Runtime engine 可以传 `providers` 和 provider options；Windows 有 Paddle Inference C++ 部署	官方 HPI 依赖当前只列 Linux x86-64，Windows 建议 Docker/WSL；公开 PP-OCRv6 表没有 Windows DirectML/NPU 数据；C++ Windows 路线不是当前 light-ocr 的 ORT backend	官方模型、算子/shape、质量指标、通用 engine 配置设计
RapidOCR Python 主线	PP-OCRv6 Tiny/Small/Medium；`onnxruntime-directml` 开关和 Build 18362 检查；OpenVINO；原生 TensorRT FP16/profile/cache builder	是 Python runtime；DirectML 测试只验证 provider 配置，未发现 Windows PP-OCRv6 端到端 CI/benchmark；session 未显式关闭 DML 要求关闭的 memory pattern；OpenVINO 当前硬编码 `CPU`；TensorRT 的 `use_int8` 只设置 builder flag，没有校准器或 QDQ 生成流程	DirectML provider 选择、Windows build 检查、TensorRT dynamic profiles/cache、PP-OCRv6 pipeline 参数
RapidOcrOnnx C++	Windows C++/ORT、CUDA 和 DirectML 示例	旧仓库停留在 ORT 1.12/旧模型；DirectML 只注册到 recognition/classification，detection session 没有注册，不能作为完整 OCR 加速实现	CMake/Windows native 接线参考，不复用其 runtime/model contract
Windows ML / ORT vendor EP	DirectML、OpenVINO、NvTensorRtRtx、MIGraphX、VitisAI、QNN 的通用 EP 与分发机制	Microsoft 明确说明 Windows ML 负责 EP 分发，不负责替应用优化模型；没有 PP-OCRv6 Small 的统一 Windows 优化包	EP ABI、provider 获取/注册、profiling、fallback 和 context/cache 机制
芯片厂商模型库	Intel 有 PaddleOCR/OpenVINO 示例和通用 `pp-ocr` 验证；AMD 有 Ryzen AI OCR 示例；Qualcomm AI Hub 有 EasyOCR/TroCR	Intel 公开 notebook 使用 PP-OCRv3，RapidOCR OpenVINO 当前只走 CPU；AMD 当前 OCR 示例是 Nemotron OCR；Qualcomm 模型库未发现 PP-OCR/PP-OCRv6。都不是当前 PP-OCRv6 Small detector/recognizer 的 Windows NPU 产物	转换、量化、固定 shape、context/compiled-cache 工具链

锁定模型也不同：RapidOCR v3.9.1 的 PP-OCRv6 Small ONNX 声明 SHA-256 为 detector 090f04…、recognizer 6f3272…；light-ocr 当前官方 ONNX 分别是 d73e00…、5435fd…。即使网络语义接近，也必须按不同 bytes 重新验证 graph coverage、数值和性能。

审计依据：

3.5 可复用边界与最小自研量

当前源码已经把 official WebGPU provider package 转为完整自包含 Windows qualification payload：ORT Core 1.24.4、WebGPU plugin 0.1.0、dxcompiler.dll、dxil.dll、addon、schema 2 descriptor、licenses、SPDX SBOM 和 artifact hashes 全部随包。它只替换 inference backend，继续复用现有 preprocess、DB postprocess、crop/sort、CTC decode、资源限制和结果契约。其他厂商路径仍可在开发环境做对照，但发布时同样必须转为固定、自包含 payload。

已实现与待验证边界：

Native WebGPU FP32 实现与真机 Gate 完成： ORT/plugin 与 Dawn/D3D12 companion 已精确锁定，C++/Node FP32 路由、bounded CPU partition、strict fail-closed、profiling、descriptor、npm staging 与 offline verifier 已接线；AMD 780M 已完成 placement、动态 shape、质量、driver、内存和收益验证。
Windows Auto 实现与真机验证完成： D112 webgpu → cpu、固定路径 plugin load、typed adapter absence、fatal package/hash/load、完整 trace 与运行期冻结已实现；AMD 780M 报告中 Auto 实际选择 WebGPU，没有把 CPU fallback 当作成功。
专用后端启动 Gate： 仅当 WebGPU 在预注册设备/workload 上失败或专用路径的用户加权收益足够时，才启动 DirectML、OpenVINO、TensorRT RTX、MIGraphX 或 VitisAI Spike。
厂商模型派生： 需要 FP16/QDQ/BF16 时使用独立 model ID/hash、calibration、shape profile、quality Gate 与 context-cache 生命周期，不重写 OCR 算法。

任何 benchmark 成功只有在干净 Windows VM 上卸载厂商开发 SDK 后，仍能仅凭 npm release set 离线运行，才算完成分发验证。

4. 当前设备与 Provider 矩阵

Windows 设备	候选 provider	首选初始精度	当前项目状态	主要约束
具备合格 D3D12 adapter 的 x64 GPU	Native WebGPU	Auto/显式均为 FP32	产品实现与 AMD Radeon 780M 真机 PG 已完成（164/164）	WebGPU kernel/shape、三类 CPU partition、Dawn、driver、copy、包体
任意兼容 DirectX 12 的 x64 GPU	DirectML	当前 FP32 原样验证；FP16 后续	专用兼容性备选，等待启动 Gate	legacy；固定 shape；同 session 串行
Intel 12th Gen+ GPU	OpenVINO GPU	FP16	x64 候选	需要对应 runtime/driver；验证完整 graph
Intel Core Ultra NPU	OpenVINO NPU	FP16；INT8/QDQ 后续	x64 交互式 NPU 候选	NPU operator/shape coverage；不能接受隐藏 CPU fallback
NVIDIA RTX 30xx+	TensorRT RTX EP	FP16	x64 高性能客户端候选	接近 200 MB 级插件；driver/CUDA；JIT/context cache
AMD GPU	MIGraphX	先以 provider 支持精度资格审查	x64 候选	Windows ML 当前要求严格 driver 组合；BYO 分发路径待确认
AMD Ryzen AI NPU	VitisAI	INT8 或 BF16	x64 NPU 候选	provider-specific quantization；首次编译可能很长；cache 必需
Snapdragon X HTP NPU	QNN	QDQ quantized	Windows arm64 后续	当前不是 Tier 1；需要 context binary 和 arm64 发布矩阵
所有 Windows x64	ORT CPU	FP32	Auto 稳定最终候选、显式 backend	CPU 占用高；保留质量与性能基线

Windows ML 当前公开的 vendor EP 包括 MIGraphX、NvTensorRtRtx、OpenVINO、QNN 和 VitisAI；但“可从 catalog 获取”不等于 light-ocr 已经获得离线分发权、固定兼容矩阵或 PP-OCRv6 完整 graph 支持。

4.1 Intel OpenVINO

OpenVINO EP 可以显式选择 Intel CPU、GPU 或 NPU。官方当前建议 GPU/NPU 使用 FP16，NPU 也支持经 NNCF 等工具生成的 INT8 模型；动态 shape 可以通过 provider 配置变成 static/bounded shape，并支持 model cache。

第一阶段只评估：

Intel GPU FP16；
Intel Core Ultra NPU FP16；
session.disable_cpu_ep_fallback=1 或等价严格模式下的 operator coverage；
static/bounded shape、cache、cold start 和 CPU-s。

只有 FP16 完整通过后才建立 OpenVINO-specific QDQ/INT8 模型，不能直接复用 Apple W8A8 产物或质量结论。

依据：ONNX Runtime OpenVINO EP。

4.2 NVIDIA TensorRT RTX

Windows 客户端优先研究 TensorRT RTX EP ABI plugin，而不是已经 deprecated 的内置 TensorRT RTX EP。官方当前要求 RTX 30xx 及更新架构，支持 shape profiles、CUDA Graph、EP context 和 runtime cache。

PP-OCRv6 Small 包含大量短小 recognition inference，CUDA Graph 和固定 profile 理论上可能减少 CPU launch overhead，但这是待验证假设。第一阶段保持 FP16；INT8 或其他低精度只有在插件版本明确支持、校准质量通过且端到端收益足够时才进入。

依据：ONNX Runtime TensorRT RTX EP。

4.3 AMD MIGraphX 与 VitisAI

AMD 路径不能合并为一个 provider：

MIGraphX 是 AMD GPU provider。Windows ML 已提供对应 EP，但当前公开矩阵有严格 driver 要求，稳定 BYO package、模型精度和 PP-OCRv6 graph coverage 均需单独确认。
VitisAI 是 Ryzen AI NPU provider。官方 ORT 文档支持 INT8/BF16 量化模型，并在 session 创建时编译为设备执行文件；首次编译可能达到分钟级，必须依赖按模型/设备正确失效的 cache。

VitisAI 的量化模型是 AMD-specific 派生物，不能把 Apple W8A8、OpenVINO INT8 或 QNN QDQ 当作同一份可互换模型。

依据：Windows ML provider matrix、ONNX Runtime VitisAI EP。

4.4 Qualcomm QNN

QNN HTP 路径需要适配 QNN 的 QDQ 模型和 context binary。官方示例在 Windows arm64 上使用量化模型，并提供禁用 CPU fallback、context cache 和 HTP profiling 能力。

QNN GPU backend 可以运行 FP16/FP32，但 Snapdragon X 的主要产品价值是 HTP NPU。由于 Windows arm64 仍是 deferred target，本方案只保留模型和 backend 接口兼容性，不为当前 Windows x64 包携带 QNN。

依据：ONNX Runtime QNN EP。

5. 推荐运行时架构

5.1 保持一套 OCR Core

现有 C++ preprocess、detection postprocess、geometry、crop、CTC decode、资源限制和结果组装保持权威。Windows provider 只实现内部 inference session：

DetectionSession
  run(float tensor, exact shape) -> float probability map

RecognitionSession
  run(float tensor, exact shape) -> float logits

Provider-specific 量化模型如果改变输入/输出 dtype、scale 或 zero-point，转换只允许发生在 backend/bundle contract 中，不能泄漏成另一套公共 OCR 结果语义。

5.2 推荐 runtime 选择

当前产品 runtime 已选择 pinned ORT Core 1.24.4 + Native WebGPU plugin 0.1.0 + Dawn/D3D12 companions，以 Windows x64 私有目录自包含交付。Windows ML 2.x / DirectML 保留为专用备选对照：

WebGPU 与 Linux 共享 provider API 和 ONNX 模型资格方法，在 Windows 由 Dawn 映射 D3D12/Vulkan；
NuGet URL/catalog、bytes/SHA-512、plugin upstream tag/commit、headers、DLL paths、licenses 与 session options 已精确锁定，不依赖系统安装的 ORT、SDK 或动态 catalog；
Windows ML 的 EP ABI 仍可承载通过专用 Gate 的 vendor plugin，但不决定通用默认；
所有方案都与现有 ONNX model 和 backend-neutral session 边界保持一致。

这里的 self-contained 是 package 内自包含，不是让用户安装 Windows App SDK runtime。@arcships/light-ocr-win32-x64 必须把实际需要的 DLL 放进固定私有目录并使用受控加载路径；engine 创建不得依赖系统 PATH、Python site-packages、CUDA toolkit、OpenVINO 安装目录或全局 Windows ML framework package。

WebGPU qualification 不以 DirectML 对照为前置条件。只有专用后端启动 Gate 接受 Windows ML/DirectML 后，才在 self-contained Windows ML 与 standalone DML-enabled ORT 之间做同条件选择；届时至少比较固定版本与更新策略、C++20/bridge 边界、EP ABI、CPU package 共存、placement、性能、CPU-s、冷启动和包体积。未启动该 Gate 时，不为维持旧路线提前引入 Windows ML runtime。

5.3 一个公共入口与内部 provider 隔离

用户可见拓扑保持当前 npm packaging contract：

@arcships/light-ocr
├── required: @arcships/light-ocr-model-ppocrv6-small
└── optional, npm selects exactly one by os/cpu
    ├── @arcships/light-ocr-darwin-arm64
    ├── @arcships/light-ocr-darwin-x64
    ├── @arcships/light-ocr-linux-x64-gnu
    └── @arcships/light-ocr-win32-x64
        ├── baseline native addon + pinned runtime
        ├── Native WebGPU + CPU
        └── zero or more accepted specialized EP payloads

厂商 payload 是否物理放在同一个 tarball，或由 @arcships/light-ocr-win32-x64 依赖内部、同版本、Windows-only shard，是 release staging 的实现细节；二者都会在一次 npm install @arcships/light-ocr 中完成，不能要求用户再安装 provider package。

运行时隔离规则：

WebGPU 主线优先让 CPU 与 WebGPU plugin 共享一份兼容 ORT Core；Windows ML/DirectML/vendor EP 只有专用 Gate 通过后才进入共存设计。
D112 Auto 只尝试 runtime descriptor 声明且 package 实际携带的候选；失败候选必须完整销毁部分状态。不能安全卸载或与后续候选 ABI 不兼容的 runtime 必须先放入受控 worker 隔离，否则无资格进入同一候选链。
显式 provider 不跨 backend 回退；Auto 只对 D112 的四类可跳过创建原因继续，致命包/ABI/load 错误立即返回。首版 Auto 仅接受 provider-neutral 默认值，strict placement、显式 precision、device ID 和 throughput 资格测试使用显式 provider。
如果某个厂商最优路线只能使用独立 runtime，它必须作为 package 内部 backend/worker 隔离，仍由同一个 facade 自动选择和管理；其进程、IPC、关闭、崩溃和包体积必须单独通过 Gate。
禁止扫描系统 SDK、注册表或 PATH 猜测可用 runtime。
npm 不按 GPU vendor 过滤依赖。每增加一个默认 vendor payload，所有 Windows x64 安装都会承担其下载和磁盘成本，因此 provider 接受决策必须使用用户加权收益，而不是单机最快数字。

6. Shape 与模型派生物

6.1 公共 shape contract

Windows provider 共享一份版本化的逻辑 shape policy，但不强迫所有 EP 使用相同编译格式：

Detector 保持 bounded/960 语义，使用经过资格审查的 exact shape 或 padding bucket。
Recognition 继续限制最大宽度 3200，使用少量质量通过的 width bucket 或 provider profile。
额外 padding、round-up、输出裁剪和坐标恢复必须通过现有 parity/quality corpus。
未覆盖 shape 必须使用已声明的 provider 路由或稳定失败，不能临时生成无界 session/cache。

6.2 Provider-specific 形式

Provider	推荐 shape 形式	风险
DirectML	fixed model 或 session free-dimension override；少量 bucket session	session 数和显存/RSS；不支持同 session 并发 Run
OpenVINO	bounded/static reshape + model cache	NPU operator coverage；dynamic→static 行为
TensorRT RTX	min/opt/max profile；必要时 multi-profile + EP context	JIT、profile 选择、cache 与具体 GPU
VitisAI	量化 fixed/bounded 模型 + compiled cache	首次分钟级编译；cache 正确失效
QNN	QDQ fixed shape + context binary	arm64/device/SDK 绑定；量化质量

Apple 的 EnumeratedShapes 不能照搬到 Windows。Windows 需要一个逻辑 bucket 集，随后为不同 EP 生成各自的 profile/context/model 派生物。

7. 精度与量化策略

Provider/硬件	第一阶段	第二阶段	不应假设
DirectML GPU	当前 FP32 ONNX 原样验证	保持 FP32 I/O 的 FP16 派生模型	DirectML 会自动把 FP32 模型变成最优 FP16，或 INT8 一定跨厂商更快
OpenVINO Intel GPU	FP16	provider-specific INT8/QDQ	与 Intel NPU 结果相同
OpenVINO Intel NPU	FP16	NNCF/QDQ INT8	所有算子会自动留在 NPU
TensorRT RTX GPU	FP16	provider 明确支持且质量通过的低精度	复用 Apple Core ML 量化模型
VitisAI AMD NPU	INT8 或 BF16	QAT/混合精度	FP16 ONNX 可以不经处理获得 NPU 最优路径
QNN HTP NPU	QNN-compatible QDQ	按硬件支持选择量化 dtype	统一等同于 W8A8
CPU	当前 FP32	独立 CPU INT8 研究	用 NPU/GPU 模型替换稳定 CPU oracle

Windows 上的“INT8”不是一种通用产物。至少需要区分 OpenVINO INT8、VitisAI INT8、QNN QDQ 和未来 NVIDIA 低精度模型；它们的校准规则、支持算子、context 和质量证据都不同。

量化流程统一遵守：

先让 FP32 provider 完成 placement 并建立质量基线；
锁定 provider-specific calibration corpus 和指标；
PTQ 不通过则 QAT 或保留敏感层高精度；
质量先过 Gate，再跑正式性能数字；
每个 provider-specific 量化模型拥有独立 model ID、hash 和 compatibility manifest。

8. 调度、并发与 CPU 预算

Windows interactive profile 初始仍保持一个 engine 一个 active call：

DirectML session 明确禁止多线程并发 Run，必须串行；
OpenVINO stream、TensorRT CUDA Graph、多 session 和厂商 throughput option 只在独立 throughput profile 中研究；
PDF renderer 最多有界预取下一页，是否与 OCR 重叠取决于总 CPU-s、RSS 和 UI 响应；
recognition batch 默认 1，扩大 batch 必须同时报告 latency、throughput 和质量；
GPU/NPU queue、device lost、driver reset、close 和进程退出必须有稳定错误与资源释放语义。

交互式模式的目标是 CPU 不与用户前台任务争抢。把 iGPU/NPU 跑满也可能影响 UI、视频或其他系统 AI workload，因此需要报告 device contention，而不是只报告吞吐。

9. 分发、缓存与供应链

稳定 Windows platform package 的产物至少包括：

@arcships/light-ocr-win32-x64 release payload
├── native addon and pinned self-contained runtime
├── Native WebGPU + CPU baseline
├── accepted vendor EP/runtime payloads
├── provider-specific model/profile/context artifacts
├── platform runtime descriptor（D112 policy/artifacts/ABI）
├── capability, OS and driver manifest
├── licenses / SBOM / provenance / artifact hashes
└── cache version and invalidation contract

规则：

当前 WebGPU qualification package 精确包含 light_ocr_node.node、onnxruntime.dll、onnxruntime_providers_webgpu.dll、dxcompiler.dll 与 dxil.dll；descriptor 的 exact inventory、bytes 和 SHA-256 在 addon 加载前复核，provider DLL 在注册前再复核。
Self-contained runtime 和 EP plugin 精确锁定版本；升级必须重新跑全部 Gate。
Vendor EP 的 driver minimum/maximum、GPU/NPU family、Windows build 和 ORT ABI 写入 manifest。
Cache key 至少包含 model hash、provider/ORT version、precision、shape policy、device/driver compatibility key。
Cache 路径不能使用不安全的全局临时目录；必须有大小上限、权限检查、原子写入和损坏恢复。
显式 provider 的首次编译/创建失败直接返回。只有 provider=auto 且 typed reason 属于 D112 可跳过集合时，才销毁候选状态并尝试 CPU；包损坏、hash/ABI 不匹配或不可恢复加载失败立即终止，不得解析异常消息猜测分类。
用户安装入口固定为 @arcships/light-ocr。内部 native/provider shard 如果存在，必须由 facade/native package 的 exact-version dependency 自动取得，不能成为用户操作步骤。
默认 Windows package 不以“支持越多越好”为目标。每个 vendor payload 必须分别披露压缩下载、解包大小、DLL 数、license 和 CVE/升级责任；未通过 package-size Gate 就不进入默认 release set。
禁止 install/postinstall 下载 runtime、根据本机 GPU 现场编译 provider、访问厂商安装器，或从全局 DLL 搜索路径借用未锁定组件。
Release qualification 必须在没有 Paddle、Python、CUDA toolkit、TensorRT SDK、OpenVINO SDK、Ryzen AI SDK 和 QNN SDK 的干净 VM 上，从 npm tarball 离线安装并运行。目标机只允许预装操作系统和正常硬件 driver。
Official Windows binaries 依赖 Microsoft Visual C++ 2015-2022 x64 runtime；这是与 D3D12 driver 同级的明确系统前置条件，不从 PATH 借用项目 runtime。
Dynamic catalog、Windows Update 和 framework-dependent runtime 如未来开放，必须是宿主明确选择的另一种分发 profile，不能改变稳定 self-contained 语义。

10. 公共策略与可观测性

正式资格工具先使用显式 provider，用户默认方向使用 D112 Auto：

auto: webgpu → cpu
explicit: cpu | webgpu
specialized after independent Gate: directml | openvino | nvtensorrtrtx | vitisai | migraphx
future Windows arm64: qnn

只有已经通过 Provider Gate、由 Windows runtime descriptor 声明且实际随 package 交付的名称才进入正式 union 和 Auto policy。显式 provider 失败不转 CPU；Auto 只按 D112 的 typed 创建失败分类继续，并仅接受 provider-neutral 默认选项。任何 sessionFallback=cpu 都返回 invalid_argument。它不能下载 provider、扫描系统安装或接受任意 DLL 路径。Windows ML 的 MAX_EFFICIENCY 等 Device Policy 继续保持实验性，不能替代项目的版本化候选序。

诊断至少报告：

字段	含义
requested provider/profile	用户请求值
runtime / ORT / EP version	实际加载的固定版本
OS build / architecture	Windows build、x64/arm64
hardware device	CPU/GPU/NPU、vendor、adapter/device ID；不上传稳定设备标识
driver version	实际资格审查输入
detector/recognizer model ID	precision、shape policy、hash
actual provider chain	每个 session 的真实链
graph placement	qualification profiling 的 node/subgraph coverage
selection trace	成功 `EngineInfo` 含 policy ID/version、候选顺序、零或多个 `skipped` 与唯一 `selected`；创建失败 trace 由结构化 creation error 承载
compile/cache	cold compile、cache hit/miss、context ID
effective concurrency	session、stream、batch、engine admission

Release qualification 必须开启 ORT/provider profiling，并在可用时禁用 CPU EP fallback。GetProviders()、GetEpDevices() 和 Task Manager 只能证明 provider/device 可见，不能单独证明 PP-OCRv6 全 graph 执行位置。

11. 最简 Benchmark Contract

Windows 与 Apple 使用同一份用户可读 scoreboard：

模式	15 页总耗时	PDF render	OCR-only	OCR CPU-s / 平均 CPU core	Peak RSS/VRAM	质量
Windows CPU low-impact	待测	单列	待测	待测	待测	CPU oracle
Windows CPU fast	待测	单列	待测	待测	待测	CPU oracle
Native WebGPU FP32 / AMD Radeon 780M	14-fixture P50 总和 2,669.160 ms	单列	相对 CPU 6,500.853 ms 为 2.436×	报告记录	warmup-aware lifecycle -22.9 MiB	14/14 字节级一致，164/164 Gate
DirectML FP32/FP16 备选	启动 Gate 后	单列	待测	待测	待测	待测
OpenVINO NPU/GPU FP16	待测	单列	待测	待测	待测	待测
TensorRT RTX FP16	待测	单列	待测	待测	待测	待测
AMD provider	待测	单列	待测	待测	待测	待测
QNN HTP	Windows arm64 接受后	单列	待测	待测	待测	待测

正式报告另外保存 cold runtime load、provider registration、model compile、first inference、cache hit/miss、warm P50/P95、driver、电源模式、device placement、CPU partition 和 D112 selection trace。

同一个数字不能代表“Windows”：至少要区分 iGPU、dGPU、NPU、vendor 和设备代际。每个 provider 的首次 Gate 至少需要两台预注册设备；WebGPU Windows Preview 至少跨两个 GPU vendor。

11.1 Provider Gate

Windows provider 继承 Roadmap PG，并增加以下要求：

默认 one-command suite 覆盖锁定 14-fixture corpus，每个正常 case 执行 3 次独立 engine cold start、每次 2 次 warmup + 10 次测量（合计 30 次）；至少两个 fixture P50 speedup ≥1.5，P50 总和 speedup ≥1.1，任一 fixture WebGPU P95 ≤CPU 3×；
OCR process CPU-s/average cores 进入报告和发布范围审查，不使用 runner 未强制的目标冒充自动 Gate；
qualification 中禁止未声明 CPU EP fallback，关键 graph placement 达到预注册要求；
公共 contract 100% 通过，FP16/INT8/BF16 的质量容差在查看最终性能前锁定；
canary initialization + first result ≤30 s、resident maximum ≤2 GiB、20 次 lifecycle retained growth 绝对值 ≤128 MiB；device memory/driver 范围由真机报告补充；
device unavailable、driver 不兼容、cache 损坏、device lost 和 session failure 都有稳定行为；
Windows platform/provider payload 保持完全离线且解包后的自包含 native payload ≤256 MiB，dynamic catalog profile 除外且必须由宿主显式授权。

12. 分阶段落地

Phase A — Native WebGPU Windows qualification

已固定 ORT Core 1.24.4、WebGPU plugin 0.1.0、Dawn/D3D12 companion、artifact hashes 与 qualification identity。
已实现 FP32 detector/recognizer 路由、bounded allow、strict fail-closed、Auto、C++/Node diagnostics、profiling 和 14-fixture one-command runner；FP16 不进入 0.3.0 WebGPU 公共 profile。
已实现从实际 payload 生成的 npm descriptor、license/SBOM、sterile cwd load 和离线 runtime/package cache 复装。
已在 AMD Radeon 780M 上运行完整 Gate；显式 FP32 allow 证明 placement，strict 证明稳定拒绝，Auto 与 native C++ 均实际选择 WebGPU。

退出条件：WebGPU 得到接受、缩减或拒绝结论；未通过前 released Auto policy 仍只包含实际已交付候选。

Phase B — D112 Auto 与自包含 Preview

Windows webgpu → cpu 创建期原子候选链、typed 失败分类和同构 selection trace 已实现。
hardware-independent tests 已验证致命 descriptor/artifact 错误停止、显式 provider 不回退、旧 sessionFallback=cpu 被拒绝；真机继续验证 adapter、session close 与运行期冻结。
Gate 通过后才把 report/artifact hashes 和 compatibility range 写入 production lock；否则保持 qualification-only 或拒绝。

退出条件：WebGPU 被接受为 Windows 通用 Preview，且 Auto 行为可审计；否则记录缩减范围或拒绝证据。

Phase C — DirectML 与当前 x64 厂商 provider

只有专用后端启动 Gate 满足时才进入，顺序由 Perf-0 用户覆盖决定：

WebGPU 未覆盖的 DX12 设备占比足够高：DirectML FP32，再决定是否研究 FP16；
Intel 用户权重高：OpenVINO GPU/NPU FP16，然后 INT8；
NVIDIA RTX 用户权重高：TensorRT RTX FP16、profile、CUDA Graph 和 context cache；
AMD Ryzen AI 用户权重高：分别验证 MIGraphX GPU 与 VitisAI NPU。

每个 provider 独立通过 Gate 和 package review，不因另一个 provider 成功而自动发布。厂商开发环境中的 benchmark 只决定技术候选；最终还必须证明 runtime/EP 能被合法、固定、离线地装入 @arcships/light-ocr 的 Windows release set。不能满足这一点时，结论是“不进入默认 package”，而不是把安装 runtime 的责任交给用户。

Phase D — Windows arm64/QNN

只有 D110 接受 Windows arm64 后才建立 arm64 native、Node、模型和 CI 矩阵。
为 QNN HTP 生成独立 QDQ/context 模型并验证 Snapdragon X。
不从 x64 DirectML/OpenVINO/VitisAI 结果推断 arm64 性能或质量。

13. 仍需真机 Gate 决定的问题

用户的 Windows GPU/driver 是否通过 FP32 placement/质量、strict rejection、冷启动、性能、RSS 和 lifecycle Gate？AMD Radeon 780M 记录设备已通过；新增设备需独立回答。
最低 Windows build、D3D12 driver、feature/limit 与设备族如何写入 compatibility range？
Recognition 的 Concat/Gather/Slice 有界 CPU partition 是否可接受，最低 placement coverage 与产品文案如何锁定？
单一 Windows platform package 的压缩下载、解包大小和实际用户收益是否值得默认携带 WebGPU？
哪些设备/workload 失败足以启动 DirectML 或厂商 backend，而不是缩减 WebGPU 范围？
Stable 是否完全禁止 Windows ML catalog 下载，还是未来提供宿主显式授权、与自包含路径分开的 profile？
Windows arm64 何时进入 Tier 1，从而允许 QNN 成为实际产品路径？

14. 与 Apple 方案的关键差异

维度	Apple Device	Windows Device
统一硬件	Apple GPU/ANE，由 Core ML 管理	无统一 NPU；GPU/NPU provider 按厂商分裂
主要 INT8 路径	新硬件 ANE W8A8	OpenVINO/VitisAI/QNN/NVIDIA 各自定义，不能共用一种 INT8 模型
广覆盖 GPU	Core ML GPU	Native WebGPU；DirectML 是 legacy/maintenance 专用备选
Runtime 选择	Direct Core ML 已选	固定 ORT Core + WebGPU plugin + Dawn；Windows ML/厂商 EP 需独立 Gate
Shape	Core ML enumerated shapes	DML fixed override、OpenVINO bounds、TensorRT profiles、NPU context
分发	facade 自动选择 Apple native package；runtime/model 随包交付	facade 自动选择 Windows native package；runtime/EP/model 随包交付，用户不安装厂商 SDK
当前平台缺口	iOS/iPadOS 不在 Tier 1	Windows arm64 不在 Tier 1，QNN 延后

15. 关联工作

本方案的跨 backend 选择受 D112 约束；每个 Windows provider 的硬件、driver 和模型证据继续保留在独立 issue 与 qualification report 中，只有通过 Gate 的范围才能进入 runtime descriptor。

Navigation Menu

Uh oh!

Windows Device 加速技术方案

1. 结论

1.1 `0.3.0` Windows 真机结论

2. 目标与非目标

2.1 目标

2.2 非目标

3. 当前官方能力与项目边界

3.1 Windows ML 2.x

3.2 Dynamic catalog 与 Bring Your Own

3.3 DirectML

3.4 上游现成实现审计

3.5 可复用边界与最小自研量

4. 当前设备与 Provider 矩阵

4.1 Intel OpenVINO

4.2 NVIDIA TensorRT RTX

4.3 AMD MIGraphX 与 VitisAI

4.4 Qualcomm QNN

5. 推荐运行时架构

5.1 保持一套 OCR Core

5.2 推荐 runtime 选择

5.3 一个公共入口与内部 provider 隔离

6. Shape 与模型派生物

6.1 公共 shape contract

6.2 Provider-specific 形式

7. 精度与量化策略

8. 调度、并发与 CPU 预算

9. 分发、缓存与供应链

10. 公共策略与可观测性

11. 最简 Benchmark Contract

11.1 Provider Gate

12. 分阶段落地

Phase A — Native WebGPU Windows qualification

Phase B — D112 Auto 与自包含 Preview

Phase C — DirectML 与当前 x64 厂商 provider

Phase D — Windows arm64/QNN

13. 仍需真机 Gate 决定的问题

14. 与 Apple 方案的关键差异

15. 关联工作

Uh oh!

FilesExpand file tree

windows-device-acceleration.md

Latest commit

History

windows-device-acceleration.md

File metadata and controls

Windows Device 加速技术方案

1. 结论

1.1 0.3.0 Windows 真机结论

2. 目标与非目标

2.1 目标

2.2 非目标

3. 当前官方能力与项目边界

3.1 Windows ML 2.x

3.2 Dynamic catalog 与 Bring Your Own

3.3 DirectML

3.4 上游现成实现审计

3.5 可复用边界与最小自研量

4. 当前设备与 Provider 矩阵

4.1 Intel OpenVINO

4.2 NVIDIA TensorRT RTX

4.3 AMD MIGraphX 与 VitisAI

4.4 Qualcomm QNN

5. 推荐运行时架构

5.1 保持一套 OCR Core

5.2 推荐 runtime 选择

5.3 一个公共入口与内部 provider 隔离

6. Shape 与模型派生物

6.1 公共 shape contract

6.2 Provider-specific 形式

7. 精度与量化策略

8. 调度、并发与 CPU 预算

9. 分发、缓存与供应链

10. 公共策略与可观测性

11. 最简 Benchmark Contract

11.1 Provider Gate

12. 分阶段落地

Phase A — Native WebGPU Windows qualification

Phase B — D112 Auto 与自包含 Preview

Phase C — DirectML 与当前 x64 厂商 provider

Phase D — Windows arm64/QNN

13. 仍需真机 Gate 决定的问题

14. 与 Apple 方案的关键差异

15. 关联工作

1.1 `0.3.0` Windows 真机结论