feat: support HunyuanOCR 1.5

[GreatV]

Summary

• detect HunyuanOCR 1.5 checkpoints while retaining archived 1.0 compatibility
• align 1.5 prompt construction, repetition penalty, 4K preprocessing, and positional interpolation with the reference implementation
• fix positional-embedding loading for the 65,536-token vision config and document the new model layout

Why

HunyuanOCR 1.5 keeps the same backbone tensor shapes as 1.0 but changes its config schema, prompt template, image budget, interpolation behavior, and vision sequence limit. Treating the root checkpoint as 1.0 attempts to load 65,537 positional rows from a checkpoint that retains the 16,385-row learned base grid.

Impact

HunyuanOcr::from_dir now loads HunyuanOCR 1.5 directly from the model repository root. Existing 1.0 directories continue to work and the detected generation is exposed through HunyuanOcr::version().

Validation

• cargo test -p oar-ocr-vl --features download-binaries --lib (93 passed)
• cargo clippy -p oar-ocr-vl --features download-binaries --lib --examples -- -D warnings
• cargo check -p oar-ocr-vl --features cuda,download-binaries
• CUDA inference with /home/greatx/repos/tencent/HunyuanOCR on text-line and full-page fixtures
• CUDA regression inference with archived /home/greatx/repos/tencent/HunyuanOCR/v1.0

[gemini-code-assist]

Code Review

This pull request adds support for HunyuanOCR 1.5 while maintaining backward compatibility with version 1.0. Key changes include automatic version detection via the configuration file, updated image preprocessing budgets (supporting up to 4K square inputs for 1.5), version-specific prompt formatting, and adjusted interpolation scaling for vision positional embeddings. The review feedback suggests making the version detection more robust by verifying that "text_config" is a valid JSON object rather than just checking "is_some()", and using checked arithmetic when calculating "num_positions" to prevent potential overflow panics.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[Copilot]

Pull request overview

Adds first-class support for the HunyuanOCR 1.5 checkpoint layout and behavior while retaining compatibility with the archived 1.0 layout. The loader now detects the checkpoint generation from config.json, adapts prompt/image preprocessing + positional interpolation accordingly, and exposes the detected version to callers.

Changes:

• Introduce HunyuanOcrVersion and auto-detect 1.5 vs 1.0 via config schema (text_config presence).
• Align version-specific behavior: prompt template differences, repetition penalty fallback, 4K preprocessing budget, and positional interpolation semantics.
• Update public exports, examples, and documentation to reflect the new default layout (1.5 at repo root, 1.0 under v1.0/).

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
oar-ocr-vl/src/lib.rs	Re-export HunyuanOcrVersion and update module docs to reflect 1.5/1.0 support.
oar-ocr-vl/src/hunyuanocr/config.rs	Add HunyuanOcrVersion + version detection via text_config.
oar-ocr-vl/src/hunyuanocr/mod.rs	Export HunyuanOcrVersion and update module-level docs for the new layout.
oar-ocr-vl/src/hunyuanocr/model.rs	Thread version through model load/inference, adjust prompt construction and repetition penalty defaults, expose version().
oar-ocr-vl/src/hunyuanocr/processing.rs	Make image preprocessing version-aware (v1 clamps to base grid; v1.5 uses pixel-budget smart-resize).
oar-ocr-vl/src/hunyuanocr/vision.rs	Fix positional embedding sizing/loading for 1.5’s 65,536-token config by interpolating from the learned base grid; version-specific interpolation scaling.
oar-ocr-vl/examples/hunyuanocr.rs	Log detected HunyuanOCR version and update example descriptions.
oar-ocr-vl/README.md	Document that 1.5 is at repo root and 1.0 remains supported under v1.0/.
docs/usage.md	Update usage docs to describe 1.5 defaults, 4K pixel budget, and archived 1.0 path.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.