# CoreOCRTensorRT

**Repository Path**: corallite/CoreOCRTensorRT

## Basic Information

- **Project Name**: CoreOCRTensorRT
- **Description**: A lightweight, high-performance C++ OCR and YOLO inference service powered by NVIDIA TensorRT, PaddleOCR ONNX, and a simple HTTP API. Supports Windows x64 and Ubuntu x64.
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-09-08
- **Last Updated**: 2026-09-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<p align="center">
  <img src="runtime-assets/coreocr-tensorrt-banner.png" alt="CoreOCRTensorRT OCR and object detection accelerated by TensorRT" width="100%">
</p>

<div align="center">

# CoreOCRTensorRT

[English](README.md) | **简体中文**

**以 TensorRT 为核心推理后端，面向 Windows 与 Linux 的轻量级 OCR 与目标检测 HTTP 服务**

C++17 · TensorRT 加速 · NVIDIA GPU · ONNX 模型 · OCR 文本识别 · YOLO 目标检测

[项目介绍](#项目介绍) · [核心特性](#核心特性) · [快速开始](#快速开始) · [接口文档](#接口文档) · [常见问题](#常见问题) · [许可证与授权](#许可证与授权)

</div>

## 项目介绍

**CoreOCRTensorRT** 是一个以 **NVIDIA TensorRT 为核心推理后端**的 OCR 与目标检测 HTTP 服务。
项目通过 PaddleOCROnnx 原生库集成 TensorRT 的 GPU 推理加速能力，围绕 ONNX 模型部署，
以统一接口提供图像文字识别、YOLO 目标检测和 Tensor 数据输出。

服务层采用 C++17 实现，负责 HTTP 请求处理、配置管理和推理结果返回；底层推理通过原生库调用 TensorRT，
面向 NVIDIA GPU 部署场景。内置浏览器演示页面，便于在本地验证模型效果，也便于 Web、桌面应用及其他语言的客户端接入。

如果你需要将已有 OCR 推理能力部署为接口服务，而不希望另行维护 Python 或 .NET Web 服务运行时，
可以使用本项目构建 Windows x64 或 Linux x64 可执行程序，并携带模型、配置及原生依赖一起部署。

本项目重点是 **TensorRT 推理服务化与跨平台部署集成**，不是模型训练工具，也不等同于上游
[PaddleOCR](https://github.com/PaddlePaddle/PaddleOCR) 完整工具包。实际推理由
`PaddleOCROnnx.dll`（Windows）或 `PaddleOCROnnx.so`（Linux）承担。

> **部署前请注意：** 服务源码、原生推理库、模型权重和第三方运行时具有各自的授权要求。
> 默认配置启用 GPU；首次构建前需准备 OCR 模型、平台原生库及有效授权文件。
> 构建脚本可下载 YOLO 模型和 TensorRT，但不会自动补齐全部部署依赖。

## 核心特性

| 能力 | 说明 |
| --- | --- |
| TensorRT 推理加速 | 以 NVIDIA TensorRT 为核心后端，通过 PaddleOCROnnx 原生库提供 GPU 推理能力，服务层使用 C++17 封装。 |
| 通用 OCR | 支持 Base64 与 multipart 图片上传，返回识别文本或 OCR JSON。 |
| YOLO 目标检测 | 提供检测框 JSON 与原始 Tensor 接口，满足展示与后处理两类需求。 |
| 浏览器演示 | 服务根路径内置 OCR / YOLO 演示页面，可在图片上绘制检测结果。 |
| 跨平台部署 | 提供 Windows x64 和 Ubuntu 24.04 x64 构建入口，统一组织发布资产。 |
| 配置与状态检查 | 通过 JSON 配置模型及推理参数，通过 `/health` 查看引擎初始化状态。 |
| 构建期依赖准备 | 缺失时下载 YOLO 模型和 TensorRT；服务启动阶段不自动下载这些依赖。 |

OCR 是必需能力：初始化失败时服务不会启动。YOLO 是可选能力：未配置模型或初始化失败时，
OCR 和网页仍可用，调用 YOLO 接口会返回对应的初始化错误。

## 快速开始

### 1. 准备环境与资产

在仓库根目录执行后续命令。先按[模型与运行时](#模型与运行时)准备资产，再选择对应平台构建。

| 平台 | 编译环境 | 原生库与运行环境 |
| --- | --- | --- |
| Windows x64 | CMake 3.20+、Visual Studio C++ x64 工具链、Windows PowerShell | `PaddleOCROnnx.dll` / `.lib`，默认 GPU 路径需要兼容的 NVIDIA 驱动、CUDA 和 TensorRT。 |
| Ubuntu 24.04 x64 | CMake 3.20+、G++、Bash、curl、binutils、dpkg-deb | `PaddleOCROnnx.so` 及其匹配的 Linux 原生运行时。 |

默认配置见 [appsettings.json](appsettings.json)，OCR 与 YOLO 的 `use_gpu` 均为 `true`。
切换推理配置前，请确认所用原生库支持目标后端；设置为 CPU 并不保证可以省略库的动态链接依赖。

### 2. 构建并启动

**Windows：**

```powershell
.\build_Release_x64.bat
.\build\windows-x64\Release\CoreOCRTensorRT.exe
```

**Ubuntu 24.04：**

```bash
sudo apt update
sudo apt install -y build-essential cmake curl binutils dpkg ca-certificates
bash ./build_linux_x64.sh
./build/linux-x64/Release/CoreOCRTensorRT
```

依赖安装可能需要管理员权限，构建脚本本身无需通过 `sudo` 执行。
首次下载 TensorRT 可能占用数 GB 网络流量与磁盘空间，请预留下载、解压和发布目录所需空间。

### 3. 体验与调用

启动后访问：

| 入口 | 地址 |
| --- | --- |
| 浏览器演示 | <http://localhost:5000/> |
| 健康检查 | <http://localhost:5000/health> |

使用 `curl` 上传图片获取识别文本，Windows PowerShell 中请使用 `curl.exe`：

```bash
curl -X POST http://localhost:5000/GetOCRTextFile -F "request=@/path/to/image.jpg"
```

`/path/to/image.jpg` 为待识别图片路径。接口列表与返回结构见[接口文档](#接口文档)。

## 模型与运行时

### 资产目录

`runtime-assets/` 是构建输入目录，`build/<平台>/Release/` 是发布输出目录。
下面列出部署相关的主要文件，不代表所有第三方运行时均已包含在仓库中：

```text
runtime-assets/
├── Readme.txt
├── images/
├── models/
│   ├── PP-OCRv6_tiny_det.onnx
│   ├── ch_PP-LCNet_x0_25_textline_ori_cls_mobile.onnx
│   ├── PP-OCRv6_tiny_rec.onnx
│   ├── ppocrv6tiny_dict.txt
│   ├── yolov8s.onnx
│   ├── paddleocr.lic
│   └── paddleocr-linux.lic
└── runtimes/
    ├── win-x64/native/
    │   ├── PaddleOCROnnx.dll
    │   └── PaddleOCROnnx.lib
    └── linux-x64/native/
        └── PaddleOCROnnx.so
```

### 模型与授权文件

| 资产 | 准备方式 |
| --- | --- |
| OCR 检测、方向分类、识别模型及字典 | 准备与当前原生库匹配的文件，放入 `runtime-assets/models/`；默认名称如上。 |
| `yolov8s.onnx` | 平台构建脚本在文件缺失或为空时，从下方 ModelScope 地址下载；已有非空文件则跳过。 |
| Windows OCR 授权 | 放入 `runtime-assets/models/paddleocr.lic`。 |
| Linux OCR 授权 | 放入 `runtime-assets/models/paddleocr-linux.lic`；构建时复制为输出目录的 `models/paddleocr.lic`。 |

YOLO 默认模型下载地址：
[ModelScope / PaddleOCROnnx / yolov8s.onnx](https://www.modelscope.cn/models/paddleocr/PaddleOCROnnx/resolve/master/models%2Fyolov8s.onnx)。
下载先写入 `.partial` 文件，成功后改为正式名称；下载失败会中止构建。
构建成功后，两端脚本都会显式同步该模型到 Release 的 `models/`，包括增量构建。

替换 YOLO 模型时，请同步修改 `YOLOConfig.model_path` 并确认模型与原生接口兼容。
当前下载脚本仍准备默认的 `yolov8s.onnx`，不会根据自定义配置下载其他模型。
Windows 和 Linux 输出统一使用 `OCRConfig.OCRLicense = "models/paddleocr.lic"`，无需为部署平台修改配置路径。

### TensorRT 与 CUDA

当前准备脚本使用 **TensorRT Enterprise 11.1.0.106 / CUDA 12.9** 对应的下载包。
脚本检测到 TensorRT 运行库缺失时，从 NVIDIA 官方地址下载并提取到对应平台的 `native/` 目录，
下载缓存位于 `build/downloads/tensorrt/`。Linux 脚本通过 `dpkg-deb` 提取文件，不执行系统级安装。

| 环境变量 | 用途 |
| --- | --- |
| `TENSORRT_WINDOWS_URL` / `TENSORRT_LINUX_URL` | 覆盖对应平台的 TensorRT 下载地址。 |
| `TENSORRT_WINDOWS_SHA256` / `TENSORRT_LINUX_SHA256` | 在处理下载包时校验 SHA-256；值应从可信来源获取。 |

**Windows：** 安装兼容的 CUDA Toolkit，推荐与下载包匹配的 CUDA 12.9。
准备脚本会在资产目录缺少 `cudart64_12.dll` 时尝试从本机 CUDA 安装复制，找不到则中止构建。
TensorRT ZIP 本身不包含这个 CUDA 运行库。

**Linux：** 将原生库需要的 CUDA 运行时与 TensorRT 库放入同一 `native/` 目录，例如
`libcudart.so.12`、`libnvinfer.so.11` 和 `libnvonnxparser.so.11`。
保留 TensorRT 包中的 `libnvinfer_builder_resource_*.so.*` 文件，不要只保留某个 GPU 架构的资源库。

下载脚本不会安装显卡驱动或完整 CUDA 环境。请核对原生库、TensorRT、CUDA、按需使用的 cuDNN
和显卡驱动之间的版本兼容性；更多发行信息见 [NVIDIA TensorRT](https://developer.nvidia.com/tensorrt/download/11x)。

## 构建与部署

### 项目结构

```text
├── src/                       C++ 服务与推理封装实现
├── include/                   项目头文件
├── third_party/               第三方头文件与许可证
├── scripts/                   平台 TensorRT 准备脚本
├── runtime-assets/            模型、原生库及发布资产
├── CMakeLists.txt             跨平台构建配置
├── appsettings.json           默认服务与推理配置
├── build_Release_x64.bat       Windows 构建入口
└── build_linux_x64.sh          Linux 构建入口
```

### 手动 CMake 构建

推荐优先使用[快速开始](#快速开始)中的平台脚本。直接调用 CMake **不会运行模型或 TensorRT 下载步骤**，
请事先准备完整资产。

**Windows：**

```powershell
cmake -S . -B build/windows-x64 -A x64
cmake --build build/windows-x64 --config Release
```

**Linux：**

```bash
cmake -S . -B build/linux-x64 -DCMAKE_BUILD_TYPE=Release
cmake --build build/linux-x64 --parallel
```

如需使用仓库外的资产目录，可在 CMake 配置命令中追加：

```text
-DPADDLEOCR_ASSETS_DIR="/path/to/runtime-assets"
```

Windows 可使用 `C:/path/to/runtime-assets`。该选项用于直接调用 CMake；当前平台脚本使用仓库内的资产目录。

### 发布目录

| 平台 | 可执行文件 |
| --- | --- |
| Windows | `build/windows-x64/Release/CoreOCRTensorRT.exe` |
| Linux | `build/linux-x64/Release/CoreOCRTensorRT` |

部署时复制整个 Release 目录，而不只是可执行文件。配套目录包括 `models/`、`images/`、
`runtimes/<RID>/native/`，以及 `appsettings.json` 和 `Readme.txt`。

Windows 优先从 `runtimes/win-x64/native/` 加载 `PaddleOCROnnx.dll`，也支持将原生库及其依赖一起放在
EXE 同目录。推荐保持默认布局，避免将依赖分散到不同目录。

Linux 会将整个原生运行时目录复制到发布目录，并为可执行文件设置包含
`$ORIGIN/runtimes/linux-x64/native` 的传递式运行时搜索路径，以支持随程序部署的依赖库。

## 配置与运行

通过 [appsettings.json](appsettings.json) 设置监听地址、模型路径和推理参数：

| 配置节 | 主要内容 |
| --- | --- |
| `Server` | 监听地址、端口、请求体大小上限。 |
| `OCRConfig` | OCR 模型、字典、授权路径、GPU 设置、OCR 实例数及识别参数。 |
| `YOLOConfig` | YOLO 模型路径、GPU 设置、置信度与 IoU 阈值。 |

命令行参数：

```text
--config <path>       指定配置文件
--host <address>      覆盖监听地址
--port <number>       覆盖监听端口
--self-test [image]   执行一次 OCR，不启动 HTTP 服务
```

默认监听 `0.0.0.0:5000`。仅本机使用时可通过 `--host 127.0.0.1` 限制监听范围。
对外提供服务前，请按部署环境配置访问控制、HTTPS 和请求限制，不要将默认监听配置直接视为安全的公网部署方案。
启动错误写入可执行文件同目录的 `CoreOCRTensorRT.error.log`。

## 接口文档

接口采用 `status`、`data`、`errorMessage` 等字段包装结果。
为保持现有接口兼容性，业务错误仍可能返回 HTTP 200，并在响应体中使用 `status: 400`；
客户端需同时检查 HTTP 状态与响应体状态。

### OCR API

| 路由 | 请求 | 响应 `data` |
| --- | --- | --- |
| `GET/POST /GetOCRText` | 裸 Base64 请求体 | 识别文本 |
| `GET/POST /GetOCRJson` | 裸 Base64 请求体 | OCR JSON |
| `POST /GetOCRText` | JSON：`Base64String`、`ResultType` | 文本或 JSON 字符串 |
| `POST /GetOCRTextFile` | multipart 字段 `request` | 识别文本 |
| `POST /GetOCRJsonFile` | multipart 字段 `request` | OCR JSON 字符串 |

Base64 JSON 示例：

```json
{
  "Base64String": "<image bytes as Base64>",
  "ResultType": "json"
}
```

### YOLO API

| 路由 | 请求 | 响应 `data` |
| --- | --- | --- |
| `POST /GetYOLOFileTensor` | multipart 字段 `request` | Tensor 对象 |
| `POST /GetYOLOBase64Tensor` | JSON：`Base64String` | Tensor 对象 |
| `POST /GetYOLOFile` | multipart 字段 `request` | 检测框 JSON |
| `POST /GetYOLOBase64` | JSON：`Base64String` | 检测框 JSON |

Tensor 对象属性示例如下，`data` 仅展示一个元素，实际数组长度由 `elementCount` 表示：

```json
{
  "data": [0.0],
  "shape": [1, 84, 8400],
  "shapeLen": 3,
  "elementCount": 705600
}
```

浏览器 Demo 使用 JSON 路由，避免向页面传输完整 Tensor。检测结果中的 `box` 坐标基于
原图尺寸，页面会按照 `image.width` 和 `image.height` 缩放绘制类别、置信度和边框。

### 响应示例

```json
{
  "status": 200,
  "data": {},
  "errorMessage": "",
  "elapsedTime": "26.5ms"
}
```

`elapsedTime` 使用原生 OCR 返回的 `detectTime`，可与原生 benchmark 的 `full`
指标直接比较。Base64 与图片字节解码、实例租约、DLL 结果 JSON 序列化和结果缓冲区
复制不包含在该值中。

## 常见问题

### Windows 提示无法加载 DLL 或错误 126

错误 126 不一定表示 `PaddleOCROnnx.dll` 本身缺失，也可能是其依赖未找到。
检查发布目录中的 TensorRT 和 `cudart64_12.dll` 等直接、间接依赖，确认文件架构与版本匹配。
模型文件存在不代表原生依赖已经完整。

### Linux 无法创建 CMake 构建目录

先确认构建目录所在文件系统可写、磁盘空间充足。若在 WSL 的 `/mnt/*` 挂载盘上出现
“创建提示已存在，但查询提示不存在”的矛盾，应排查挂载状态，而不是反复修改 `mkdir` 参数或提升构建权限。
可保存工作后重启 WSL，或将项目放到 Linux 自身文件系统中重新构建；不要复用另一位置的 CMake 缓存。

### OCR 可用，但 YOLO 请求失败

检查 `/health` 和 YOLO 初始化错误，确认 `YOLOConfig.model_path` 对应文件存在，且模型格式与原生接口兼容。
YOLO 是可选引擎，其初始化失败不会使已正常初始化的 OCR 停止服务。

### 是否可以离线部署

模型和原生依赖准备完整后，服务启动阶段不执行上述下载步骤。离线构建前也需预先准备资产，
否则平台脚本可能尝试联网。原生库授权的具体要求以其提供方说明为准。

## 参与贡献

欢迎通过 GitHub Issues 反馈问题，通过 Pull Requests 改进代码和文档。
提交问题时，请提供操作系统、编译工具链、原生库与 CUDA / TensorRT 版本、复现步骤和相关错误日志。
涉及接口行为的变更，请附上请求示例及预期响应，便于核对兼容性。

请勿在 Issue、日志或提交中上传授权文件、密钥以及包含个人或业务敏感信息的图片。

## 💬 开发交流群

欢迎加入QQ群 **475159576** 交流，或者添加QQ定制项目：**2380243976**

若您喜欢本项目，请点击免费的 **Star ⭐**

<img src="./runtime-assets/qq.png" width="150px;" />

## 许可证与授权

请区分本仓库服务源码的许可证与外部组件的使用授权：

- **服务源码：** 以本仓库正式发布的许可证文件为准；公开代码本身不等同于授予任意使用或再分发权限。
- **原生推理库与授权文件：** `PaddleOCROnnx.dll` / `.so` 及 `.lic` 的使用和分发需遵守提供方条款。
- **模型权重：** OCR 与 YOLO 模型分别遵循其来源和上游许可，下载成功不代表获得无限制的再分发授权。
- **NVIDIA 组件：** TensorRT、CUDA 和其他 NVIDIA 运行时遵循其各自条款，不因本项目源码公开而改变。

## 致谢

- [PaddleOCR](https://github.com/PaddlePaddle/PaddleOCR)：OCR 上游生态与模型工具；本文档参考其中文 README 的信息组织方式。
- [nlohmann/json](https://github.com/nlohmann/json)：JSON 处理，头文件位于 [third_party/nlohmann](third_party/nlohmann)。
- [cpp-httplib](https://github.com/yhirose/cpp-httplib)：HTTP 服务支持，许可证见 [third_party/cpp-httplib.LICENSE](third_party/cpp-httplib.LICENSE)。

<div align="center">

[返回顶部](#coreocrtensorrt)

</div>