# ocrd

**Repository Path**: taj5/ocrd

## Basic Information

- **Project Name**: ocrd
- **Description**: 车厢集装箱识别服务
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-06-24
- **Last Updated**: 2026-08-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OCRD

面向铁路货车图像的 OCR 服务。项目基于 FastAPI 和 MiniCPMV，支持识别货车车型/车号，以及集装箱箱号。服务同时提供面阵相机、线阵相机和本地文件输入，默认监听 `0.0.0.0:9527`。

## 功能

- 面阵相机：`/carriage_ocr_areascan`
- 线阵相机：`/carriage_ocr_linescan`（兼容别名 `/carriage_ocr`）
- 集装箱箱号：`/box_ocr`
- 健康检查：`/health`
- Swagger 文档：`/docs`
- 支持 JPEG、PNG、BMP，单个文件最大 20 MiB
- 支持 NVIDIA GPU（PyTorch CUDA 12.4）

## 运行要求

- Python 3.10 或更高版本
- NVIDIA GPU、驱动和 NVIDIA Container Toolkit（Docker 部署时）
- OCR 大模型目录（MiniCPMV，包含 `config.json`、权重和 tokenizer 文件）

项目依赖和 PyTorch 版本以 [`pyproject.toml`](pyproject.toml) 为准。标准（开发/推荐）环境为 **Ubuntu 22.04 + PyTorch `2.6.0`、torchvision `0.21.0`**，CUDA wheel 使用 `cu124`（index：`https://download.pytorch.org/whl/cu124`）。

### NVIDIA 驱动最低要求

PyTorch 的 CUDA wheel 要求宿主机 NVIDIA 驱动版本不低于对应 CUDA 的最低要求，否则无法启用 GPU 加速。各档位要求如下：

| 场景 | 目标机驱动 | 驱动最高支持 CUDA | 该驱动可支持的最高 PyTorch（GPU） | 本项目可用性 |
| --- | --- | --- | --- | --- |
| 标准（推荐/开发环境） | `550.54.14` | CUDA 12.4 | torch `2.6.0` + torchvision `0.21.0`（cu124，要求驱动 ≥ 550.54.14） | ✅ 可用 |
| 旧机器兼容 | `470.256.02` | CUDA 11.4 | torch `1.12.1` + torchvision `0.13.1`（cu113，要求驱动 ≥ 450.80.02） | ❌ 无法运行本项目，见下方说明 |

> **470.256.02 驱动说明**：
>
> 1. `470.256.02` 驱动最高支持 CUDA 11.4（即 `nvidia-smi` 输出的 "CUDA Version" 为 11.4）。在官方 wheel 中，该驱动可运行的最高组合是 **torch `1.12.1` + torchvision `0.13.1`（cu113 版）**——不是 cu118 版（cu118 要求驱动 ≥ 520.61.05，470.256.02 不满足）。
> 2. 但 torch 1.12.1 是 2022 年的版本：与 numpy 2.x 不兼容，也无法加载基于新版 transformers 的 MiniCPMV 模型。本项目依赖 `numpy>=2.1.1` 并加载 MiniCPMV，需要 **torch ≥ 2.x**；而 torch 2.x 的 GPU wheel 最低为 cu117/cu118（要求驱动 ≥ 515.43.04 / ≥ 520.61.05），470.256.02 均无法满足。
> 3. 结论：**470.256.02 驱动下本项目无法使用 GPU 运行**。两个可行方案：
>    - **CPU 推理**：安装 CPU 版 PyTorch（`pip install torch==2.6.0 torchvision==0.21.0 --index-url https://download.pytorch.org/whl/cpu`），本项目可运行但推理速度较慢；
>    - **升级驱动**：升级至 ≥ 550.54.14 后使用默认 `cu124` 档位，获得 GPU 加速。

#### 档位选择

- **开发环境（默认）**：Ubuntu 22.04，直接使用本项目默认配置（PyTorch `2.6.0` + `cu124`），要求驱动 ≥ 550.54.14。
- **目标机 550.54.14**：保持默认配置即可，驱动满足 `cu124` 最低要求。
- **目标机 470.256.02**：无法 GPU 运行本项目（详见上方说明）。若坚持使用该驱动：CPU 推理按上方命令安装 CPU 版 torch；需要 GPU 则必须升级驱动至 ≥ 550.54.14。

