# 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-11

## 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 11.8）

## 运行要求

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

项目依赖和 PyTorch 版本以 [`pyproject.toml`](pyproject.toml) 为准：PyTorch `2.1.2`、torchvision `0.16.2`，CUDA wheel 使用 `cu118`。

## 安装与本地运行

```bash
python -m venv .venv
source .venv/bin/activate       # Windows: .venv\Scripts\activate
python -m pip install -U pip
python -m pip install -e .
```

准备 OCR 大模型后设置路径。路径也可以是宿主机上的绝对路径：

```bash
export APP_ENV=prod
export OCRD_BIG_MODEL_PATH=/data/models/ocr_model
export OCRD_STORAGE_PATH=./ocrd_storage
ocrd
```

Windows PowerShell 示例：

```powershell
$env:APP_ENV = "prod"
$env:OCRD_BIG_MODEL_PATH = "C:\models\ocr_model"
$env:OCRD_STORAGE_PATH = ".\ocrd_storage"
ocrd
```

启动后访问 <http://localhost:9527/docs>。开发环境可将 `APP_ENV` 设为 `dev`（默认值），生产环境建议使用 `prod`。

## 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
```

Windows PowerShell：

```powershell
.\scripts\build_and_export.ps1
```

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

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

```powershell
.\scripts\build_and_export.ps1 -ImageName "registry.example.com/ocrd" -ImageTag "2026.08.10" -OutputDir ".\release"
```

在目标服务器导入：

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

`scripts/build_and_export.*` 只导出镜像本身，不包含 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`，`file` 与 `local_file` 二选一：

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

### 货车识别（面阵）

```bash
curl -X POST http://localhost:9527/carriage_ocr_areascan \
  -F "file=@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 "file=@linescan.jpg"
```

### 集装箱箱号识别

```bash
curl -X POST http://localhost:9527/box_ocr \
  -F "file=@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`。

## 配置

| 变量 | 默认值 | 说明 |
| --- | --- | --- |
| `APP_ENV` | `dev` | 配置环境：`dev`、`prod` 或 `test` |
| `OCRD_BIG_MODEL_PATH` | `ocrd/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 大小限制在代码中固定定义。环境变量采用 `ocrd_` 前缀的 Pydantic 配置名；模型和存储路径由程序直接读取上表中的大写变量。

## 项目结构

```text
ocrd/
├── ocrd/main.py          # FastAPI 应用和路由
├── ocrd/ocr_utils.py     # OCR 推理与结果后处理
├── ocrd/dependencies.py  # 模型加载
├── ocrd/config/           # dev/prod 配置
├── ocrd/models/*.pt       # YOLO 过滤、定位模型
├── 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)。