概览：PaddleOCR 是什么，该选哪条产线

PaddleOCR 是百度飞桨团队的开源 OCR 与文档解析工具包，采用 Apache License 2.0。本页是当前 3.7 API 的实用指南。页面中的所有代码示例都是针对 3.x API 编写的，安装、API 和命令行方面的事实已于下方所示日期对照官方文档和已发布的软件包核查。

请根据你需要的输出来选择产线：

独立网站。paddleocr.dev 并非由百度或 PaddleOCR 维护者运营。如需权威参考，请使用 GitHub 仓库和 PaddleOCR 官方文档。最近核查：2026 年 10 月，对应 PaddleOCR 3.7.0。参见我们的编辑政策（英文）。

安装

PaddleOCR 需要一个推理引擎（PaddlePaddle）加上 paddleocr 包。请先安装引擎，再安装 PaddleOCR，并使用虚拟环境。

环境要求

• 实际使用 Python 3.9–3.13。paddleocr 包声明的是 >=3.8，但 PaddlePaddle 3.x 的安装包面向 3.9–3.13，文档解析需要 3.9+。
• 操作系统：Linux、Windows 或 macOS（Apple Silicon 使用 CPU 运行）。
• NVIDIA GPU（可选）：驱动需支持你所安装的 CUDA 版本（下文为 CUDA 12.6；同时也发布了 CUDA 11.8 版本）。

CPU

python -m pip install paddlepaddle==3.2.1 -i https://www.paddlepaddle.org.cn/packages/stable/cpu/
python -m pip install "paddleocr[all]"

NVIDIA GPU（CUDA 12.6）

python -m pip install paddlepaddle-gpu==3.2.1 -i https://www.paddlepaddle.org.cn/packages/stable/cu126/
python -m pip install "paddleocr[all]"

不要直接从 PyPI 执行 pip install paddlepaddle-gpu。PyPI 上最新的 GPU 版本是 2.6.2，PaddleOCR 3.x 并不支持。请务必使用上面的 -i 索引。可从 PaddlePaddle 官方安装选择器中选择对应的 CUDA 索引（例如 cu118）。

可选依赖

验证

import paddle
paddle.utils.run_check()

from paddleocr import PaddleOCR
print("PaddleOCR import OK")

首次真正运行时会下载模型权重（默认来自 Hugging Face），因此需要联网一次。若要使用已下载好的模型，请传入 text_detection_model_dir 和 text_recognition_model_dir。

快速开始：五行代码完成第一次 OCR

PaddleOCR 3.x 返回的是结果对象。调用 predict()，然后读取 rec_texts、rec_scores 和 rec_boxes 等字段。

from paddleocr import PaddleOCR

ocr = PaddleOCR(lang="en")            # "en" 的默认模型是 PP-OCRv6（medium）
result = ocr.predict("invoice.jpg")  # 路径、URL、numpy 数组或 PDF

for res in result:
    for text, score, box in zip(res["rec_texts"], res["rec_scores"], res["rec_boxes"]):
        if score >= 0.8:
            print(f"{score:.2f}  {box.tolist()}  {text}")

    res.save_to_img("output")        # 带标注的图片
    res.save_to_json("output")       # 结构化结果

命令行

paddleocr ocr -i invoice.jpg --lang en --save_path ./output

结果字段

想直观地尝试各种选项？请使用首页的代码生成器，它会为你的环境输出可运行的代码片段和命令行。

从 PaddleOCR 2.x 迁移

PaddleOCR 3.x 不向后兼容。大多数旧教程（以及旧的 AI 生成答案）展示的仍是 2.x API。以下是会导致代码报错的改动：

# 2.x
# ocr = PaddleOCR(use_angle_cls=True, lang="en", use_gpu=True)
# result = ocr.ocr("img.jpg", cls=True)

# 3.x
from paddleocr import PaddleOCR
ocr = PaddleOCR(lang="en", device="gpu", use_textline_orientation=True)
result = ocr.predict("img.jpg")
for res in result:
    print(res["rec_texts"])

PP-OCRv6：文本检测与识别

PP-OCRv6 随 PaddleOCR 3.7.0（2026 年 6 月 11 日）发布，是 PaddleOCR 类的默认模型。下列数据来自百度自己的报告，我们没有独立做过基准测试。

