PP-OCRv5_API
更新时间:2025-11-25
PP-OCRv5 服务化部署调用示例及 API 介绍:
PaddleOCR 开源项目 GitHub 地址,此处和开源的模型完全一致。
1. PP-OCRv5 介绍
OCR(光学字符识别,Optical Character Recognition)是一项将图片中的文字内容转换为可编辑文本的技术,广泛应用于文档数字化、信息提取、数据处理等场景。OCR 能够识别印刷体、手写体等多种类型的文本,帮助用户高效获取图像中的关键信息。
PP-OCRv5 是 PP-OCR 系列最新一代的文字识别解决方案,专为多场景、多文字类型的识别任务设计。相比前代版本,PP-OCRv5 在文字类型支持和应用场景适应性方面实现了全面升级。该方案不仅能够返回文本行的坐标信息,还可输出对应文本内容及其置信度,有效提升了文字检测与识别的准确性和实用性,该方案具有如下特点:
- 支持五大主流文字类型:简体中文、中文拼音、繁体中文、英文、日文。
- 具备强大的多场景适应能力:包括中英复杂手写体、竖排文本、生僻字等多种挑战性场景。
- 在内部多场景复杂评估集上,PP-OCRv5 相比上一代 PP-OCRv4 端到端识别精度提升了 13 个百分点。
PP-OCRv5 产线整体流程如下图所示:
2. 接口说明
适用于通过 API 创建解析任务的场景,用户须先申请 Token。 注意:
- 每个用户每天针对每个模型可解析的页面总数上限为 3000 页,后续的解析请求将返回 429 错误。
- 对于单个文件页数和体积大小不做限制,但是大体积文件资源紧张时可能会服务超时,返回 503 错误。
3. 服务调用示例(python)
# Please make sure the requests library is installed
# pip install requests
import os
import base64
import requests
# API_URL 及 TOKEN 请访问 https://aistudio.baidu.com/paddleocr/task,在 API 调用示例中获取。
API_URL = "<your url>"
TOKEN = "<access token>"
file_path = "<local file path>"
input_filename = os.path.splitext(os.path.basename(file_path))[0]
with open(file_path, "rb") as file:
file_bytes = file.read()
file_data = base64.b64encode(file_bytes).decode("ascii")
headers = {
"Authorization": f"token {TOKEN}",
"Content-Type": "application/json"
}
required_payload = {
"file": file_data,
"fileType": <file type>, # For PDF documents, set `fileType` to 0; for images, set `fileType` to 1
}
optional_payload = {
"useDocOrientationClassify": False,
"useDocUnwarping": False,
"useTextlineOrientation": False,
}
payload = {**required_payload, **optional_payload}
response = requests.post(API_URL, json=payload, headers=headers)
assert response.status_code == 200
result = response.json()["result"]
os.makedirs("output", exist_ok=True)
for i, res in enumerate(result["ocrResults"]):
print(res["prunedResult"])
image_url = res["ocrImage"]
img_response = requests.get(image_url)
if img_response.status_code == 200:
# Save image to local
filename = f"output/{input_filename}_{i}.jpg"
with open(filename, "wb") as f:
f.write(img_response.content)
print(f"Image saved to: {filename}")
else:
print(f"Failed to download image, status code: {img_response.status_code}")对于服务提供的主要操作:
- HTTP请求方法为POST。
- 请求体和响应体均为JSON数据(JSON对象)。
- 当请求处理成功时,响应状态码为
200,响应体的属性如下:
| 名称 | 类型 | 含义 |
|---|---|---|
logId |
string |
请求的UUID。 |
errorCode |
integer |
错误码。固定为0。 |
errorMsg |
string |
错误说明。固定为"Success"。 |
result |
object |
操作结果。 |
- 当请求处理未成功时,响应体的属性如下:
| 名称 | 类型 | 含义 |
|---|---|---|
logId |
string |
请求的UUID。 |
errorCode |
integer |
错误码。与响应状态码相同。 |
errorMsg |
string |
错误说明。 |
服务提供的主要操作如下:
infer
获取图像OCR结果。
POST /ocr
4. 请求参数说明
| 名称 | 参数 | 类型 | 含义 | 是否必填 |
|---|---|---|---|---|
输入文件 |
file |
string |
服务器可访问的图像文件或PDF文件的URL,或上述类型文件内容的Base64编码结果。默认对于超过10页的PDF文件,只有前10页的内容会被处理。 要解除页数限制,请在产线配置文件中添加以下配置:
|
是 |
文件类型 |
fileType |
integer | null |
文件类型。0表示PDF文件,1表示图像文件。若请求体无此属性,则将根据URL推断文件类型。 |
否 |
图片方向矫正 |
useDocOrientationClassify |
boolean | null |
是否在推理时使用文档方向分类模块,开启后,可以自动识别并矫正 0°、90°、180°、270°的图片。 | 否 |
图片扭曲矫正 |
useDocUnwarping |
boolean | null |
是否在推理时使用文本图像矫正模块,开启后,可以自动矫正扭曲图片,例如褶皱、倾斜等情况。 | 否 |
文本行方向矫正 |
useTextlineOrientation |
boolean | null |
是否在推理时使用文本行方向分类模块,开启后,可以自动识别和矫正 0° 和 180° 的文本行。 | 否 |
图像边长限制 |
textDetLimitSideLen |
integer | null |
文本检测的图像边长限制。 大于0 的任意整数。如果不设置,将使用产线初始化的该参数值,默认初始化为 64。 |
否 |
图像边长限制类型 |
textDetLimitType |
string | null |
文本检测的边长度限制类型。支持 min 和 max,min 表示保证图像最短边不小于 textDetLimitSideLen,max 表示保证图像最长边不大于 textDetLimitSideLen。如果不设置,将使用产线初始化的该参数值,默认初始化为 min。 |
否 |
文本检测像素阈值 |
textDetThresh |
number | null |
文本检测像素阈值,输出的概率图中,得分大于该阈值的像素点才会被认为是文字像素点。 大于 0 的任意浮点数。如果不设置,将使用产线初始化的该参数值(默认为 0.3)。 |
否 |
文本检测框阈值 |
textDetBoxThresh |
number | null |
文本检测框阈值,检测结果边框内,所有像素点的平均得分大于该阈值时,该结果会被认为是文字区域。 大于 0 的任意浮点数。如果不设置,将使用产线初始化的该参数值(默认为 0.6)。 |
否 |
扩张系数 |
textDetUnclipRatio |
number | null |
文本检测扩张系数,使用该方法对文字区域进行扩张,该值越大,扩张的面积越大。大于 0 的任意浮点数。如果不设置,将使用产线初始化的该参数值(默认为 1.5)。 |
否 |
文本识别阈值 |
textRecScoreThresh |
number | null |
文本识别阈值,得分大于该阈值的文本结果会被保留。 大于 0 的任意浮点数。如果不设置,将使用产线初始化的该参数值(默认为 0.0,即不设阈值)。 |
否 |
可视化 |
visualize |
boolean | null |
支持返回可视化结果图及处理过程中的中间图像。开启此功能后,将增加结果返回时间。
例如,在产线配置文件中添加如下字段:
将默认不返回图像,通过请求体中的visualize参数可以覆盖默认行为。如果请求体和配置文件中均未设置(或请求体传入null、配置文件中未设置),则默认返回图像。
|
否 |
- 请求处理成功时,响应体的
result具有如下属性:
| 名称 | 类型 | 含义 |
|---|---|---|
ocrResults |
object |
OCR结果。数组长度为1(对于图像输入)或实际处理的文档页数(对于PDF输入)。对于PDF输入,数组中的每个元素依次表示PDF文件中实际处理的每一页的结果。 |
dataInfo |
object |
输入数据信息。 |
ocrResults中的每个元素为一个object,具有如下属性:
| 名称 | 类型 | 含义 |
|---|---|---|
prunedResult |
object |
产线对象的 predict 方法生成结果的 JSON 表示中 res 字段的简化版本,其中去除了 input_path 和 page_index 字段。 |
ocrImage |
string | null |
OCR结果图,其中标注检测到的文本位置。图像为JPEG格式,使用Base64编码。 |
docPreprocessingImage |
string | null |
可视化结果图像。图像为JPEG格式,使用Base64编码。 |
inputImage |
string | null |
输入图像。图像为JPEG格式,使用Base64编码。 |
5. 错误码说明
| 错误码 | 说明 | 解决建议 |
|---|---|---|
| 403 | Token 错误 | 检查 Token 是否正确,或 URL 是否与 Token 匹配 |
| 429 | 超出单日解析最大页数 | 请使用其他模型或稍后再试 |
| 500 | 传参错误 | 请确保参数类型及 fileType 正确 |
| 504 | 网关超时 | 请稍后再试 |
注:如果在使用过程中遇到问题,欢迎随时在 issue 区提交反馈。
