配置

通过 docker run -e KEY=VALUE 传入环境变量来配置 TurboOCR。所有设置都在容器启动时读取一次——改动需重启容器才生效。每次请求的行为（layout、PDF 模式、渲染 DPI）通过查询参数控制，详见 API 参考。

速查表

变量	默认值	说明	何时修改
OCR_MODEL	tiny	识别模型选择器。PP-OCRv6 档位 tiny / small / medium（拉丁文 + 中文 + 日文），或 PP-OCRv5 单文字模型 arabic / eslav / korean / thai / greek。未知取值会致命退出并打印有效列表。	需要更高精度（small/medium）或非拉丁/中文/日文的文字。
TABLE_BACKEND	未设置	slanext 加载 SLANet-Plus（表格 → HTML）；编码器从内置 bundle 自动解析。（vlm 路由到 VL 端点。）?tables=1 生效需要启动时设置它。	你要解析表格。
FORMULA_BACKEND	未设置	ppformulanet_s（英文/拉丁文，默认引擎）ppformulanet_plus_m（支持中文，仅 GPU）或 auto（仅 GPU：全部先跑 -S，含 CJK 的裁剪再跑 plus-M — 英文输出与 -S 逐字节一致）加载公式 → LaTeX。（vlm 路由到 VL 端点。）?formulas=1 生效需要启动时设置它。	你要解析公式。
PIPELINE_POOL_SIZE	自动	并发 GPU 流水线数量。启动时按总显存自动选定。	与其他工作负载共用 GPU 时设上限，或固定值便于容量规划。
TURBO_OCR_CUDA_GRAPHS	1	预热时为识别批量形状烘焙 CUDA 图（自 v3.1.0 起默认开启）：吞吐 +10–16%、p50 更低、精度不变，每条流水线多占约 0.5 GiB 显存。	显存紧张的显卡设为 0。
DISABLE_LAYOUT	0	设为 1 完全跳过加载 PP-DocLayoutV3。此时 ?layout=1 请求会报错。	你确定永远不会用到版式检测。
LAYOUT_MERGE_MODE	all	如何调和嵌套的版式框：all（全部保留）/ outer（保留外层容器）/ inner（保留最内层）。	表单在 outer 下会塌掉——保持 all。
LAYOUT_KEEP_NESTED_CHILDREN	0	设为 1 额外保留嵌套在父区域内的子框。	你需要呈现每一个嵌套区域。
ENABLE_PDF_MODE	ocr	/ocr/pdf 在请求未带 ?mode= 时的默认模式：ocr / geometric / auto / auto_verified。	你处理可信 PDF，且想要更快的默认路径。
DISABLE_ANGLE_CLS	0	设为 1 跳过角度分类器（每张图省约 0.4 ms）。	你只识别正立文本。
DET_LIMIT_TYPE	min	检测缩放策略：min 把较短边放大到 DET_LIMIT_SIDE_LEN；max 把较长边缩小。	想缩小大尺寸扫描以提吞吐时改为 max。
DET_LIMIT_SIDE_LEN	64（min）	缩放策略的目标边长。在 max 下默认改为 DET_MAX_SIDE_LIMIT（自 v3.1.0 起——单独设置 max 会保持原始分辨率，而不是缩到 64 px）。	调整检测输入分辨率。
DET_MAX_SIDE_LIMIT	1280	限定缩放后较长边的上限。（PaddleOCR 的 4000 会撑爆预分配的内存池。）	高分辨率扫描中字号很小时调高。
REQUEST_TIMEOUT_MS	60000	每次请求的推理截止时间（ms）。超时 → 504 INFERENCE_TIMEOUT 并释放槽位。0 = 无界（v3 之前的行为）。	更严的 SLA（调低）或长单任务（调高）。
PIPELINE_HARD_KILL_MS	600000	看门狗硬杀边界（ms）。若某 worker 在截止触发后仍卡在 CUDA 中超过此时长，进程退出以便编排器重启。	极少；仅在 REQUEST_TIMEOUT_MS=0 时失效。
PORT	8080	Drogon 二进制监听的 HTTP 端口。容器内 nginx 在 8000 前置反向代理到此端口。	容器内端口冲突。
GRPC_PORT	50051	gRPC 端口。	端口冲突。
PDF_DAEMONS	16	常驻的 PDFium 渲染守护进程数。	PDF 流量大时调高，让更多渲染器随时待命；想省内存时调低。
PDF_WORKERS	4	单个 PDF 请求内部的渲染并发度。	主要处理多页大型 PDF 时调高，让多页并行渲染。
HTTP_THREADS	max(pool * 32, 128)	Drogon 用于派发阻塞推理的工作线程数。	高并发下出现线程饥饿时调整，一般无需改动。
MAX_PDF_PAGES	2000	渲染前先拒掉超过此页数的 PDF。	托管或多租户场景下收紧上限。
MAX_BATCH_IMAGES	1024	/ocr/batch 与 gRPC RecognizeBatch 的单次图片数上限；超出 → 400 BATCH_TOO_LARGE。	更大的客户端批量。
MAX_BODY_MB	100	单次请求体大小上限（MB），启动时按 1..102400 校验，越界会以明确报错直接退出。Drogon HTTP 服务和前置 nginx 共用同一值。	接受更大上传（调高）或托管场景需要更严限制（调低）。
LOG_LEVEL	info	取值 debug / info / warn / error。	生产环境想更安静，调试时想更详细。
LOG_FORMAT	json	json（每行一个结构化对象）或 text（人类可读）。	本地开发时 text 更便于直接看。