• 语言：一个识别模型覆盖 50 种语言：中文、英文、日文和 46 种拉丁字母语言。其他文字（韩语、阿拉伯语、俄语、泰语、希腊语等）使用 PP-OCRv5 多语种模型；lang="korean" 会加载 korean_PP-OCRv5_mobile_rec。
• 报告的提升：medium 档位的检测精度比 PP-OCRv5_server 提升 4.6%，识别精度提升 5.1%；百度报告借助 OpenVINO 端到端 CPU 提速 5.2 倍（tiny 档位在 Apple M4 上为 6.1 倍）。

选择档位

from paddleocr import PaddleOCR

# 默认（medium）
ocr = PaddleOCR(lang="en")

# Small / tiny：同时传入两个模型名称
ocr_small = PaddleOCR(
    text_detection_model_name="PP-OCRv6_small_det",
    text_recognition_model_name="PP-OCRv6_small_rec",
)

# 继续使用上一代
ocr_v5 = PaddleOCR(lang="en", ocr_version="PP-OCRv5")

PP-OCRv5 与 PP-OCRv6

ocr_version 接受 "PP-OCRv6"、"PP-OCRv5"、"PP-OCRv4" 和 "PP-OCRv3"，但并非每种语言在每个版本中都有。如果你请求的版本缺少某个 lang，请选择其他版本或显式传入模型名称。如果需要升级前后输出可复现，请固定 ocr_version。

主要参数

langstr例如 "en"

识别语言。参见语言代码。

ocr_versionstrPP-OCRv6

模型代际：PP-OCRv6 / v5 / v4 / v3。

devicestrauto

"cpu"、"gpu"、"gpu:0"、"npu:0"、"xpu:0"、"mlu:0"。

use_doc_orientation_classifyboolTrue

矫正整页旋转（0/90/180/270°）。输入清晰端正时可关闭以节省时间。

use_doc_unwarpingboolTrue

展平弯曲或拍摄的页面。扫描件和截图请关闭。

use_textline_orientationboolTrue

矫正倒置的单行文本。

text_det_threshfloat0.3

检测概率图的像素阈值。调低能发现更多淡色文字，但噪声也会增多。

text_det_box_threshfloat0.6

区域被保留为文本框所需的平均得分。

text_det_unclip_ratiofloat2.0

检测区域的扩张幅度。值越大，文本框越宽松。

text_rec_score_threshfloat0.0

丢弃置信度低于该值的识别结果。

return_word_boxboolFalse

同时返回单词级边框。

text_recognition_batch_sizeint1

每批识别的文本行数。在 GPU 上可调大。

默认值来自官方 OCR 产线参考文档；由于默认值和档位名称会不断演进，请对照所安装版本的产线页面确认。

PP-StructureV3：文档转 Markdown 和 JSON

PP-StructureV3 整合了版面检测、OCR、表格识别、公式识别、印章识别和阅读顺序还原。当你希望把 PDF 或页面图片转成 Markdown 或 JSON，而不是一份扁平的文本行列表时，它是正确的选择。它可以在 CPU 上运行，但在 GPU 上快得多。

from paddleocr import PPStructureV3

pipeline = PPStructureV3(lang="en")   # 有 GPU 时加上 device="gpu"
output = pipeline.predict("report.pdf")

for res in output:
    res.print()
    res.save_to_json(save_path="output")
    res.save_to_markdown(save_path="output")

paddleocr pp_structurev3 -i report.pdf --device cpu --save_path ./output

请先安装对应的可选依赖：python -m pip install "paddleocr[doc-parser]"。构造函数和命令行上的常用开关有：use_doc_orientation_classify、use_doc_unwarping、use_textline_orientation，以及针对表格、公式、印章和图表的各模块开关。关闭不需要的模块可以提速。

实用建议

• 如果自己把 PDF 转成图片，建议使用约 150–200 DPI；过高的 DPI 会拖慢整体速度，却不会明显提高精度。
• 多页 PDF 每页返回一个结果。请自行拼接 Markdown，或在你的版本提供时使用产线的页面合并辅助方法。
• 务必抽查表格。合并单元格和无边框表格是所有表格识别模型都容易出错的地方。

PaddleOCR-VL：视觉语言文档解析

PaddleOCR-VL 是一个小巧的视觉语言模型，用于文档解析（文本、表格、公式、图表），支持多语言。PaddleOCR-VL-1.6 随 PaddleOCR 3.6.0（2026 年 5 月 28 日）发布，据百度报告在 OmniDocBench v1.6 上达到 96.33%（官方自报）。它是这里精度最高的选项，但需要性能足够的 GPU 或专用推理服务；CPU 也能运行，不过官方文档不建议在生产环境使用。

