TurboOCR HTTP API完全参考:9大端点+6个查询参数玩转结构化文档解析

原创2026-10-14 13:47:521,902 阅读

TurboOCR HTTP API完全参考:9大端点+6个查询参数玩转结构化文档解析

TurboOCR 是一个极速 GPU 文档解析引擎,单卡即可做到 200+ img/s,内置 HTTP + gRPC 双协议接口。本文带你快速上手 TurboOCR HTTP API:一次讲清 9 个核心端点和 6 个查询参数,覆盖图片 OCR、批量处理、PDF 解析、流式输出和 Markdown 导出,帮助你用最少的请求拿到文本、版面、表格和公式等完整结构化结果。

TurboOCR GPU文档解析引擎性能对比横幅

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 成本的高速取页图路径。

TurboOCR HTTP API版面检测layout参数三种合并模式示意

💡 记忆口诀: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'

TurboOCR /ocr/raw端点识别扫描书页图片示例

想一次性拿到版面 + 阅读顺序 + 表格,只需加查询参数:

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

TurboOCR /ocr/pixels端点零解码处理高分辨率文本图片

细节:

  • 请求体字节数必须严格等于 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"),一张坏图不会拖垮整批。

TurboOCR /ocr/batch批量识别带表格的表单图片示例

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/ 目录下。

登录后查看全文
TurboOCR