不启动也能查看解析后的配置

turboocr-server --print-config 把完全解析后的配置（env + CLI）以 JSON 打印并退出，--check-config 只做校验（有效返回 0，有误返回 2）。越界整数、未知枚举值以及 PORT == GRPC_PORT 都是致命的——服务器会拒绝绑定。完整参考有 35+ 个变量；见仓库配置文档。

模型选择

OCR_MODEL 是唯一的识别模型选择器。所有模型都在镜像构建阶段就预置进去（基于固定版本的 PaddleOCR Release，SHA256 校验）——容器启动时不会再下载，也不依赖网络。切换就是用不同的值重启容器。

三个 PP-OCRv6 档位覆盖拉丁文 + 中文 + 日文，以精度换速度，而非以语言覆盖换速度：

• tiny (默认) —— 最高吞吐；最快的档位。
• small —— 折中档位。
• medium —— 最高精度；FUNSD 92% / CORD 93% 词级 F1 用的就是它。

其他文字通过同一变量使用保留的 PP-OCRv5 识别模型：

• arabic、eslav（东斯拉夫——俄语、乌克兰语等）、korean、thai、greek。

`OCR_LANG` 是已弃用的别名

OCR_LANG 仍可用，但使用时会警告；两者同时设置时以 OCR_MODEL 为准。请处处优先使用 OCR_MODEL；旧的 latin/chinese 语言取值会映射到 v6 档位。

使用命名卷，不要用 bind-mount

TensorRT 缓存请挂成命名 Docker 卷（-v trt-cache:/home/ocr/.cache/turbo-ocr）。把宿主机的空目录 bind-mount 上去会覆盖 /home/ocr/.cache/turbo-ocr，预置的模型随之消失，服务就找不到模型可加载。

表格与公式

两个阶段都是严格按需开启，并在本地纯 C++ 运行——无 Python，无 sidecar。某阶段仅在其后端环境变量于启动时设置后才加载，且仅在请求带 ?tables=1 / ?formulas=1 时才运行（这两者也会自动启用 ?layout=1）。

• TABLE_BACKEND=slanext —— SLANet-Plus（TRT FP16 CNN 编码器 + 手写 C++ GRU 解码器），表格 → 带单元格四点框的 HTML。编码器从内置 bundle 自动解析。
• FORMULA_BACKEND=ppformulanet_s —— PP-FormulaNet-S，公式 → LaTeX。英文/拉丁文，默认引擎；进程内纯 C++（GPU 构建用 ORT-CUDA-13，CPU 构建用 ORT-CPU）。
• FORMULA_BACKEND=ppformulanet_plus_m —— 支持中文的公式引擎（仅 GPU）。
• 任一后端都可设为 vlm，把该阶段路由到 VL 端点而非本地模型。

向一个启动时未开启的阶段发请求，会得到硬性 400 TABLE_BACKEND_DISABLED / 400 FORMULA_BACKEND_DISABLED——绝不会静默返回空结果。已配置但加载失败的阶段会在启动时直接失败，而不是对外提供空结果。

流水线池

每条流水线持有自己的 CUDA stream，每次只服务一个请求。PIPELINE_POOL_SIZE 在启动时根据总显存自动选定。下列情况建议显式设置：

