PaddleOCR.js 浏览器端部署在 Web 前端直接运行 PP-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/PaddleOCRPaddleOCR.js 是 PaddleOCR 官方提供的浏览器端 OCR SDK它通过 WebAssembly / WebGPU 在客户端直接运行完整的 PP-OCR 检测与识别流水线无需后端服务即可完成文字识别。本文以 browser.en.md 为核心结合 paddleocr-js 仓库源码完整讲解 SDK 安装、模型选择、参数配置、预测调用、Worker 模式、结果可视化与宿主环境要求帮助你在 Web 应用中快速落地纯前端的 OCR 能力。一、PaddleOCR.js 是什么PaddleOCR 提供名为PaddleOCR.js的浏览器 OCR SDK用于在浏览器中运行 PP-OCR 流水线。你可以把文本检测与识别能力嵌入 Web 应用在客户端直接完成推理无需把图片上传到服务器。npm 包名paddleocr/paddleocr-js源码与演示工程位于仓库 paddleocr-js 目录packages/core/浏览器 SDK 源码发布为paddleocr/paddleocr-jsapps/demo/基于 Vite 的演示应用从源码结构看SDK 由若干职责清晰的模块组成参见 packages/core/src/index.ts 与 包结构说明runtime/推理运行时ONNX Runtime Web与 OpenCV.js 的初始化resources/模型与资源管理tar 模型包下载与解析models/检测/识别模型封装platform/浏览器/Worker 输入适配worker/Worker 传输层pipelines/OCR 流水线实现核心为pipelines/ocr/viz/可视化可选子模块其中 pipelines/ocr/core.ts 定义了OcrPipelineRunnerPaddleOCRCore负责初始化 OpenCV.js、ONNX Runtime、加载检测/识别模型并执行完整的「检测 → 裁剪 → 识别 → 过滤」流水线pipelines/ocr/index.ts 导出的PaddleOCR类是其浏览器入口。二、安装npm install paddleocr/paddleocr-js如果要在本地开发并运行官方 demo可以在 paddleocr-js 目录执行npm install npm run dev:demo其他常用命令还包括npm run build、npm run test、npm run typecheck、npm run check。三、快速开始import { PaddleOCR } from paddleocr/paddleocr-js; const ocr await PaddleOCR.create({ lang: ch, ocrVersion: PP-OCRv5, ortOptions: { backend: auto } }); const [result] await ocr.predict(fileOrBlob); console.log(result.items);需要特别注意的是predict解析出的结果是一个OcrResult数组每个输入图片对应一个元素。即使只传入单个Blob/File也会返回单元素数组——因此上面的示例使用了解构const [result]或者你也可以用results[0]取第一个结果。从 core.ts 的实现可以看到predict内部会把输入归一化为数组Array.isArray(input) ? input : [input]按流水线批大小切分后逐批执行最后为每张图生成一个OcrResult。四、构造选项PaddleOCR.create(options)支持两种构造风格直接参数direct parameters或pipelineConfig对象YAML 文本或解析后的对象。若同时提供两者直接参数优先。4.1 直接参数方式直接参数方式可以指定模型并设置批大小、ORT 选项及其他运行时参数。方式 A用langocrVersion选择内置模型await PaddleOCR.create({ lang: ch, ocrVersion: PP-OCRv5 });内置模型映射由 SDK 默认流水线配置决定见 default-config.ts。需要说明的是SDK 的默认配置以 PP-OCRv5 移动端模型为基准文本检测默认PP-OCRv5_mobile_det文本识别默认PP-OCRv5_mobile_rec并默认挂载文本行方向分类模型PP-LCNet_x1_0_textline_ori。若使用ocrVersion: PP-OCRv6lang会映射到内置的 PP-OCRv6_small 检测/识别模型对如需 PP-OCRv6_tiny则需要显式传入模型名await PaddleOCR.create({ textDetectionModelName: PP-OCRv6_tiny_det, textRecognitionModelName: PP-OCRv6_tiny_rec });方式 B直接用内置模型名await PaddleOCR.create({ textDetectionModelName: PP-OCRv5_mobile_det, textRecognitionModelName: PP-OCRv5_mobile_rec });方式 C自定义模型——为检测和识别分别提供模型名与资源 URLawait PaddleOCR.create({ textDetectionModelName: my_det_model, textDetectionModelAsset: { url: https://example.com/models/my_det_model.tar }, textRecognitionModelName: my_rec_model, textRecognitionModelAsset: { url: https://example.com/models/my_rec_model.tar } });批大小、ORT 选项与其他运行时设置await PaddleOCR.create({ lang: ch, ocrVersion: PP-OCRv5, textDetectionBatchSize: 2, textRecognitionBatchSize: 8, ortOptions: { backend: wasm, wasmPaths: /assets/ } });从 index.ts 的PaddleOCRCreateOptions类型可见SDK 对参数同时接受 camelCase 与 snake_case 两种写法如textDetectionModelName/text_detection_model_name、textDetectionModelAsset/textDetectionModelDir/text_detection_model_dir、textDetectionBatchSize/text_detection_batch_size/batch_size方便从 PaddleOCR/PaddleX 生态迁移配置。4.2 自定义模型归档格式与校验SDK 会通过 HTTP(S) 下载textDetectionModelAsset.url/textRecognitionModelAsset.url并把响应体解析为未压缩的 ustar tar 归档。必须满足以下要求要求说明归档格式响应体必须是未压缩的.tar。实现不会解压.tar.gz如果传入 gzip 压缩的 tar 包解析通常会失败并抛出错误必需文件tar 中必须包含inference.onnx与inference.yml允许位于子目录中按 basename 匹配model_nameinference.yml中必须定义model_name且与传给create的textDetectionModelName/textRecognitionModelName一致。该检查在初始化阶段加载完成后执行如果需要把 Paddle 模型转换为这里使用的 ONNX 模型文件请参见 Obtaining ONNX models。该流程产出的标准模型文件按上述规则打包为.tar后即可用于 PaddleOCR.js。如果归档或模型文件不满足上述规则初始化通常会抛出一个描述具体问题的Error例如下载非 2xx 状态、tar 中缺少inference.onnx/inference.yml、资源为空、model_name缺失或不匹配、模型配置不完整、ONNX 加载失败等。SDK没有静默降级——错误会直接抛出。所有选中的 OCR 模型都必须满足上述model_name规则。从源码看model_name校验实现在 core.ts初始化时通过validateLoadedModelName(TextDetection / TextRecognition, ...)对下载到的inference.yml文本与modelSelection中声明的模型名逐一比对。检测与识别模型随后并行构建 ONNX 推理会话createDetModel/createRecModel批大小分别取自textDetectionBatchSize与textRecognitionBatchSize。4.3 Pipeline config 方式import { PaddleOCR } from paddleocr/paddleocr-js; const pipelineConfig pipeline_name: OCR SubModules: TextDetection: model_name: PP-OCRv5_mobile_det batch_size: 2 TextRecognition: model_name: PP-OCRv5_mobile_rec batch_size: 6 ; const ocr await PaddleOCR.create({ pipelineConfig });pipelineConfig可以是 YAML 文本或已解析的对象。在浏览器中子模块的model_dir必须为null或资产对象例如{ url: ... }不能是本地文件系统路径字符串。解析逻辑在 config.ts字符串输入用js-yaml解析为对象model_dir为对象时经normalizeModelAsset归一化为浏览器侧资产描述pipeline_name必须是OCR未支持的子模块特性会进入warnings列表并反映在初始化摘要pipelineConfigWarnings中。如果你想从 PaddleOCR / PaddleX 导出的流水线配置起步请参考 PaddleOCR and PaddleX 中的「Exporting Pipeline Configuration Files」一节导出的 YAML 可作为pipelineConfig的基础其中所有的model_dir条目需要改写成浏览器侧资产对象。如果同时提供了直接参数与pipelineConfig直接参数优先。4.4 默认流水线与运行时默认值即便不传任何参数SDK 也内置了一份完整的默认流水线配置见 default-config.ts其中包含text_type: generaluse_doc_preprocessor: Falseuse_textline_orientation: False子模块TextDetectionPP-OCRv5_mobile_detlimit_side_len: 64、limit_type: min、max_side_limit: 4000、thresh: 0.3、box_thresh: 0.6、unclip_ratio: 1.5子模块TextLineOrientationPP-LCNet_x1_0_textline_oribatch_size: 6子模块TextRecognitionPP-OCRv5_mobile_recbatch_size: 6score_thresh: 0.0当text_type为general时SDK 还会补充一组通用运行时默认值见 config.tstext_det_limit_side_len: 960、limit_type: max、max_side_limit: 4000、thresh: 0.3、box_thresh: 0.6、unclip_ratio: 2.0、text_rec_score_thresh: 0。这些默认值在predict时作为兜底优先级低于调用方显式传入的参数。五、预测Prediction5.1 参数ocr.predict(image | images[], params?)同时接受 camelCase 与 PaddleOCR 风格的 snake_case 参数textDetLimitSideLen或text_det_limit_side_lentextDetLimitType或text_det_limit_typetextDetMaxSideLimit或text_det_max_side_limittextDetThresh或text_det_threshtextDetBoxThresh或text_det_box_threshtextDetUnclipRatio或text_det_unclip_ratiotextRecScoreThresh或text_rec_score_thresh支持的image输入包括Blob、ImageBitmap、ImageData、HTMLCanvasElement、HTMLImageElement以及cv.Mat。传入数组可在一次调用中处理多张图片。Worker 模式下cv.Mat不可转移not transferable因此不支持作为输入。从源码看参数归一化实现在 runtime-params.ts 的getOcrRuntimeParams每个参数按「显式参数 → 运行时默认值 → 模型配置」的优先级取第一个有效值firstDefined。例如text_det_limit_side_len的最终值会依次尝试params、defaults与config.det.resizeLongtext_det_box_thresh会回落到模型配置中的postprocess.boxThresh。这意味着不传任何参数时检测阈值等行为由模型包内inference.yml中的配置决定。5.2 返回值predict返回PromiseOcrResult[]每个OcrResult包含image{ width, height }对应输入图片的尺寸items识别出的文本行每行包含poly、text、scoremetricsdetMs、recMs、totalMs、detectedBoxes、recognizedCount——其中框数量与行数量是逐图统计的而detMs、recMs、totalMs覆盖整个predict()调用因此传入多张图时每个元素上的这三个耗时字段是相同的runtime请求的后端与 provider 元数据对照 core.ts 的类型定义OcrResultRuntime具体包含requestedBackend、detProvider、recProvider、webgpuAvailable四个字段。流水线的执行顺序是先对整张图做检测detModel.predict再用cropByPoly按检测框裁剪文本区域逐图送入识别模型recModel.predict最后用text_rec_score_thresh过滤掉低置信度的识别结果见 core.ts。六、Worker 模式可以在专用 Worker 中运行 OCR 流水线同时保持相同的高层 APIimport { PaddleOCR } from paddleocr/paddleocr-js; const ocr await PaddleOCR.create({ lang: ch, ocrVersion: PP-OCRv5, worker: true, ortOptions: { backend: wasm, wasmPaths: https://cdn.jsdelivr.net/npm/onnxruntime-web/dist/, numThreads: 2, simd: true } });要点总结Worker 模式使用包自带的 worker 入口而不是 ONNX Runtime Web 的env.wasm.proxy当worker: true时包会强制关闭 ORT 的 wasm proxy以避免嵌套 Worker浏览器输入在主线程归一化后再转移到 Worker 中执行推理cv.Mat仅在主线程流水线路径下受支持从源码看PaddleOCR.create会先调用resolveWorkerOptions(options.worker)判定是否启用 Worker 模式见 index.ts启用时创建WorkerBackedPaddleOCRworker-backed.ts同时Worker 模式不支持自定义fetch实现会直接抛错。主线程侧通过 worker/client.ts 与 Worker 通信输入在主线程经sourceToImageBitmap归一化为ImageBitmap后转移transfer给 Worker参见 platform/browser.ts 与WorkerPayload定义。七、结果可视化可选的paddleocr/paddleocr-js/viz子路径可以把 OCR 结果渲染成图片import { OcrVisualizer } from paddleocr/paddleocr-js/viz; const viz new OcrVisualizer({ font: { family: Noto Sans SC, source: /fonts/NotoSansSC-Regular.ttf } }); const blob await viz.toBlob(imageBitmap, result); const url URL.createObjectURL(blob); const a document.createElement(a); a.href url; a.download ocr_result.png; a.click(); URL.revokeObjectURL(url); viz.dispose();此外还导出了renderOcrToBlob与deterministicColorimport { renderOcrToBlob } from paddleocr/paddleocr-js/viz; const blob await renderOcrToBlob(imageBitmap, result, { font: { family: Noto Sans SC, source: /fonts/NotoSansSC-Regular.ttf } });可视化模块渲染的是左右对比图左侧为叠加检测框的原始图片右侧为识别出的文本参见 packages/core/src/viz 目录下的draw-boxes.ts、draw-text.ts、side-by-side.ts、renderer.ts。CJK 文本可通过自定义字体加载。可视化需要单个OcrResult单图时取predict结果数组的第一个元素例如const [result] await ocr.predict(image)。deterministicColor(index)把数字索引映射为稳定的 RGB 颜色是内置渲染器默认的颜色函数构建自定义可视化时可直接调用以保证颜色一致。八、API 摘要PaddleOCR.create(options)ocr.initialize()/ocr.getInitializationSummary()ocr.predict(image | images[], params?)→PromiseOcrResult[]ocr.dispose()parseOcrPipelineConfigText(text)/normalizeOcrPipelineConfig(config)OcrVisualizer、renderOcrToBlob、deterministicColor来自paddleocr/paddleocr-js/viz其中getInitializationSummary()返回的InitializationSummary见 core.ts包含backend、webgpuAvailable、detProvider、recProvider、assets模型下载摘要、elapsedMs与pipelineConfigWarnings可用于诊断初始化耗时与模型加载情况。PaddleOCR.create默认会自动调用initialize()除非显式传入initialize: false见 index.ts。九、宿主应用的责任SDK 内部管理 OpenCV.js 与 ONNX Runtime 的加载但宿主应用仍需处理以下运行时环境问题COOP/COEP以及相关响应头启用线程化 WASM 或 WebGPU 时必须正确设置ORT 环境选项例如wasmPaths、线程数numThreads、SIMD 标志打包器/运行时当worker: true时需要能够生成并加载module workers此外SDK 要求页面运行在 HTTP(S) 源上ensureServedFromHttp会在file:协议下直接抛错PaddleOCR.js requires an HTTP(S) origin so model assets can be fetched.见 platform/browser.ts因此直接用file://打开 HTML 无法使用该 SDK。9.1 后端选择与 WebGPU 探测ortOptions.backend支持webgpu、wasm与auto见 runtime/ort.ts 的OrtOptions定义。初始化时SDK 会先探测navigator.gpu与 WebGPU adapter 的可用性detectWebGpuAvailability再按后端生成执行提供方候选列表getProviderCandidatesbackend: webgpu要求 WebGPU 可用否则直接抛错候选为[[webgpu]]backend: wasm候选为[[wasm]]backend: autoWebGPU 可用则优先尝试[[webgpu], [wasm]]否则仅[[wasm]]创建 ONNX 推理会话时createSessionSDK 会按候选顺序逐个尝试执行提供方并统一使用graphOptimizationLevel: all做图优化runtime/ort.ts。9.2 初始化与推理调用链一次完整的调用流程可概括为PaddleOCR.create(options)→ 归一化选项resolvePaddleOCROptions选择主线程或 Worker 路径initialize()→ 加载 OpenCV.jsinitOpenCvRuntime→ 加载并配置 ONNX RuntimeinitOrtRuntime→ 并行下载检测/识别模型 tarloadModelAsset→ 校验model_name→ 构建检测/识别推理会话predict(input, params)→ 归一化输入与运行时参数 → 检测 → 逐图裁剪 → 识别 → 分数过滤 → 汇总OcrResult[]对应的测试覆盖可以参考 packages/core/test 目录下的ocr-api.test.ts、ocr-core.test.ts、ocr-config-branches.test.ts、model-asset.test.ts、runtime-ort.test.ts、worker-backed.test.ts等用例它们验证了 API 形态、配置分支、tar 解析与 Worker 行为可作为理解 SDK 契约的补充材料。十、常见问题与注意事项结果一定是数组predict永远返回OcrResult[]单图也要用[result]解构或results[0]。模型包必须为未压缩 tarSDK 不做 gzip 解压.tar.gz会解析失败。model_name必须匹配inference.yml中的model_name与create传入的模型名不一致会导致初始化报错且没有任何静默回退。浏览器环境约束需要 HTTP(S) 源file://直接打开不可用。Worker 模式限制不支持cv.Mat输入也不支持自定义fetch。并发批处理predict会按pipelineBatchSize把多张图片切分为多个批次执行检测批大小与识别批大小分别通过textDetectionBatchSize/textRecognitionBatchSize控制。十一、下一步从 Paddle 模型导出 ONNX阅读 Obtaining ONNX models再将产物按本文 4.2 节规则打包为 tar。复用 PaddleX 流水线配置阅读 PaddleOCR and PaddleX 中的配置导出说明将model_dir改写为浏览器资产对象后直接作为pipelineConfig使用。查看 paddleocr-js 的架构与开发文档docs/architecture.md、docs/development.md、docs/monorepo.md了解 monorepo 约定与二次开发方式。【免费下载链接】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），仅供参考