python -m pip install paddlepaddle-gpu==3.2.1 -i https://www.paddlepaddle.org.cn/packages/stable/cu126/
python -m pip install -U "paddleocr[doc-parser]"

from paddleocr import PaddleOCRVL

pipeline = PaddleOCRVL()                     # 或用 PaddleOCRVL(device="cpu") 做缓慢的试运行
output = pipeline.predict("page.png")

for res in output:
    res.print()
    res.save_to_json(save_path="output")
    res.save_to_markdown(save_path="output")

paddleocr doc_parser -i page.png --save_path ./output

多页文档

from paddleocr import PaddleOCRVL

pipeline = PaddleOCRVL()
pages = list(pipeline.predict("contract.pdf"))
merged = pipeline.restructure_pages(pages, merge_tables=True, relevel_titles=True, concatenate_pages=True)

for res in merged:
    res.save_to_markdown(save_path="output")

推理引擎

PaddleOCRVL(engine="transformers") 通过 Hugging Face Transformers 而不是 Paddle 引擎运行模型。为了提高吞吐量，文档介绍了把 VLM 放在专用推理服务（如 vLLM 或 SGLang）之后，并通过 vl_rec_backend 让 PaddleOCR-VL 指向它；具体设置请遵循所用版本的 PaddleOCR-VL 官方页面。

HPD-Parsing：高吞吐解析

HPD-Parsing 由 PaddleOCR 团队于 2026 年 7 月 22 日发布，是面向 GPU 大批量任务的高吞吐文档解析模型。它比其他产线更新、文档也更少，因此我们特意不在这里重复吞吐量数字。在围绕它规划容量之前，请阅读发布说明和官方文档，了解模型下载、支持的硬件和基准测试方法，并在自己的文档上做基准测试。

性能调优

先测量。以下是通常最有效的优化手段，大致按收益从高到低排列：

1. 关闭不需要的模块。对于清晰的扫描件：use_doc_orientation_classify=False, use_doc_unwarping=False, use_textline_orientation=False。
2. 选择更小的档位（small 或 tiny），前提是在你的文档上精度已经足够。
3. 复用对象。只创建一次 PaddleOCR(...)；单次调用的耗时主要在模型加载。
4. 在 GPU 上调大批大小（text_recognition_batch_size）。
5. 缩小大尺寸输入。降低 text_det_limit_side_len，或在 OCR 前先缩小超大照片。
6. CPU：保持 enable_mkldnn 开启并调整 cpu_threads；在 Intel CPU 上可考虑 OpenVINO 引擎。
7. 高性能推理：enable_hpi=True 会自动选择优化后的后端。目前支持 Linux x86-64 上的 Python 3.8–3.12，并需要额外插件；详见官方指南。

from paddleocr import PaddleOCR

ocr = PaddleOCR(
    lang="en",
    device="gpu",
    use_doc_orientation_classify=False,
    use_doc_unwarping=False,
    use_textline_orientation=False,
    text_recognition_batch_size=16,
)

GPU 和其他加速器

设置 device：NVIDIA 用 "gpu"/"gpu:0"，受支持的国产加速器用 "npu:0"、"xpu:0"、"mlu:0" 等（这些需要对应的 PaddlePaddle 构建）。macOS 上请使用 CPU。如果 GPU 在被使用，paddle.device.get_device() 应该输出 gpu:0；如果输出 cpu，说明你安装的是 CPU 版安装包。

批量处理

from pathlib import Path
from paddleocr import PaddleOCR

ocr = PaddleOCR(lang="en", use_doc_orientation_classify=False, use_doc_unwarping=False)
files = sorted(str(p) for p in Path("scans").glob("*.jpg"))

# predict() 接受列表，并为每个输入返回一个结果
for res in ocr.predict(files):
    name = Path(res["input_path"]).stem
    res.save_to_json(f"output/{name}")

自定义模型

可以按目录使用你自己训练或导出的模型：PaddleOCR(text_detection_model_dir="./my_det", text_recognition_model_dir="./my_rec")，也可以同时传入 text_detection_model_name / text_recognition_model_name。训练和微调见官方文档；对于大多数印刷体文本，调整阈值和预处理比训练模型成本更低，值得先做。

RAG 与大模型流水线

对于检索增强生成（RAG），先把文档解析为 Markdown，按标题切分，再对分块做向量化。PP-StructureV3 和 PaddleOCR-VL 已经能输出带标题层级的 Markdown，这让分块比切分原始 OCR 文本行干净得多。

