CnOCR Documentation

To fine-tune an existing model instead of training from scratch, you should use a smaller learning rate and configure the lr_scheduler. Avoid over-fitting during fine-tuning.

Example configuration for fine-tuning:

• Set learning_rate to a small value (e.g., 3e-5).
• Configure lr_scheduler with cos_warmup and appropriate warmup epochs.

{
  "learning_rate": 3e-5,
  "lr_scheduler": {
    "name": "cos_warmup",
    "min_lr_mult_factor": 0.01,
    "warmup_epochs": 2
  }
}

For users in China, a domestic mirror of the Hugging Face demo is available for faster access.

https://hf.qhduan.com/spaces/breezedeus/CnOCR-Demo

CnOCR provides a FastAPI-based HTTP service. To use this feature, you must first install the service dependencies:

pip install cnocr[serve]

Once installed, start the server using cnocr serve.

Key options:

• -p, --port: Server port (default: 8501).
• -H, --host: Server host (default: 0.0.0.0).
• --reload: Reload the server automatically when code changes.

By default, the onnxruntime package is installed for CPU usage. To enable GPU acceleration for ONNX models, you must uninstall the CPU version and install onnxruntime-gpu.

pip uninstall onnxruntime
pip install onnxruntime-gpu

Models can be downloaded for free from HuggingFace repositories:

• cnstd-cnocr-models
• breezedeus/cnocr-ppocr-*
• breezedeus/cnstd-ppocr-*

Alternatively, you can download them from Baidu Netdisk using the following credentials:

• URL: Baidu Netdisk Link
• Extraction Code: nocr

You can install CnOCR with CPU support using the following command. Note that if you haven't installed PyTorch or OpenCV before, you might encounter common installation issues that can be resolved via standard search engines.

$ pip install cnocr[ort-cpu]

Install CnOCR using pip. Ensure you are using Python 3.8 or later. Choose the installation variant based on your environment:

• CPU (ONNX Runtime): pip install cnocr[ort-cpu]
• GPU (ONNX Runtime): pip install cnocr[ort-gpu]
• Development (for training models): pip install cnocr[dev]

If installation is slow, use a mirror like Aliyun:

pip install cnocr[ort-cpu] -i https://mirrors.aliyun.com/pypi/simple

Alternatively, pull the pre-installed Docker image:

docker pull breezedeus/cnocr:latest

CnOCR provides an HTTP service based on FastAPI.

1. Install dependencies: You must install the serve extra.
2. Start the service: Use the cnocr serve command. Use the -p flag to specify the port.
3. Endpoint: The service provides an /ocr endpoint that accepts an image file.

CnOCR provides several categories of recognition models optimized for different scenarios. Choose a model based on your input image type:

• scene- models: Optimized for general photos taken by cameras (e.g., scene-densenet_lite_136-gru).
• doc- models: Optimized for document screenshots or scans (e.g., doc-densenet_lite_136-gru).
• number- models: Optimized for recognizing only digits (0-9), ideal for bank cards or ID numbers (e.g., number-densenet_lite_136-fc).
• general models: Standard models for images without a specific bias (e.g., densenet_lite_136-gru).

Note: For best results, test the model against your specific data as these categories are guidelines.

You can pull a pre-configured Docker image from Docker Hub to use CnOCR immediately.

$ docker pull breezedeus/cnocr:latest

If the system cannot automatically download the model zip file, follow these steps:

1. Download the model zip file from cnstd-cnocr-models or via Baidu Netdisk (extraction code: nocr).
2. Place the downloaded zip file into the ~/.cnocr/2.3 directory.
3. The code will handle the subsequent extraction and setup automatically once the file is in place.