Fix PP-DocLayoutV3 head aliasing in layout loader

[VooDisss]

Summary

Fixes #179

• fix PP-DocLayoutV3 checkpoint loading in GLM-OCR by aliasing tied enc_* detection-head weights to the decoder head names expected by PPDocLayoutV3ForObjectDetection
• load the layout model from a prepared state dict so transformers no longer initializes missing decoder detection heads
• replace deprecated PPDocLayoutV3ImageProcessorFast usage with PPDocLayoutV3ImageProcessor
• add focused unit coverage for the aliasing logic and update detector startup mocks for the new load path and processor rename

Why

The published PaddlePaddle/PP-DocLayoutV3_safetensors checkpoint stores trained detection-head weights under:

• model.enc_score_head.*
• model.enc_bbox_head.layers.*

but the object-detection wrapper used by GLM-OCR expects:

• model.decoder.class_embed.*
• model.decoder.bbox_embed.layers.*

Without aliasing those keys before model load, the decoder detection heads are treated as missing and newly initialized, which degrades layout detection in practice.

The runtime also still used the deprecated PPDocLayoutV3ImageProcessorFast entry point, which produced a warning on every worker startup under transformers 5.4.0.

Validation

• pytest glmocr/tests/test_unit.py -k "detector_device_selection or detector_prepares_pp_doclayout_decoder_head_aliases"
• real self-hosted OCR pipeline run on local PDFs with successful processing after the fix

Scope

This PR intentionally keeps the fix narrow:

• no meta-tensor recovery logic
• no broader layout runtime refactor
• no broader processor refactor beyond replacing the deprecated entry point used by the detector

Those can be handled separately if needed.

[VooDisss]

@JaredforReal note that my PRs are stacked and not based directly on main:

• Add printed page number metadata to SDK JSON output #171
• Add optional SDK image asset export for rendered and embedded PDF images #174
• Fix PP-DocLayoutV3 head aliasing in layout loader #180

For #180 specifically, I spent some time ruling out user/config error vs an actual GLM-OCR integration issue.

What I found is that under the current transformers 5.x PP-DocLayoutV3 load path, the layout detector comes up with missing decoder detection-head weights and then fails during startup/device move. In practice this showed up when running the self-hosted OCR pipeline with multi-worker layout initialization.

Minimal symptom:

PPDocLayoutV3ForObjectDetection LOAD REPORT
model.decoder.bbox_embed.layers.{0,1,2}.bias   | MISSING
model.decoder.bbox_embed.layers.{0,1,2}.weight | MISSING
model.decoder.class_embed.weight               | MISSING
model.decoder.class_embed.bias                 | MISSING

NotImplementedError: Cannot copy out of meta tensor; no data!
Please use torch.nn.Module.to_empty() instead of torch.nn.Module.to()
when moving module from meta to a different device.

After digging into the checkpoint and local transformers implementation, the issue appears to be a checkpoint/load-path mismatch rather than simple user error:

• the published PaddlePaddle/PP-DocLayoutV3_safetensors checkpoint stores the tied prediction head weights under enc_* names
• PPDocLayoutV3ForObjectDetection expects the corresponding decoder.* names at load time
• without aliasing those keys before model construction, the decoder detection heads are treated as missing and newly initialized

That is what #180 fixes:

• alias enc_score_head.* -> decoder.class_embed.*
• alias enc_bbox_head.layers.* -> decoder.bbox_embed.layers.*
• construct the model from the prepared state dict
• also switch from the deprecated PPDocLayoutV3ImageProcessorFast entry point to PPDocLayoutV3ImageProcessor

I opened the upstream issue with the evidence here:

• PP-DocLayoutV3 checkpoint/load-path mismatch under transformers 5.4.0 #179

So from my side this does not look like just a local environment mistake; it looks like a real PP-DocLayoutV3 HF checkpoint/load-path compatibility bug that GLM-OCR needs to bridge explicitly.