PaddleOCR.js 浏览器端架构解析SDK 包结构、Worker 执行模型与 WASM 加载策略【免费下载链接】PaddleOCR飞桨多语言OCR工具包实用超轻量OCR系统支持80种语言识别提供数据标注与合成工具支持服务器、移动端、嵌入式及IoT设备端的训练与部署 Awesome multilingual OCR toolkits based on PaddlePaddle (practical ultra lightweight OCR system, support 80 languages recognition, provide data annotation and synthesis tools, support training and deployment among server, mobile, embedded and IoT devices)项目地址: https://gitcode.com/paddlepaddle/PaddleOCR本篇技术指南围绕 paddleocr-js 架构文档中文版见 architecture_cn.md展开系统讲解 PaddleOCR 在浏览器端的 JavaScript SDK 内部架构packages/core与apps/demo的分层关系、PaddleOCR.create()高层的五步协调流程、主线程与 Worker 两种执行模式的完整调用链、以及 ONNX Runtime Web 的 WASM 二进制加载策略。读完本文你将掌握paddleocr/paddleocr-js的代码组织方式、Worker 模式下init/predict/dispose的端到端消息流转并能正确配置ortOptions.wasmPaths与模型资源在自己的宿主应用中接入浏览器端 OCR。一、项目结构SDK 与宿主应用分离paddleocr-js目录采用典型的 monorepo 思维划分为两个核心部分packages/core浏览器 PaddleOCR SDK发布到 npm 时包名为paddleocr/paddleocr-js负责 OCR 运行时初始化与推理编排apps/demo一个消费该 SDK 的 PP-OCR 演示应用负责界面、状态提示与结果可视化。这种SDK 只做推理编排、宿主应用管 UI 与资源托管的分工是理解整个架构的出发点SDK 不关心按钮、上传框或结果表格它只暴露PaddleOCR.create()、predict()等能力接口宿主应用则通过配置项把模型 URL、WASM 路径、Worker 工厂等运行环境信息注入 SDK。演示应用的入口 apps/demo/src/main.ts 是理解这套分工的最佳范例它直接import { PaddleOCR } from paddleocr/paddleocr-js创建引擎后调用predict(file)再用 SDK 的viz模块做可视化其余 UI 逻辑全部由应用自身管理。二、SDK 包布局packages/corepackages/core的src/目录按职责划分为九个模块对应架构文档中的目录树目录均位于 paddleocr-js/packages/core/src/src/ ├── runtime/ — 推理运行时初始化OpenCV.js、ONNX Runtime Web ├── resources/ — 模型与资源管理模型资产下载 ├── models/ — 模型接线检测模型 det、识别模型 rec ├── platform/ — 浏览器 / Worker 输入适配 ├── worker/ — Worker 传输层客户端、入口、协议 ├── pipelines/ — 产线实现OCR 产线核心 ├── viz/ — 可视化可选 ├── types/ — 外部库类型声明opencv、clipper-lib 等 └── utils/ — 共享工具从源码结构看各目录的依赖关系大致是单向的platform与runtime属于底层适配层models在两者之上构建检测/识别模型封装pipelines/ocr作为最高层产线把上述全部组装起来而worker传输层与viz分别负责跨线程通信与可视化这两个横切关注点。runtime/opencv.ts初始化 OpenCV.js 运行时runtime/ort.ts初始化 ONNX Runtime Web检测 WebGPU 可用性并创建推理会话models/det.ts、models/rec.ts分别封装文本检测与文本识别模型的创建、预测与释放pipelines/ocr/core.tsOcrPipelineRunner产线核心串联检测 → 裁剪 → 识别的完整推理流程。三、高层入口PaddleOCR.create()的五步协调当前高层产线入口为PaddleOCR.create()定义于 paddleocr-js/packages/core/src/index.ts它负责协调五个步骤运行时初始化加载 OpenCV.js 与 ONNX Runtime Web 模块执行后端选择在 WebGPU 与 WASM 之间选择推理执行后端auto时优先 WebGPU不可用则回退 WASM见 runtime/ort.ts 的getProviderCandidates模型下载按model_name从默认资产表或用户提供的 URL 拉取检测/识别模型推理会话创建调用onnxruntime-web的InferenceSession.create创建会话graphOptimizationLevel: allOCR 产线执行对外暴露predict()完成检测与识别。源码层面create的静态实现index.ts先通过resolveWorkerOptions判断是否启用 Worker再调用resolvePaddleOCROptions归一化全部选项最后按模式实例化PaddleOCR或WorkerBackedPaddleOCR除非显式传入initialize: false否则创建后会自动执行initialize()。initialize()见 pipelines/ocr/core.ts内部依次完成OpenCV 运行时初始化 → ORT 运行时初始化含 WebGPU 探测→ 并行下载检测与识别模型资产 → 校验模型model_name与期望值一致validateLoadedModelName→ 并行创建两个 ONNX 会话 → 返回InitializationSummary包含 backend、webgpuAvailable、detProvider、recProvider、assets 下载摘要与耗时。四、两种执行模式主线程与 WorkerPaddleOCR.create()通过worker选项支持两种执行模式主线程模式默认返回PaddleOCR直接在调用线程上执行 OCRWorker 模式传入{ worker: true }时返回WorkerBackedPaddleOCR将 OCR 生命周期调用转发到独立 Worker避免模型推理阻塞页面主线程。worker选项既可以是布尔值也可以是{ createWorker?: () Worker }对象允许宿主应用注入自定义 Worker 工厂解析逻辑见 pipelines/ocr/shared.ts 的resolveWorkerOptions。需要说明的是从源码看 Worker 模式不支持自定义fetch实现create中会显式抛出worker mode does not support a custom fetch implementation.。两种模式共享同一份OcrPipelineRunner核心逻辑区别仅在于运行位置与输入适配主线程模式由PaddleOCR类把ensureServedFromHttp与sourceToMat注入OcrPipelineRunnercore.tsWorker 模式由WorkerBackedPaddleOCR在 Worker 内部构造OcrPipelineRunner并注入 Worker 侧的sourcePayloadToMat见 pipelines/ocr/worker-entry.ts。Worker 模式下的六步运行流程架构文档给出了 Worker 模式的完整链路结合源码可还原每一步的实现位置创建PaddleOCR.create({ worker: true })解析 OCR 选项并创建WorkerBackedPaddleOCR转发请求WorkerBackedPaddleOCR通过WorkerTransportClient发送init/predict/dispose三类请求默认 Worker 工厂OCR 产线层持有默认 Worker 工厂指向 pipelines/ocr/worker-entry.ts——默认工厂通过new Worker(new URL(./worker-entry.ts, import.meta.url), { type: module })创建模块化 Worker见 worker-backed.ts绑定引导逻辑worker-entry.ts调用通用引导函数attachWorkerMessageHandler把 worker/entry.ts 中的通用 Worker 消息分发与 OCR 专用 handlerinit/predict/dispose三个分支绑定Worker 内推理OcrPipelineRunner在 Worker 内运行 OpenCV.js、ONNX Runtime Web、模型加载、检测与识别handler 中通过sourcePayloadToMat把主线程传来的负载还原为cv.Mat运行时输入结果回传结果与错误经postMessage序列化回主线程主线程侧按requestId匹配 Promise 并 resolve/reject见 worker/client.ts 的onmessage处理。传输层与消息协议Worker 传输层worker/protocol.ts定义了一套带requestId的请求/响应协议主线程侧WorkerTransportClient维护pending: Mapnumber, PendingRequest待决请求表每次request()递增requestId后postMessage收到响应后按requestId取出对应 Promise 完成错误则通过serializeError/deserializeError在两侧还原 Error 对象。dispose()时还会 reject 所有未决请求并worker.terminate()保证资源彻底回收。输入处理按环境拆分输入适配是两种模式的关键差异主线程platform/browser.ts的sourceToMat把浏览器输入如File、ImageBitmap、HTMLImageElement标准化为cv.Mat同时ensureServedFromHttp校验页面必须通过 HTTP(S) 服务避免file://协议下资源加载失败Worker主线程侧sourceToWorkerPayload先把输入转换为可结构化克隆/可转移transferable的负载Worker 侧platform/worker.ts的sourcePayloadToMat再重建为cv.Mat。架构文档强调Worker 模式使用包内 Worker 路径并在内部显式关闭 ONNX Runtime Web 的 wasm proxydisableWasmProxy: true见 worker-backed.ts。这样可以避免SDK 的 Worker 再套一层 ORT 的 Worker proxy造成双层 Worker 叠加让包自身负责并发模型。五、WASM 加载策略与ortOptions.wasmPathsONNX Runtime Web 在运行时需要 WASM 二进制文件。ortOptions.wasmPaths是一个对两种执行模式统一生效的配置——设置一次即可同时控制主线程与 Worker 两侧的 WASM 加载位置PaddleOCR.create({ ortOptions: { wasmPaths: /assets/ } });源码层面wasmPaths会被写入ort.env.wasm.wasmPaths见 runtime/ort.ts 的applyOrtEnvironmentOptions因此它对主线程与 Worker 内的 ORT 实例同样有效。当wasmPaths未设置时两种模式的回退行为不同主线程模式ORT 通过使用方的打包工具解析 WASM——打包工具会把node_modules/onnxruntime-web/dist/下的.wasm文件拷贝到构建产物并自动改写 URLWorker 模式SDK 回退到与构建时安装的 ORT 版本绑定的 CDN URL源码中通过编译期常量__ORT_WASM_CDN_PREFIX__注入并在控制台输出 warning建议消费者显式设置ortOptions.wasmPaths见 worker-backed.ts。因此架构文档明确建议在 Worker 模式下显式设置ortOptions.wasmPaths以保证两种模式使用同一套 WASM 版本避免 CDN 回退版本与主线程打包产物版本不一致带来的行为差异。演示应用 apps/demo/src/main.ts 给出了一个贴近实战的ortOptions组合包括backendauto/webgpu/wasm 三选一、wasmPaths、numThreads基于crossOriginIsolated与hardwareConcurrency动态计算线程数与simd: truefunction getRuntimeOptions() { return { backend: ui.runtimeBackend.value as auto | webgpu | wasm, wasmPaths: ORT_WASM_PATHS, numThreads: getDemoThreadCount(), simd: true }; }六、应用侧职责SDK 之外你需要自己负责的部分架构文档最后明确了职责边界SDK 负责 OCR 运行时初始化与推理编排但宿主应用仍需负责运行环境所需的部署响应头例如多线程 WASM 需要的Cross-Origin-Isolation相关响应头demo 中getDemoThreadCount()会检测crossOriginIsolated静态资源托管与模型 URL 配置模型文件与 WASM 二进制需要由应用托管或通过 URL 提供Worker 支持worker: true场景下需要打包工具/运行时支持产出并加载 Worker默认使用new Worker(..., { type: module })应用界面、状态提示与可视化SDK 的可视化能力是可选模块paddleocr/paddleocr-js/vizUI 交互仍由应用实现。架构文档中强调apps/目录正是这类宿主应用的载体。演示应用完整展示了这套职责分工初始化时先dispose()旧引擎再重建、展示InitializationSummary中的 backend/provider/耗时指标、predict 后渲染检测框并列出识别结果与置信度、以及未初始化完成不可运行的按钮状态管控。七、小结PaddleOCR.js 的架构核心可以概括为三点职责分离packages/core提供纯推理编排的 SDKapps/demo承担宿主应用职责双执行模式主线程模式与 Worker 模式共享OcrPipelineRunner核心差异被隔离在platform/输入适配与worker/传输层两个模块中Worker 模式下显式关闭 ORT wasm proxy 以避免双层 Worker统一的运行时配置ortOptions.wasmPaths一处配置、双模式生效Worker 模式务必显式设置以保证 WASM 版本一致性。如果希望深入实践建议依次阅读 architecture.md或中文版 architecture_cn.md、SDK 导出入口 packages/core/src/index.ts、产线核心 pipelines/ocr/core.ts、Worker 传输层 worker/client.ts 与 worker/protocol.ts再对照演示应用 apps/demo/src/main.ts 实际运行一遍即可完整掌握这套浏览器端 OCR 架构。【免费下载链接】PaddleOCR飞桨多语言OCR工具包实用超轻量OCR系统支持80种语言识别提供数据标注与合成工具支持服务器、移动端、嵌入式及IoT设备端的训练与部署 Awesome multilingual OCR toolkits based on PaddlePaddle (practical ultra lightweight OCR system, support 80 languages recognition, provide data annotation and synthesis tools, support training and deployment among server, mobile, embedded and IoT devices)项目地址: https://gitcode.com/paddlepaddle/PaddleOCR创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考