from pathlib import Path
from paddleocr import PPStructureV3

pipeline = PPStructureV3(lang="en")
md_parts = []
for res in pipeline.predict("handbook.pdf"):
    res.save_to_markdown(save_path="md")

text = "\n\n".join(p.read_text(encoding="utf-8") for p in sorted(Path("md").glob("*.md")))

# 按二级标题切分；可换成你喜欢的切分器
chunks = [c.strip() for c in text.split("\n## ") if c.strip()]
print(len(chunks), "chunks")

• 在分块元数据中保留页码和源文件，以便回答时可以引用来源。
• 对于质量较差的扫描件，保存 OCR 置信度，并标记低置信度的分块。
• 不要想当然地认为提取出的数字是正确的；对于发票和财务数据，请做校验（合计、日期、校验和）。

Dify、RAGFlow 及其他平台

大多数无代码平台通过 HTTP 调用 OCR。把 PaddleOCR 作为服务运行（参见 Docker 和下文的服务化 API），然后从平台的 HTTP/工具节点调用它；如果平台自带 PaddleOCR 连接器，也可以直接使用。请以平台当前的文档为准，因为连接器的名称和选项经常变化。

通过 HTTP 提供服务

paddlex --install serving
paddlex --serve --pipeline OCR          # 默认监听 8080 端口

import base64, requests

with open("demo.jpg", "rb") as f:
    payload = {"file": base64.b64encode(f.read()).decode("ascii"), "fileType": 1}  # 1 = 图片，0 = PDF

r = requests.post("http://localhost:8080/ocr", json=payload, timeout=120)
r.raise_for_status()
for res in r.json()["result"]["ocrResults"]:
    print(res["prunedResult"])

详细信息、鉴权和扩展选项见官方服务化部署指南。在没有自己的鉴权层之前，请不要把该端口暴露到互联网。

面向 AI 智能体的 MCP 服务器

官方的 paddleocr-mcp 包（撰写本文时为 0.8.5，需要 Python 3.10+）把 OCR、PP-StructureV3 或 PaddleOCR-VL 作为 Model Context Protocol 工具提供，这样 Claude Desktop 等宿主就能读取图片和 PDF。

python -m pip install "paddleocr-mcp[local-cpu]"      # 本地 CPU 推理
# 或：python -m pip install paddleocr-mcp               # 仅使用托管 / 自托管后端

用 --model（或 PADDLEOCR_MCP_MODEL）选择模型：PP-OCRv6（默认）、PP-OCRv5、PP-OCRv5-latin、PP-StructureV3、PaddleOCR-VL、PaddleOCR-VL-1.5、PaddleOCR-VL-1.6。用 --ppocr_source 选择推理运行的位置：local（默认）、aistudio、qianfan 或 self_hosted。使用 --http 可改用 Streamable HTTP 而不是 stdio（默认绑定 127.0.0.1:8000）。

{
  "mcpServers": {
    "paddleocr": {
      "command": "paddleocr_mcp",
      "args": ["--model", "PP-OCRv6", "--ppocr_source", "local"]
    }
  }
}

隐私：使用 local 时，文件保留在你的机器上。使用 aistudio 或 qianfan 时，你的文档会被上传到这些服务。请谨慎选择。

JavaScript 与浏览器 OCR

@paddleocr/paddleocr-js（撰写本文时为 0.4.2，Apache-2.0）借助 ONNX Runtime Web 和 OpenCV.js 在浏览器中运行 PaddleOCR 模型。图片不会离开用户的设备。这是一个很新的包（0.x 版本），请固定版本号，并预期 API 会有变化。

npm install @paddleocr/paddleocr-js

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);   // predict() 返回数组，每张图片对应一项
console.log(result.items);

设置 ocrVersion: "PP-OCRv6" 时，SDK 使用 PP-OCRv6 small 这一对模型；若要用 tiny，请传入 textDetectionModelName: "PP-OCRv6_tiny_det" 和 textRecognitionModelName: "PP-OCRv6_tiny_rec"。支持自行托管模型压缩包和 WASM 文件；详见该包的 README。模型下载体积和首次加载时间在移动网络上很重要，所以请显示加载状态。

Docker

一个最小化的 CPU 容器。这只是示例配方，并非官方镜像；请在你自己的基础镜像和硬件上测试。

FROM python:3.12-slim

