快速开始

TurboOCR 以单个容器交付。拉镜像、绑 GPU、POST 一份文档、解析 JSON——本页面带你五分钟内拿到第一条真实响应。它是一个完整的文档解析器——文本、版面、表格、公式——而不只是 OCR。

1. 环境要求

Linux 主机，配备 Turing 或更新架构的 NVIDIA GPU（RTX 20 系列 / GTX 16 系列及以上），驱动版本 595+。Docker 已安装 NVIDIA Container Toolkit，使 --gpus all 生效。纯文本部署预留约 4 GB 显存，完整流水线（版面 + 表格 + 公式）约 8 GB。所有模型与语言包都已打包进镜像。

2. 启动容器

从 GHCR 拉取并启动 :latest（生产环境请固定到 :v3.1.0）。HTTP 监听 8000 端口，gRPC 监听 50051。命名卷会保留编译好的 TensorRT 引擎，重启时直接复用。

docker run --gpus all -p 8000:8000 -p 50051:50051 \
  -v trt-cache:/home/ocr/.cache/turbo-ocr \
  ghcr.io/aiptimizer/turboocr:latest

首次启动会从 ONNX 编译 TensorRT 引擎（在 5090 上约 90 秒，旧 GPU 上可能长达一小时——设 TRT_OPT_LEVEL=3 可把编译时间缩短 3–5×，仅带来很小的速度回退）。之后每次重启都直接从 trt-cache 卷加载，瞬间完成。请使用命名卷，不要使用主机 bind-mount——空目录的 bind-mount 会覆盖镜像中预置的模型。

日志显示就绪后，简单验证一下服务：

curl http://localhost:8000/health

3. 发送第一个请求

多个端点覆盖大多数场景。POST /ocr/raw 接收原始图片字节（最快路径）；POST /ocr/pdf 并行渲染并识别每一页 PDF。其他路由：POST /ocr（JSON 内 base64 图片）、POST /ocr/pixels（零解码原始像素缓冲）、POST /ocr/batch（一次请求多张图片）、POST /infer（OCR + 版面 / 阅读顺序 / 块，单次结构化响应）、POST /ocr/markdown（整页 → 忠实 Markdown）。完整 schema 见 API 参考。

图片
PDF

curl -X POST http://localhost:8000/ocr/raw \
  --data-binary @document.png \
  -H "Content-Type: image/png"

curl -X POST http://localhost:8000/ocr/pdf \
  --data-binary @document.pdf \
  -H "Content-Type: application/pdf"

或者用 Python 调用

pip install turboocr

from turboocr import Client

with Client(
    base_url="http://localhost:8000",
    api_key="tocr_live_...",
) as client:
    response = client.recognize_image("invoice.jpg")
    print(response.results[0].text)

4. 解读响应

图片端点返回一个扁平的 results 数组。每个条目包含识别出的文本、[0, 1] 区间的置信度，以及一个像素坐标下的四点边界多边形（左上、右上、右下、左下）。

{
  "results": [
    {
      "text": "Invoice Total",
      "confidence": 0.97,
      "bounding_box": [[42, 10], [210, 10], [210, 38], [42, 38]]
    },
    {
      "text": "$1,284.00",
      "confidence": 0.95,
      "bounding_box": [[220, 10], [320, 10], [320, 38], [220, 38]]
    }
  ]
}

PDF 响应在 pages[] 中为每页包装一个 results 数组，并附带页索引、渲染 DPI 和像素尺寸。在任一端点上追加 ?layout=1 即可同时检测文档区域；每个结果会带上 layout_id，关联到所属区域。/infer 还接受 ?reading_order=1（基于版面区域的 XY-cut，增加一个阅读顺序数组）和 ?as_blocks=1（把单行聚合成段落块）；两者都会自动启用 ?layout=1。

如果某个已配置的阶段没有产出，JSON 会带上 text_degraded / table_degraded / formula_degraded（以及一个 *_warning 字符串），而不是静默返回空结果——部分结果绝不会伪装成一个干净的 200。

5. 表格、公式与 Markdown

表格和公式是严格按需开启的：后端必须在启动时加载，并且请求必须显式索取。所有权重都已打包进镜像——你只需设置后端环境变量来加载该阶段（无需任何路径）。版面默认开启；每个额外阶段仍只在请求索取时才运行。

# Text + layout is the default. Add backends to load the table and
# formula stages, and pick a bigger / other-language OCR tier.
docker run --gpus all -p 8000:8000 -p 50051:50051 \
  -e TABLE_BACKEND=slanext \
  -e FORMULA_BACKEND=ppformulanet_s \
  -e OCR_MODEL=medium \
  -v trt-cache:/home/ocr/.cache/turbo-ocr \
  ghcr.io/aiptimizer/turboocr:latest

# OCR_MODEL: tiny (default) | small | medium | arabic | eslav | korean | thai | greek
# FORMULA_BACKEND: ppformulanet_s (Latin/EN) | ppformulanet_plus_m (Chinese-capable) | vlm

然后按请求开启——?tables=1 和 ?formulas=1 可自由组合，并会自动启用版面：

# Full structured parse: layout regions + tables -> HTML + formulas -> LaTeX.
# tables=1 / formulas=1 auto-enable layout. The backends must be loaded at
# startup (TABLE_BACKEND / FORMULA_BACKEND) or you get a 400, never empties.
curl -X POST "http://localhost:8000/ocr/raw?layout=1&tables=1&formulas=1" \
  --data-binary @paper.png \
  -H "Content-Type: image/png"

响应会新增一个 tables 数组（HTML + 单元格四点框）和/或一个 formulas 数组（LaTeX）。向一个启动时未开启的阶段发请求，会得到硬性 400（TABLE_BACKEND_DISABLED / FORMULA_BACKEND_DISABLED），绝不会静默返回空结果。

要导出整页，POST /ocr/markdown 返回内联表格与公式的忠实 Markdown（GPU 构建；需要版面）：

# Page -> faithful Markdown (GPU build). Requires layout; tables + formulas
# are always included best-effort, since a faithful export needs them.
curl -X POST "http://localhost:8000/ocr/markdown" \
  --data-binary @page.png \
  -H "Content-Type: image/png"

不确定运行中的服务加载了哪些阶段？直接问它：

# Discover which stages and routes a running server actually has loaded.
curl http://localhost:8000/capabilities

6. 试试 Web GUI（Studio）

想点点鼠标？Studio Web UI 让你拖入一张图片或 PDF，运行 OCR，查看版面叠加层与阅读顺序，在页面上选中识别出的文本，并下载可搜索的 PDF。在仓库根目录用一条命令同时启动服务与 GUI（demo compose 已开启表格与公式阶段）：

docker compose -f docker-compose.demo.yml up --build

然后打开 http://localhost:3000。纯 CPU 开发请改用 docker-compose.demo.cpu.yml（CPU 仅供开发/CI——个位数张/秒）。

7. 下一步

API 参考完整的 HTTP 与 gRPC 端点、参数和 JSON Schema —— 内置 Try It 控制台。

客户端可直接上线的 Python、Java、C++ 范例 —— 持久连接、并发分发、gRPC。

配置调优服务：OCR_MODEL 档位、表格/公式后端、流水线池大小、PDF 并行度、日志。

部署 Docker 标签、GPU 与驱动版本对照、TensorRT 缓存卷、Prometheus 监控、生产部署建议。