TurboOCR HTTP API完全参考:9大端点+6个查询参数玩转结构化文档解析
TurboOCR HTTP API完全参考:9大端点+6个查询参数玩转结构化文档解析
TurboOCR 是一个极速 GPU 文档解析引擎,单卡即可做到 200+ img/s,内置 HTTP + gRPC 双协议接口。本文带你快速上手 TurboOCR HTTP API:一次讲清 9 个核心端点和 6 个查询参数,覆盖图片 OCR、批量处理、PDF 解析、流式输出和 Markdown 导出,帮助你用最少的请求拿到文本、版面、表格和公式等完整结构化结果。
1️⃣ 为什么选择 TurboOCR HTTP API?
TurboOCR 不是传统 OCR 工具,而是一条完整的文档解析流水线:文本检测/识别 + 版面分析 + 表格→HTML + 公式→LaTeX + 阅读顺序 Markdown,全部跑在同一个 TensorRT FP16 引擎上。相比 VLM 类文档解析器(约 1 页/秒),它的全结构解析可达 ~20 页/秒,且完全本地化、无 API 依赖。
HTTP 接口的设计特点:
- 🚀 零拷贝快路径:
/ocr/raw直接收图片字节,/ocr/pixels连解码都跳过; - 🧩 按请求付费:版面、表格、公式等能力全部通过查询参数按需开启,默认路径零额外开销;
- 📡 流式优先:
/ocr/stream逐页吐出 NDJSON,RAG 场景可边解析边入库; - 🏥 K8s 友好:内置 liveness/readiness 探针和 Prometheus 指标。
完整端点清单见 README.md 的 API 章节,端点源码入口在 src/http/ 目录,完整协议说明见 docs/api/http.md。
2️⃣ 9大端点速览表
| # | 端点 | 方法 | 用途 | 备注 |
|---|---|---|---|---|
| 1 | /ocr/raw |
POST | 原始图片字节 OCR | 最快路径,GPU 用 nvJPEG 解码 |
| 2 | /ocr |
POST | base64 JSON 图片 OCR | 适合不方便发二进制流的场景 |
| 3 | /ocr/pixels |
POST | 裸像素缓冲区 OCR | 零解码,最低延迟入口 |
| 4 | /ocr/batch |
POST | 批量图片(base64 数组) | 单图失败不影响其他图 |
| 5 | /ocr/pdf |
POST | PDF→文本/版面/图片 | 支持文本层快速路径、自动旋转 |
| 6 | /ocr/stream |
POST | PDF/图片逐页流式输出 | GPU 版,NDJSON 协议 |
| 7 | /ocr/markdown |
POST | 单页→忠实 Markdown | GPU 版,自动内嵌插图 |
| 8 | /infer |
POST | 单个裁剪区域走指定后端 | 输入走 JSON body |
| 9 | /capabilities |
GET | 运行时能力探测 | 发请求前先查支持哪些能力 |
另有 /metrics(Prometheus 指标)和 /health/live、/health/ready(健康探针)两个运维端点,详见 docs/api/monitoring.md。
⚠️ 端口约定:Docker 部署经 nginx 对外是 8000 端口;原生编译直接监听 8080(
PORT可改)。
3️⃣ 6个共享查询参数:一次开启全部能力
所有 OCR 端点共享一组查询参数(解析逻辑见 server_types.h 中的 server::parse_query_options()),均接受 1/true/on/yes 这类布尔写法:
| 参数 | 默认 | 效果 |
|---|---|---|
layout |
0 |
运行 PP-DocLayoutV3 版面检测,返回 layout 数组 |
reading_order |
0 |
按版面模型预测的阅读顺序排序文本(列感知 XY-cut 兜底),自动开启 layout |
as_blocks |
0 |
输出段落级 blocks,自动开启 layout + reading_order |
tables |
0 |
运行表格分支(SLANeXt 或 VLM 后端),表格转 HTML 输出 |
formulas |
0 |
运行公式分支(PP-FormulaNet-S),公式转 LaTeX 输出 |
words |
0 |
每个结果附加 words 数组:每个词的文字、置信度和独立边界框 |
还有一个"反向开关":
text(默认1):唯一可关闭的参数。text=0完全跳过文字检测/识别,配合layout=1就是一次纯版面扫描,成本极低;在/ocr/pdf上text=0&images=inline是零 OCR 成本的高速取页图路径。
💡 记忆口诀:layout 打底,reading_order 排序,as_blocks 成段;tables/formulas 严格 opt-in(后端未加载时返回 400 *_BACKEND_DISABLED,绝不会静默返回空结果);words 独立于 layout。
4️⃣ 逐个端点实战
4.1 POST /ocr/raw —— 最快的手
请求体直接是图片字节,支持 JPEG/PNG/WebP/BMP/TIFF。GPU 构建下 JPEG 走 nvJPEG、PNG 走 Wuffs 快速通道:
curl -X POST http://localhost:8000/ocr/raw \
--data-binary @page.jpg \
-H 'Content-Type: image/jpeg'
想一次性拿到版面 + 阅读顺序 + 表格,只需加查询参数:
curl -X POST 'http://localhost:8000/ocr/raw?layout=1&reading_order=1&tables=1' \
--data-binary @page.png -H 'Content-Type: image/png'
响应结构(空数组的可选字段会被省略,文本页响应与旧版完全一致):
{
"results": [
{"id": 0, "text": "Hello world", "confidence": 0.987,
"bounding_box": [[12,8],[180,8],[180,32],[12,32]], "layout_id": 0}
],
"layout": [
{"id": 0, "class": "text", "class_id": 1, "confidence": 0.94,
"bounding_box": [[10,4],[800,4],[800,40],[10,40]]}
],
"reading_order": [0],
"tables": [],
"formulas": []
}
加 ?words=1 后,每条结果里还会出现 words 数组(英文按空格切词、每个 CJK 字独立成词,边界框按真实墨迹空隙裁剪):
{"text": "Hello, world", "words": [
{"text": "Hello,", "confidence": 0.991, "bounding_box": [[14,10],[88,10],[88,30],[14,30]]},
{"text": "world", "confidence": 0.983, "bounding_box": [[97,10],[176,10],[176,30],[97,30]]}
]}
尺寸守卫:MAX_IMAGE_DIM 默认 16384,PNG/JPEG 会在解码前嗅探头部提前拦截超大图。
4.2 POST /ocr —— base64 图片进 JSON
请求体为 {"image": "<base64>"},适合不方便发二进制的客户端(如部分 Web SDK)。JPEG 输入同样会走 GPU 直解码快路径,处理逻辑见 ocr_base64_route.cpp。
4.3 POST /ocr/pixels —— 零解码最低延迟
如果你手上已经是解码好的 BGR/灰度缓冲区(比如视频帧、OpenCV 读出的内存图),直接把像素发过来,width/height/channels 走查询参数:
curl -X POST 'http://localhost:8000/ocr/pixels?width=1280&height=720&channels=3' \
-H 'Content-Type: application/octet-stream' \
--data-binary @frame.bgr
细节:
- 请求体字节数必须严格等于
width × height × channels,否则400 BODY_SIZE_MISMATCH; - 旧版
X-Width/X-Height请求头仍可用,但会收到Deprecation: true响应头; - 查询参数与旧头部同时给出且不一致 →
400 DIMENSION_CONFLICT。
4.4 POST /ocr/batch —— 批量图片一次搞定
请求体是 base64 图片数组:{"images": ["<b64>", "<b64>", ...]},≥2 张 JPEG 时启用 nvJPEG 批量解码。响应数组与输入严格对齐:成功槽位进 batch_results,失败槽位进 errors 数组(如 "base64_decode_failed"),一张坏图不会拖垮整批。
curl -X POST 'http://localhost:8000/ocr/batch?layout=1' \
-H 'Content-Type: application/json' \
-d '{"images": ["'$(base64 -w0 page1.jpg)'", "'$(base64 -w0 page2.jpg)'"]}'
{
"batch_results": [
{"results": [{"text": "page1 line", "confidence": 0.96,
"bounding_box": [[0,0],[200,0],[200,30],[0,30]]}], "layout": []},
{"results": [], "layout": []}
],
"errors": [null, "decode_failed"]
}
4.5 POST /ocr/pdf —— PDF 解析瑞士军刀
接受三种请求体:原始 PDF 字节(application/pdf)、{"pdf": "<base64>"} JSON、或 file/pdf 字段的 multipart。页面用 PDFium 渲染,逐页并行跑流水线(实现见 pdf_route.cpp)。
关键查询参数:
| 参数 | 取值 | 说明 |
|---|---|---|
mode |
ocr(默认) / geometric / auto / auto_verified |
geometric 只读文本层绝不 OCR;auto 文本层可信就用文本层否则 OCR;auto_verified(仅 GPU)用 OCR 结果与文本层交叉校验 |
dpi |
50–600,默认 100 | 渲染分辨率 |
markdown=1 |
— | 整个 PDF 直接转成忠实 Markdown,&as_pages=1 改返 JSON 分页 |
images=inline |
— | 每页附 base64 页图,可用 format/quality/lossless/png_compression/max_side 控制编码 |
autorotate=1 |
— | PP-LCNet_x1_0_doc_ori 先校正 0/90/180/270° 旋转,受影响页带 orientation_deg 字段 |
# 典型用法:auto 模式 + 150dpi + 版面
curl -X POST 'http://localhost:8000/ocr/pdf?mode=auto&dpi=150&layout=1' \
--data-binary @doc.pdf -H 'Content-Type: application/pdf'
# 一句话转 Markdown
curl -X POST 'http://localhost:8000/ocr/pdf?markdown=1' \
--data-binary @paper.pdf -H 'Content-Type: application/pdf'
响应按页组织,文本层来源的文字会带 "source": "pdf",text_layer_quality 告诉你该页文本层是 absent/rejected/trusted:
{
"pages": [
{"page": 1, "page_index": 0, "dpi": 150, "width": 1240, "height": 1754,
"results": [{"text": "Title", "confidence": 1.0,
"bounding_box": [[50,80],[420,80],[420,120],[50,120]],
"source": "pdf"}],
"layout": [], "mode": "geometric", "text_layer_quality": "trusted"}
]
}
两个大文档警告:
- ⚠️ 页数上限
MAX_PDF_PAGES默认 2000,超出返回400 PDF_TOO_LARGE; - ⚠️ 长文档期间连接静默超过
IDLE_CONNECTION_TIMEOUT_S(默认 120s)会被掐断(nginx 下表现为 504),可把该值调大,0表示不限。
4.6 POST /ocr/stream —— 流式逐页输出(GPU 版)
一个端点同时吃 PDF 和单图(按魔数嗅探),响应是 application/x-ndjson:每完成一页立刻冲出一行 JSON,RAG 摄取器可以第 1 页还没读完就开始切片嵌入。
{"event":"meta","kind":"pdf","pages":500,"dpi":100,"mode":"ocr"}
{"event":"page", ...同 /ocr/pdf 的 pages[] 元素...}
{"event":"page_error","page_index":17}
{"event":"error","code":"..."}
{"event":"end","pages":500,"failed":0}
curl -sN -X POST 'http://localhost:8000/ocr/stream?layout=1' \
--data-binary @doc.pdf -H 'Content-Type: application/pdf'
注意:页事件乱序到达(谁先完成谁先出),需要顺序请按 page_index 重排;流必须走 keep-alive 连接,带 Connection: close 会被直接 400 拒绝。
4.7 POST /ocr/markdown —— 单页→忠实 Markdown(GPU 版)
跑满流水线(强制 layout + reading order),把整页导出为忠实 Markdown:标题层级、双栏合并、公式转 $…$/$$…$$ LaTeX、表格转 HTML、插图以 base64 data: URI 内联(自包含单文件 .md)。等价于 PaddleOCR 生态的 save_to_markdown,但跑在进程内。
curl --data-binary @page.png http://localhost:8000/ocr/markdown > page.md
序列化规则详见 docs/output_markdown.md。
4.8 POST /infer —— 指定后端处理单个裁剪
面向已经切好的区域(crop),把单个裁剪区域交给指定后端处理,输入全部走 JSON body(无查询参数),实现见 infer_route_gpu.cpp。适合做版面后处理、对特定区域二次推理等场景。
4.9 GET /capabilities —— 发请求前先探路
返回服务端实际加载了什么,避免盲发 ?tables=1 收到 400:
curl http://localhost:8000/capabilities
{
"is_gpu": true,
"features": { "layout": true, "tables": true, "formulas": true, "autorotate": false },
"routing": { "routes": { "table": "table-env", "formula": "formula-env", "text": "default" } }
}
顺带一提:GET /metrics 提供 Prometheus 文本指标(请求量、延迟直方图、池耗尽次数、GPU 显存等,见 docs/api/monitoring.md);GET /health/live 是存活探针,GET /health/ready 是就绪探针(TensorRT 引擎首启构建期间会正确返回 503 NOT_READY,nginx 会自动映射为带 Retry-After: 15 的 503,让客户端退避而不是硬失败)。
5️⃣ 统一错误码与排错指南
所有错误都走同一个 JSON 信封(错误码定义见 ocr.proto,与 gRPC 的 x-error-code 元数据同源):
{"error": {"code": "DIMENSIONS_TOO_LARGE",
"message": "Image dimensions 32000x32000 exceed maximum of 16384x16384"}}
| 场景 | 错误码 | 处理建议 |
|---|---|---|
| 请求体为空 | EMPTY_BODY |
检查是否漏传 --data-binary |
| 图片解码失败 | IMAGE_DECODE_FAILED / GPU_DECODE_FAILED |
确认文件完整、Content-Type 正确 |
| 图片过大 | DIMENSIONS_TOO_LARGE / PIXELS_TOO_LARGE |
降采样,或调大 MAX_IMAGE_DIM / MAX_IMAGE_PIXELS_MP |
| 版面未启用却请求 layout 类参数 | LAYOUT_DISABLED |
启动时去掉 DISABLE_LAYOUT=1 |
| 请求了未加载的表格/公式后端 | TABLE_BACKEND_DISABLED / FORMULA_BACKEND_DISABLED |
启动时加 TABLE_BACKEND=slanext / FORMULA_BACKEND=ppformulanet_s |
| 未加载文档方向模型却请求自动旋转 | AUTOROTATE_DISABLED |
提供 models/doc_ori.onnx(DOC_ORI_ONNX) |
| 尺寸信息缺失/冲突(pixels) | MISSING_DIMENSIONS / DIMENSION_CONFLICT |
用 ?width=&height= 查询参数并保证与请求体大小一致 |
| base64 解码失败 | BASE64_DECODE_FAILED |
检查 base64 完整性 |
| PDF 页数超限 | PDF_TOO_LARGE |
拆分文档或调大 MAX_PDF_PAGES |
| GPU 流水线池满 | 503 SERVER_BUSY |
提高 PIPELINE_POOL_SIZE 或降低并发 |
📌 排查三板斧:curl /capabilities 看能力 → curl /health/ready 看就绪 → curl /metrics 看哪个 route 在报错。
6️⃣ 总结:一张表选端点
| 你的需求 | 选哪个 |
|---|---|
| 发一张图片要文字 | /ocr/raw?layout=1&reading_order=1 |
| 视频流/内存像素实时 OCR | /ocr/pixels |
| 一次传几十张图 | /ocr/batch |
| 扫描件 PDF 全文档 | /ocr/pdf?mode=ocr&dpi=150&layout=1 |
| 电子版 PDF 要精确文字 | /ocr/pdf?mode=geometric |
| 大文档 RAG 边解析边入库 | /ocr/stream |
| 直接要 Markdown 文档 | /ocr/pdf?markdown=1(整本)或 /ocr/markdown(单页) |
| 只要版面不要文字 | /ocr/raw?text=0&layout=1 |
| 词级框(高亮/点击跳转) | 任意端点 ?words=1 |
TurboOCR HTTP API 的设计哲学一句话:默认最快,能力按查询参数逐个付费,出错永远大声报错。配合 docs/api/grpc.md 的 gRPC 接口(同一套流水线、同样的错误码),你可以按客户端生态自由选择协议。更多参数细节可查阅 docs/api/http.md,源码入口都在 src/http/ 与 include/turbo_ocr/http/ 目录下。