• 与其他进程共用 GPU 时设上限。
• 自动检测偏保守时强制取更大的值。
• 跨部署固定一个已知值，便于容量规划。

HTTP_THREADS 默认是 max(pool * 32, 128)。这个倍数考虑了 PDF 请求会同时占用多个流水线槽位的情况，一般不必覆盖。

显存预算

默认池大小下，纯文本部署预算约 4 GB，完整流水线（版面 + 表格 + 公式）约 8 GB。每增加一个 PIPELINE_POOL_SIZE 副本，再加约一整套，因此显存随池大小增长——在共享或较小的卡上请固定一个更小的值。

版式检测

版式检测（PP-DocLayoutV3，RT-DETR-L，25 类区域）在启动时加载，但只有请求带 ?layout=1（或经由 ?tables=1 / ?formulas=1 隐式触发）才会真正运行。不带的请求零版式开销。

设 DISABLE_LAYOUT=1 可完全跳过加载该模型。仅在你确定该部署永不需要版式检测时这么做——禁用之后，?layout=1 请求会直接返回错误。

嵌套框调和

LAYOUT_MERGE_MODE（默认 all）控制检测器的嵌套框如何调和：

• all (默认) —— 保留每一个框，使模型嵌套在较大区域内的公式/表格/标题永不被丢弃。
• outer —— 保留外层容器区域，丢弃嵌套其内的框。会塌掉表单——表单里每个字段都坐落在外框内，那里请用 all 或 inner。
• inner —— 保留最内层的框，丢弃纯容器。

旧的 large / small / union 名称作为 outer / inner / all 的已弃用别名仍被接受。设 LAYOUT_KEEP_NESTED_CHILDREN=1 可额外呈现嵌套在父区域内的子框。

PDF 默认模式

ENABLE_PDF_MODE 设定 /ocr/pdf 在请求未带 ?mode= 时的回退模式。四种模式：

• ocr —— 渲染每页并跑完整 OCR 流水线。基准速度；不受文本层伪造影响，是安全默认值。
• geometric —— 只读取 PDFium 文本层，不做光栅化。比 ocr 快约 10×，但完全相信 PDF 作者写入的内容。
• auto —— 按页判断：有文本层就用文本层，否则做 OCR。处理来源可信的混合 PDF 时最快。
• auto_verified —— 跑完整 OCR，再与文本层交叉校验，原生文本只在通过启发式检查（字符数、替换符比例、无旋转）时才被接受。比 ocr 略慢。

PDF 文本层信任模型

除 ocr 之外的模式都要读取 PDF 自带的文本层，而文本层完全由 PDF 作者控制。恶意 PDF 可以塞入不可见文本或通过 ToUnicode 重映射字形。如果你的服务接收来源不可信的 PDF，请保留全局默认 ocr，仅在你能控制来源的请求里通过 ?mode= 临时切换。

角度分类器

角度分类器在识别前处理旋转 90°、180°、270° 的文本，每张图开销约 0.4 ms。如果你只识别正立扫描件（例如自动定向的扫描仪输出）并想榨出这点时间，可以设 DISABLE_ANGLE_CLS=1，代价是旋转文本会被错读。

检测输入分辨率

三个旋钮决定检测模型看到的图：

• DET_LIMIT_TYPE（默认 min）—— 缩放策略。min 把较短边放大到 DET_LIMIT_SIDE_LEN；max 把较长边缩小到它。
• DET_LIMIT_SIDE_LEN（默认 64）—— 该策略的目标边长。
• DET_MAX_SIDE_LIMIT（默认 1280）—— 限定缩放后较长边的上限。官方 PaddleOCR 用 4000，但那会撑爆预分配的内存池；1280 已能让绝大多数文档以原生分辨率运行。高分辨率扫描中字号很小时调高。

DET_MAX_SIDE 仍被当作 TensorRT 引擎优化 profile MAX 边的单旋钮覆盖项；修改它会使缓存引擎失效并触发一次性重建。

请求生命周期

REQUEST_TIMEOUT_MS（默认 60000）是每次请求的推理截止时间。超时后，单图/批量/gRPC 请求返回 504 INFERENCE_TIMEOUT 并释放其 GPU 槽位；PDF 任务的逐页 join 由同一值按页数缩放后界定。设为 0 禁用它（无界等待——v3 之前的行为）。

PIPELINE_HARD_KILL_MS（默认 600000）是派发器看门狗的硬杀边界。若某 worker 在截止触发并请求回收后仍卡在 CUDA 中超过此时长，进程退出以便编排器重启。当 REQUEST_TIMEOUT_MS=0 时它失效（看门狗仅在设置了截止后才扫描）。

