perf(minimax-h3): reduce native runtime overhead

[yifeif-nv]

Background

Reduce native MiniMax H3 runtime overhead while preserving the unified T2VA, FL2VA, and Ref2VA delivery in #1240, including explicit fixed-base super resolution and dynamic prompt/duration support. This draft is based on that PR's 19e37595033d802c7dedfed77f2a8f42b1d4a992 baseline.

Exit Criteria

• Preserve engine payloads, checkpoints, precision, attention mathematics, sampling, and public dynamic ranges.
• Reduce measured loading/allocation overhead without an obvious visual regression at matched settings.
• Complete the normal/SR, three-mode, short/long measurement matrix and publish reproducible commands, cache conditions, and quality limitations before marking ready.

Implementation

• Opt the family's serial text/vision engines into existing user-managed activation storage.
• Size internally owned dynamic I/O from live request shapes, reuse high-water allocations, and invalidate activation requirements when shapes change. Preserve external bindings, aliasing, and graph behavior.
• Size the four family-owned FirstBlockCache tensors to validated live request rows, retaining profile-MAX ABI checks and guarding reuse/binding capacity. Keep auxiliary storage and stage-release policies unchanged.
• Read Windows plan sections in bounded large blocks through the existing read-only, mutation-protected handle. Preserve Linux reading behavior and expose nested load-phase timing.
• Add a family-owned native C++ resident benchmark using the public video API and existing Windows media I/O. It records ordered requests and timing boundaries without adding a Python runtime or a second model workflow.

Validation

Measured runtime source: aa594f6010bd59204c2edc3061fc6e5042572c0d. Documentation-only follow-up: 2d8d27edd8945f0cc01c894f705c553cde9e928c (results-first Markdown report and Quick Start).

• Native RTX-only Release compilation passed. ctest --test-dir <build> --output-on-failure -R "^(minimax_h3_(math|conditioning|fl2va_runtime|ref2va_runtime)|bundle_format_v1|task_api|cli|family_loader|dynamic_library|runtime_cache_persistence|windows_utf8_argv|windows_media|dataset_answer|benchmark_worker_e2e)$": 14/14 passed, including live-cache capacity and profile-bound cases.
• On the preceding 4dcfdc79 revision, <build>/test_trt_module_dynamic_input.exe passed owned/external I/O transitions and two real RTX contexts sharing/growing an activation arena. These generic tests were not rerun on the current revision; shared runtime code is unchanged by the latest family-only commit.
• h3_benchmark_video requests.json --validate-only: passed. The same nine-request manifest also completed native generation in one process/task, covering repeated/different/1662-token prompts, T2VA/FL2VA/REF2VA transitions and changed/restored references. All nine outputs passed full decode and sampled scene checks; the report distinguishes API/request/process timing.
• All twelve primary configurations completed: normal/SR x T2VA, FL2VA and Ref2VA at 124/345 output frames, 24 fps and 32 kHz stereo audio. Full decode, finite-audio checks and sampled visual inspection completed without obvious sampled garbling or scene replacement. Outputs are not generally pixel-identical; fine details and framing/progression can differ. The report identifies each quality reference and its limitations. Full-motion/listening qualification is not claimed.
• python tools/legal_headers.py --check: zero findings on the measured runtime revision. git diff --check 19e37595...HEAD and staged documentation whitespace checks passed. python -m tools.model_ci validate passed and model-support inventory tests passed (7 tests); The current Markdown report's ten PowerShell blocks parsed successfully, and all twelve CLI argument combinations passed a CPU-only argument-expansion check. No additional generation runs were performed for this documentation revision. Full website build was not run because website dependencies were not installed.

Single-observation, unprofiled fresh-process E2E seconds with copied seeded RTX caches and both FBC thresholds 0.3 (124 output frames):

Delivery	T2VA	FL2VA	Ref2VA
Native 1344x768	570.797	601.877	960.365
SR 864x480 -> 1296x720	218.031	219.617	472.491

Completed long cases (345 output frames): native T2VA 2819.268 s, FL2VA 3042.447 s and Ref2VA 4940.005 s; SR T2VA 742.129 s, FL2VA 697.108 s and Ref2VA 1750.920 s. Short T2VA empty-RTX-cache-path checks completed at 580.089 s native and 242.461 s SR; these are not OS/driver-cold measurements.

The Markdown report and Quick Start starts with the six configuration rows, both frame-count timings, and native CLI commands. The Quick Start below includes clean Windows installation, bundle builds, input preparation, and the seeded-cache timing protocol. Dynamic-input and quality boundaries remain explicit. It links the C++ guide and frozen detailed protocol for exact fixtures, cache preparation, stage timings and evidence. Original authorized-recipient fixtures are supplied separately, not publicly uploaded.

These are measured configuration results, not a general speedup or arbitrary-hardware latency guarantee. Full-motion/listening qualification and additional matched-baseline coverage remain incomplete. Long native Ref2VA was compared directly for quality against the intermediate bulk runtime (PSNR 24.978547 dB / SSIM 0.823267), with scene content retained but detail and framing differences. That older run overlapped CPU compilation and is not a controlled timing baseline. No current-head remote premerge pass or cross-platform qualification is claimed.

Notes For Future Readers

This is stacked on #1240; the main-targeted diff includes that baseline until it lands. For the performance increment, review 19e37595..aa594f60. The baseline branch and PR are unchanged. Review generic allocation/file-reading mechanics first, then the H3 serial policy, request-sized caches and family-owned benchmark.

The measurements use the same bundles with both FBC thresholds at 0.3; product defaults remain unchanged. FBC and SR are not claimed to be equivalent to an uncached native-resolution reference. Profiled timing is diagnostic and will not be mixed with ordinary process wall time.

No checkpoints, engines, generated media, raw traces, local logs, machine paths, or hardware identifiers are included. Public C++ API declarations are unchanged by the performance increment; rebuild the matching backend/runtime together. The selected measurement matrix and report are complete; keep this PR Draft pending review of the recorded quality limitations and current-head validation.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

_{Comment @coderabbitai help to get the list of available commands.}