| --- |
| pipeline_tag: image-text-to-text |
| license: mit |
| tags: |
| - rocm |
| - amd |
| - rdna4 |
| - gfx1201 |
| - ocr |
| - runtime |
| --- |
| |
| # Unlimited-OCR RDNA 4 |
|
|
| Single-GPU [Baidu Unlimited-OCR](https://huggingface.co/baidu/Unlimited-OCR) inference for AMD RDNA 4 |
| (`gfx1200` / `gfx1201`) using native ROCm PyTorch, verified end to end on `gfx1201`. |
|
|
| This project does **not** redistribute or rename Baidu's weights. It provides a reproducible runtime around the original |
| BF16 checkpoint: an isolated AMD wheel bootstrap, pinned model preparation, audited custom-code patching, single-GPU |
| selection, local-only model resolution during inference, atomic output, bounded PDF handling, diagnostics, and |
| validation evidence. |
|
|
| > Status: beta. Verified on 31 July 2026 with an AMD Radeon RX 9070 XT (`gfx1201`). This is not an AMD or Baidu project. |
|
|
| ## Verified configuration |
|
|
| | Component | Verified value | |
| |---|---| |
| | GPU | AMD Radeon RX 9070 XT, 16 GB | |
| | GPU allocation | One isolated GPU | |
| | OS | Ubuntu 24.04.4 | |
| | Kernel | 6.17.0-40-generic | |
| | Host ROCm | 7.2.1 | |
| | PyTorch | 2.9.1 + ROCm 7.2.1 | |
| | Transformers | 4.57.1 | |
| | Matplotlib | 3.10.8 | |
| | Model revision | `07dea832e22aefee32ad281d4b80551282e1c168` | |
| | Weight precision | Original BF16; no quantization | |
| | Peak allocated VRAM | 8.25 GiB on the 1600×2000 validation page | |
|
|
| The initial validation recovered headings, reading order, a structured table, euro amounts, a formula, and an exact |
| checksum. Repeated greedy generation was byte-identical after deterministic tag cleanup. See |
| [docs/VALIDATION.md](docs/VALIDATION.md) for the evidence and its limits. |
|
|
| ## Quick start |
|
|
| The bootstrap downloads checksum-pinned AMD ROCm wheels into your XDG cache, installs every other runtime/build |
| dependency from `requirements/bootstrap.lock` with hashes required, builds this checkout without build isolation, and |
| creates a repository-local virtual environment. It does not use `sudo`, alter `/opt/rocm`, or touch the system Python. |
|
|
| ```bash |
| git clone https://huggingface.co/dougvk/Unlimited-OCR-RDNA4 |
| cd Unlimited-OCR-RDNA4 |
| |
| ./scripts/bootstrap-rocm.sh |
| .venv/bin/unlimited-ocr-rdna4 prepare |
| .venv/bin/unlimited-ocr-rdna4 run --input page.png |
| ``` |
|
|
| The model download is approximately 6.78 GB. The verified AMD wheel set is approximately 1.9 GB before installation. |
|
|
| PDFs are rendered and parsed page by page: |
|
|
| ```bash |
| .venv/bin/unlimited-ocr-rdna4 run \ |
| --input document.pdf \ |
| --output document.md \ |
| --max-pages 10 \ |
| --dpi 200 |
| ``` |
|
|
| ## Commands |
|
|
| ### `prepare` |
|
|
| Downloads the pinned original checkpoint, fully hashes the 6.67 GB safetensors file and every behavior-defining model, |
| configuration, tokenizer, and index file, preserves Baidu's original model source, and applies a narrowly scoped audited |
| patch. |
|
|
| ```bash |
| unlimited-ocr-rdna4 prepare |
| unlimited-ocr-rdna4 prepare --dry-run --json |
| unlimited-ocr-rdna4 prepare --model-dir /data/models/unlimited-ocr |
| ``` |
|
|
| Preparation is serialized and idempotent. It uses a unique partial directory, validates the exact manifest and file set, |
| and refuses unknown, extra, symlinked, or mismatched files instead of executing them. |
|
|
| ### `doctor` |
|
|
| Reports the active PyTorch/HIP stack, visible devices, RDNA 4 architecture, BF16 capability, and model readiness. |
|
|
| ```bash |
| unlimited-ocr-rdna4 doctor |
| unlimited-ocr-rdna4 doctor --device 0 --require-model |
| unlimited-ocr-rdna4 doctor --json |
| ``` |
|
|
| ### `run` |
|
|
| Parses one image or PDF and publishes untrusted model output atomically. The content may include Markdown and raw HTML; |
| do not render it in a privileged origin without sanitization. |
|
|
| ```bash |
| unlimited-ocr-rdna4 run --input scan.png |
| unlimited-ocr-rdna4 run --input scan.png --output scan.md --device 0 |
| unlimited-ocr-rdna4 run --input report.pdf --start-page 21 --max-pages 10 |
| ``` |
|
|
| Important flags: |
|
|
| | Flag | Default | Meaning | |
| |---|---:|---| |
| | `--device` | `$UNLIMITED_OCR_DEVICE` or `0` | ROCm ordinal or stable ROCr UUID | |
| | `--mode` | `gundam` | `gundam` for detailed single-page parsing; `base` for lower-detail input | |
| | `--max-length` | `4096` | Total input + output sequence limit; maximum `32768` | |
| | `--dpi` | `200` | PDF rendering resolution | |
| | `--max-pages` | `20` | Per-run PDF safety cap | |
| | `--max-page-pixels` | `60000000` | Per-page rendered-pixel cap | |
| | `--max-total-pixels` | `400000000` | Aggregate rendered-pixel cap | |
| | `--max-page-rendered-mib` | `512` | Per-page rendered temporary-byte cap | |
| | `--max-rendered-mib` | `2048` | Aggregate rendered temporary-byte cap | |
| | `--force` | off | Replace an existing output file | |
| | `--json` | off | Stable machine-readable summary on stdout | |
| | `--quiet` | off | Suppress progress diagnostics | |
|
|
| OCR content is written to the output file. Progress and warnings go to stderr. Human or JSON summaries go to stdout. |
|
|
| ## GPU selection |
|
|
| PyTorch uses the CUDA-compatible API name on ROCm. `--device` sets `ROCR_VISIBLE_DEVICES` before PyTorch is imported, so |
| the process sees one logical `cuda:0` backed by the selected AMD card. |
|
|
| For ordinary one-GPU systems: |
|
|
| ```bash |
| unlimited-ocr-rdna4 run --input page.png --device 0 |
| ``` |
|
|
| For multi-GPU systems, a stable ROCr UUID avoids dependence on enumeration order: |
|
|
| ```bash |
| unlimited-ocr-rdna4 run --input page.png --device GPU-0123456789abcdef |
| ``` |
|
|
| Run `unlimited-ocr-rdna4 doctor` before choosing a device. Do not assume another application's GPU numbering matches |
| ROCm's ordinal numbering. |
|
|
| ## What the RDNA 4 adaptation changes |
|
|
| - Pins the Baidu checkpoint and verifies the complete expected local model tree before custom code loads. |
| - Uses AMD's production ROCm 7.2.1 PyTorch, torchvision, and Triton wheels for Python 3.12. |
| - Isolates one `gfx1200`/`gfx1201` GPU before importing PyTorch. |
| - Replaces unsafe `eval()` calls in optional model-output geometry parsing with `ast.literal_eval()`. |
| - Makes one internal mask transfer follow the active tensor device. |
| - Supplies the missing all-ones attention mask and pad token for single-sequence generation. |
| - Loads only the prepared local model during inference and enables Hugging Face offline mode. |
| - Avoids vLLM, SGLang, quantization, tensor parallelism, and unverified custom serving kernels. |
| - Removes only complete, exact layout sentinel pairs without rewriting recognized Unicode or TeX. |
| - Detects obvious terminal repetition and warns without silently rewriting recognition content. |
|
|
| The model weights and mathematical operators are unchanged. PyTorch's ROCm backend provides the RDNA 4 kernels. |
|
|
| ## Configuration |
|
|
| Precedence is flags, then environment variables, then XDG defaults. |
|
|
| | Environment variable | Purpose | |
| |---|---| |
| | `UNLIMITED_OCR_DEVICE` | Default ROCm ordinal or UUID | |
| | `UNLIMITED_OCR_MODEL_DIR` | Prepared model directory | |
| | `XDG_DATA_HOME` | Default model storage root | |
| | `XDG_CACHE_HOME` | Wheel, Hugging Face, and temporary-work cache root | |
| | `NO_COLOR` | Accepted implicitly; the CLI currently emits no color | |
|
|
| This project contains no analytics or telemetry code. |
|
|
| ## Safety and limitations |
|
|
| - The default 4096 sequence limit includes visual-prefill tokens. Dense pages may require a larger value. |
| - PDF mode uses permissively licensed PDFium bindings and renders one bounded page at a time. A failed run leaves no |
| published partial document; retry with `--start-page` to resume manually. |
| - Generative OCR can omit or hallucinate content. Verify consequential documents against the source. |
| - Rotated text and repetitive pages are known upstream weak spots. |
| - Only the configuration above has completed the full repository acceptance test. Newer ROCm/PyTorch versions may work, |
| but `doctor` reports them as unverified until measured. |
| - The hardware guard accepts `gfx1200`, but reports `hardware_verified=false`; only `gfx1201` has completed this GPU gate. |
| - The bootstrap currently supports Linux x86_64, Python 3.12, and host ROCm 7.2.1. |
| |
| See [SECURITY.md](SECURITY.md) before processing untrusted documents. |
| |
| ## Development |
| |
| CPU-only tests do not install PyTorch. The commands below are convenient for development; the release bootstrap is the |
| hash-locked installation path. |
| |
| ```bash |
| python3.12 -m venv .venv-dev |
| .venv-dev/bin/pip install -e '.[dev]' |
| .venv-dev/bin/ruff check . |
| .venv-dev/bin/ruff format --check . |
| .venv-dev/bin/pytest |
| .venv-dev/bin/python -m build |
| .venv-dev/bin/twine check dist/* |
| ``` |
| |
| The GPU smoke gate is intentionally separate. It uses tracked, hash-checked fixtures; parses structured JSON; runs the |
| image twice in fresh processes; and checks image/PDF output hashes, structure, stack identity, revision, VRAM, and process |
| release. On the validated host, run it in a root-created private network namespace: |
| |
| ```bash |
| VALIDATION_NETWORK_ISOLATED=1 \ |
| UNLIMITED_OCR_DEVICE=GPU-0123456789abcdef \ |
| AMD_SMI_GPU=3 \ |
| ./scripts/validate-smoke.sh |
| ``` |
| |
| ## Credits and license |
| |
| - Model and model code: [Baidu Unlimited-OCR](https://github.com/baidu/Unlimited-OCR), MIT licensed. |
| - ROCm evaluation and batching research: [AIwork4me/Unlimited-OCR-ROCm](https://github.com/AIwork4me/Unlimited-OCR-ROCm). |
| - AMD wheel source and compatibility guidance: [ROCm documentation](https://rocm.docs.amd.com/). |
| - PDF rendering: [pypdfium2](https://pypi.org/project/pypdfium2/) and PDFium, under permissive licenses. |
| |
| The runtime is MIT licensed. Baidu's original copyright and license are preserved; see |
| [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). |
| |