v3 默认开启看门狗

由于 REQUEST_TIMEOUT_MS 现在默认 60000（原为 0），逐请求 504 路径和硬杀看门狗都开箱即用。设 REQUEST_TIMEOUT_MS=0 可恢复 v3 之前的无界等待行为。

输入尺寸限制

服务器在真正干活之前就会拒掉超大输入，返回 400：

• MAX_BATCH_IMAGES（默认 1024）—— /ocr/batch 与 gRPC RecognizeBatch 的单次图片数上限 → 400 BATCH_TOO_LARGE。
• MAX_PDF_PAGE_PIXELS_MP（默认 40）—— PDF 单页渲染后的最大百万像素（解压炸弹防护）→ 400 PIXELS_TOO_LARGE。
• MAX_IMAGE_PIXELS_MP（默认 128）—— 图片路由上的总图像面积上限 → 400 DIMENSIONS_TOO_LARGE。
• MAX_IMAGE_DIM（默认 16384）—— 解码路由上的单边像素上限。

端口与拆分模式

PORT（默认 8080）是 Drogon 二进制监听的端口。容器内 nginx 在 8000 前置，通过 keep-alive 反向代理到此端口——用来吸收连接风暴。GRPC_PORT（默认 50051）由二进制直接监听，且必须与 PORT 不同（否则致命）。

仅在你的环境出现端口冲突时才修改 PORT / GRPC_PORT。

PDF 流水线调优

PDF 请求在到达 GPU 之前会经过两层并发池：

• PDF_DAEMONS（默认 16）—— 常驻的 PDFium 守护进程，每个单线程，一次处理一个 PDF。PDF 并发量大时调高；想省内存时调低。
• PDF_WORKERS（默认 4）—— 单个 PDF 请求内部的渲染并发度。主要处理多页大型 PDF 时调高，让多页并行渲染；处理大量小 PDF 时保持默认即可。
• MAX_PDF_PAGES（默认 2000）—— 单个请求的页数硬上限。超过的请求在渲染开始前就被拒掉。
• HTTP_THREADS（默认 max(pool * 32, 128)）—— Drogon 的阻塞工作池。PDF 请求会在整个渲染加 OCR 周期内占住一个槽位，所以这里的倍数是有意为之，仅在高负载下出现线程饥饿时再覆盖。

请求体上限

MAX_BODY_MB（默认 100，范围 1..102400）限定服务器接受的请求体大小。Drogon HTTP 服务和前置的 docker nginx 反向代理在启动时读取同一值，因此上限被一致执行，超大上传会在边缘被以 413 拒绝，而不是被读入内存。

该值在启动时校验——任何超出 [1, 102400]（或非数字、前导零等）的值都会以明确错误信息直接崩溃，而不是在 90 秒后以一个令人困惑的 nginx 解析错误失败。

取一个匹配 `MAX_PDF_PAGES` 的值

一份 2000 页、100 dpi 渲染为 PNG 的 A4 PDF 约 80 MB。默认 100 能从容覆盖；如果你服务异常长的文档，请把 MAX_PDF_PAGES 和 MAX_BODY_MB 一起调高。

日志

LOG_FORMAT=json 每行输出一个结构化对象，可直接被任意日志管道（Loki、Elasticsearch、CloudWatch）摄取。LOG_FORMAT=text 在本地开发时直接 tail 更友好。

LOG_LEVEL=debug 会输出每个请求的耗时拆分；生产环境用 info 即可。warn 和 error 更安静——适合高吞吐托管部署，那种场景下每行日志都是钱。

示例：完整流水线生产部署

典型的结构化解析配置——精确的 medium 识别模型、表格与支持中文的公式后端、固定池大小，以及 JSON 日志：

docker run --gpus all -p 8000:8000 -p 50051:50051 \
  -v trt-cache:/home/ocr/.cache/turbo-ocr \
  -e OCR_MODEL=medium \
  -e TABLE_BACKEND=slanext \
  -e FORMULA_BACKEND=ppformulanet_plus_m \
  -e PIPELINE_POOL_SIZE=3 \
  -e LOG_LEVEL=info \
  -e LOG_FORMAT=json \
  ghcr.io/aiptimizer/turboocr:v3.1.0

部署拓扑、GPU 与驱动版本对照、Docker 标签选择请见部署指南。