#### 检查驱动与 GPU 可用性

```bash
nvidia-smi    # 查看 Driver Version（CUDA Version 为该驱动支持的最高 CUDA 版本，并非已安装的 Toolkit）
python -c "import torch; print(torch.version.cuda, torch.cuda.is_available())"   # 期望输出类似 12.4 True
```

## 安装与本地运行

```bash
uv sync

# 单卡模式，用物理卡 2
CUDA_VISIBLE_DEVICES=6 OCRD_SERVICE_PORT=9528 uv run server
# 物理卡 2、5 分别映射为代码里的 0、1
CUDA_VISIBLE_DEVICES=2,5 OCRD_OCR_LOAD_MODE=multi uv run server

```

启动后访问 <http://localhost:9527/docs>。配置文件不区分运行环境，所有配置项均可通过环境变量覆盖。

## Docker 部署

`docker-compose.yml` 已配置 GPU、端口和持久化目录。先准备 OCR 模型目录（默认 `/data/models/ocr_model`），再执行：

```bash
docker compose up -d --build
docker compose ps
docker compose logs -f ocrd
```

服务停止或更新：

```bash
docker compose down
docker compose up -d --build
```

### 一键构建并导出镜像

脚本会执行 `docker build`、`docker save`，并生成 SHA256 校验文件。默认镜像名为 `ocrd:latest`，输出到 `artifacts/`：

Linux/macOS：

```bash
chmod +x scripts/build_and_export.sh
scripts/build_and_export.sh
```

自定义镜像名、标签或输出目录：

```bash
IMAGE_NAME=registry.example.com/ocrd IMAGE_TAG=2026.08.10 OUTPUT_DIR=./release \
  scripts/build_and_export.sh
```

在目标服务器导入：

```bash
docker load --input artifacts/ocrd_latest.tar
docker image ls ocrd
```

`scripts/build_and_export.sh` 只导出镜像本身，不包含 OCR 大模型；离线部署建议使用下面的 `make export`，将 YOLO 模型和其他部署文件一起收集到部署包。

### 使用 Makefile 生成离线部署包

`make export` 会构建并导出镜像，同时将离线 compose、README 和 YOLO 模型统一放入 `deploy_package/`。默认镜像标签为 `YYYYMMDD-<short-commit>`，例如 `20260810-a1b2c3d`；也可通过 `IMAGE_TAG` 覆盖。OCR 大模型不会被复制到部署包，需要在离线服务器单独准备。

```bash
make export
```

将整个 `deploy_package/` 复制到离线服务器后，在该目录执行：

```bash
cat IMAGE_INFO.txt
IMAGE_TAR=$(sed -n 's/^IMAGE_TAR=//p' IMAGE_INFO.txt)
docker load --input "$IMAGE_TAR"
# 将 MiniCPMV 模型文件复制到此目录：./models/ocr_model/
docker compose -f docker-compose.offline.yml up -d
```

注意：OCR 大模型通常数 GB，不能缺少；模型目录为空时容器会启动失败。`deploy_package/` 已加入 `.gitignore`，不会提交到 Git。

部署包内的 `deploy_offline.sh` 是目标 Linux 机器上的一键部署脚本。确认 Docker、Docker Compose、NVIDIA Container Toolkit 和 OCR 模型均已准备后执行：

```bash
cd deploy_package
./deploy_offline.sh
```

脚本会校验部署文件和镜像校验和，导入镜像，创建存储目录并启动服务。

如模型不在默认路径，修改 compose 中的 volume 映射和 `OCRD_BIG_MODEL_PATH`，两者必须指向容器内同一个目录。识别结果和日志默认持久化到项目下的 `ocrd_storage/`。

离线部署可使用 [`docker-compose.offline.yml`](docker-compose.offline.yml)。该文件使用相对路径，适合与 `deploy_package/` 一起复制到现场；镜像通过 `docker save`/`docker load` 传输。