# OpenCV 运行时库（如果出现 "libGL.so.1" 或 "libgthread" 错误则需要）
RUN apt-get update && apt-get install -y --no-install-recommends libgl1 libglib2.0-0 \
    && rm -rf /var/lib/apt/lists/*

RUN python -m pip install --no-cache-dir paddlepaddle==3.2.1 -i https://www.paddlepaddle.org.cn/packages/stable/cpu/ \
    && python -m pip install --no-cache-dir "paddleocr[all]"

WORKDIR /app
COPY app.py .
CMD ["python", "app.py"]

• 缓存模型。为 ~/.paddlex（模型缓存位置）挂载一个卷，这样容器每次启动时就不必重新下载权重。
• GPU：使用 CUDA 基础镜像，从 CUDA 索引安装 paddlepaddle-gpu 安装包，并用 --gpus all 运行（宿主机需要 NVIDIA Container Toolkit）。
• 离线环境：预先下载模型，并传入 *_model_dir 参数。

Python API 参考

所有产线通用的方法

predict(input, **kwargs)generator/list

运行推理。input 可以是路径、URL、numpy 数组、目录或它们的列表；支持 PDF。调用时传入的关键字参数会覆盖该次调用的构造函数默认值。

predict_iter(input, **kwargs)generator

适用于大输入的惰性版本。

结果对象

res["rec_texts"] …类字典

字段像字典一样读取（参见结果字段）。

res.print()方法

美化打印结果。

res.save_to_json(path)方法

写出结构化 JSON。

res.save_to_img(path)方法

写出带标注的图片（OCR 产线）。

res.save_to_markdown(path)方法

写出 Markdown（文档产线）。

权威的参数列表见官方各产线页面：OCR、PP-StructureV3 和 PaddleOCR-VL。

命令行参考

paddleocr ocr -i ./scan.png --lang en --device gpu:0 --save_path ./output
paddleocr ocr -i ./scan.png --ocr_version PP-OCRv5
paddleocr ocr -i ./scan.png --use_doc_orientation_classify False --use_doc_unwarping False --use_textline_orientation False
paddleocr pp_structurev3 -i report.pdf --device cpu --save_path ./output
paddleocr doc_parser -i page.png --save_path ./output

命令行参数与 Python 构造函数的参数一一对应：-i/--input、--lang、--ocr_version、--device、--save_path，以及各种 --use_* 开关。运行 paddleocr ocr --help 可查看你所用版本支持的列表。2.x 的旧参数 --image_dir、--use_gpu 和 --use_angle_cls 已不再可用。

语言代码

通过 lang 传入语言代码。常用取值：

完整且与版本对应的映射表，见PaddleOCR 官方 OCR 产线页面附录中的表格。请以它为准，因为各版本之间的语言覆盖会有变化。

故障排查

ValueError: Unknown argument: use_gpu

你把 2.x 的教程用在了 3.x 上。请使用 PaddleOCR(device="gpu")。参见迁移。

pip 找不到匹配的 paddlepaddle-gpu

PyPI 上只有旧的 2.6.2 GPU 版本。请从 PaddlePaddle 索引安装，使用 -i https://www.paddlepaddle.org.cn/packages/stable/cu126/（或你需要的 CUDA 版本）。

明明有 GPU，却在 CPU 上运行

你可能安装了 CPU 版安装包，或者传入了 device="cpu"。请检查 python -c "import paddle; print(paddle.device.get_device())" 和 nvidia-smi。

首次运行非常慢

模型正在下载和初始化。之后的运行会复用缓存。在服务中请复用同一个 PaddleOCR 对象。

结果为空或乱码

• lang 与文字类型不匹配：韩语、阿拉伯语和俄语不在 50 种语言的 PP-OCRv6 模型中。
• 文字太小：放大图片，或调大 text_det_limit_side_len。
• 文字太淡：适当调低 text_det_thresh 和 text_det_box_thresh。
• 拍摄的页面：启用 use_doc_unwarping；扫描件和截图：关闭它。

ImportError: libGL.so.1（Linux / Docker）

安装 OpenCV 运行时库：apt-get install -y libgl1 libglib2.0-0。

GPU 显存不足

调低批大小，一次处理一页，使用更小的档位，或把 PaddleOCR-VL 放在专用推理服务之后运行。

仍然无法解决？请搜索 官方问题追踪，并附上你的 PaddleOCR 和 PaddlePaddle 版本。

版本历史

日期为 paddleocr 包在 PyPI 上的上传日期。完整说明见 GitHub 发布页面。

HPD-Parsing 于 2026 年 7 月 22 日公布（是模型发布公告，而非 PyPI 版本发布）。