## API 使用

所有 OCR 接口均使用 `multipart/form-data`，`image_upload` 与 `image_path` 二选一：

- `image_upload`：上传图片文件
- `image_path`：服务端可访问的本地图片路径

### 货车识别（面阵）

```bash
curl -X POST http://localhost:9527/carriage_ocr_areascan \
  -F "image_upload=@carriage.jpg" \
  -F "filter=true" \
  -F "filter_threshold=0.8"
```

`filter`（默认 `true`）用于过滤无文字图片，`filter_threshold`（默认 `0.8`）为过滤阈值。

### 货车识别（线阵）

```bash
curl -X POST http://localhost:9527/carriage_ocr_linescan \
  -F "image_upload=@linescan.jpg"
```

### 集装箱箱号识别

```bash
curl -X POST http://localhost:9527/box_ocr \
  -F "image_upload=@container.jpg" \
  -F "crop=true"
```

`crop`（默认 `true`）启用自动定位/裁剪；识别结果通常以 `注册号|校验码` 形式返回。

### 响应示例

```json
{
  "image_name": "carriage.jpg",
  "image_md5": "d41d8cd98f00b204e9800998ecf8427e",
  "receiving_time": "2026-08-10T12:00:00",
  "processing_time": 1.523,
  "image_saved_path": "ocrd_storage/areascan/2026-08-10/<md5>.jpg",
  "answer": "C70@1234567",
  "carriage_type": "C70",
  "carriage_id": "1234567"
}
```

### 健康检查

```bash
curl http://localhost:9527/health
```

返回 `status: "healthy"` 且 `models_loaded: true` 才表示模型已加载完成；模型加载期间状态为 `starting`。

## 配置

| 变量 | 默认值 | 说明 |
| --- | --- | --- |
| `OCRD_BIG_MODEL_PATH` | `server/models/ocr_model` | MiniCPMV OCR 大模型路径，必须存在 |
| `OCRD_STORAGE_PATH` | `ocrd_storage` | 图片和日志存储目录 |
| `OCRD_OCR_LOAD_MODE` | `single` | 模型加载方式：`single` 或 `multi` |
| `OCRD_SERVICE_HOST` | `0.0.0.0` | 服务绑定地址 |
| `OCRD_SERVICE_PORT` | `9527` | 服务端口 |
| `CUDA_VISIBLE_DEVICES` | `0`（Docker） | 使用的 GPU 编号 |

上传文件类型和 20 MiB 大小限制在代码中固定定义。全部环境变量均可通过 shell 环境变量或项目根目录 `.env` 文件配置，由 Pydantic 自动读取。

## 项目结构

```text
ocrd/
├── server/main.py          # FastAPI 应用入口
├── server/api/             # HTTP 接口层（业务路由）
├── server/core/            # 基础设施（配置与日志）
├── server/schemas/         # 接口数据模型
├── server/services/        # 业务服务层（模型加载/OCR 推理/后处理）
├── server/models/*.pt      # YOLO 过滤、定位模型
├── server/static/index.html # Web 页面
├── Dockerfile
└── docker-compose*.yml
```

## 运维与排查

```bash
docker compose logs -f ocrd
docker compose restart
nvidia-smi
curl http://localhost:9527/health
```

常见问题：

1. 模型加载失败：确认 `OCRD_BIG_MODEL_PATH` 在宿主机存在，且 compose volume 映射到容器内相同路径。
2. GPU 不可用：确认 `nvidia-smi` 正常，并安装 NVIDIA Container Toolkit。
3. 端口冲突：将 compose 的端口映射改为例如 `19527:9527`，然后访问 `http://localhost:19527`。
4. 磁盘占满：定期清理 `ocrd_storage/areascan`、`linescan` 和 `box_ocr` 下的历史图片。

## 安全提示

不要将模型仓库 token、密码或其他凭据写入 README、代码或 compose 文件。模型下载请使用 ModelScope/其他仓库的本地登录凭据，并按仓库权限管理。

## 许可证

本项目使用 MIT License，详见 [`pyproject.toml`](pyproject.toml)。