From 33e7b4cc4b92a6aaa96cbc2b305a1fbfc9f755b1 Mon Sep 17 00:00:00 2001 From: Mick Date: Fri, 9 Oct 2026 13:25:23 +0800 Subject: [PATCH] [diffusion] perf: decode plain base64 MiniMax-H3 materials without a per-character loop (#43117) Co-authored-by: Mick Qian Co-authored-by: Claude Opus 5.5 --- .../minimax_h3/material_io.py | 100 +++++++++++++----- .../test/unit/test_minimax_h3_media.py | 82 ++++++++++++++ 2 files changed, 153 insertions(+), 29 deletions(-) diff --git a/python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/material_io.py b/python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/material_io.py index a6ae54f129..cf97ce08cb 100644 --- a/python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/material_io.py +++ b/python/sglang/multimodal_gen/runtime/pipelines_core/stages/model_specific_stages/minimax_h3/material_io.py @@ -14,6 +14,7 @@ from __future__ import annotations import base64 import json import math +import re import shutil import subprocess import tempfile @@ -33,6 +34,9 @@ MINIMAX_H3_TAR_HEADER_MAX_ENCODED_CHARS = 64 * 1024 _BASE64_ALPHABET = frozenset( b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/=_-" ) +# The alphabet, then at most two padding characters. Payloads with percent escapes +# or whitespace, which material URIs may also carry, take the per-character path. +_PLAIN_BASE64_PAYLOAD = re.compile(r"[A-Za-z0-9+/_-]*={0,2}") _DEFAULT_SUFFIX_BY_TYPE = { "image": ".png", @@ -586,6 +590,67 @@ def _decode_base64_chunk(encoded: bytes | bytearray) -> bytes: raise ValueError("material URI has an invalid base64 payload") from exc +def _check_base64_size(encoded_size: int, padding: int) -> None: + if encoded_size == 0: + raise ValueError("material URI base64 payload is empty") + if encoded_size % 4 == 1 or (padding and encoded_size % 4): + raise ValueError("material URI has an invalid base64 payload length") + + +def _write_plain_base64( + uri: str, payload_start: int, output: Any +) -> tuple[int, int, int]: + """Decode a ``_PLAIN_BASE64_PAYLOAD`` payload in the per-character path's windows. + + One interpreter step per window instead of per character: the per-character + loop spent 3.5 s of the HTTP path on a 14.5 MB PNG reference (B300 host). + """ + encoded_size = len(uri) - payload_start + padding = 2 if uri.endswith("==") else int(uri.endswith("=")) + _check_base64_size(encoded_size, padding) + total = 0 + for start in range(payload_start, len(uri), MINIMAX_H3_BASE64_DECODE_CHUNK_CHARS): + chunk = uri[start : start + MINIMAX_H3_BASE64_DECODE_CHUNK_CHARS].encode( + "ascii" + ) + decoded_chunk = _decode_base64_chunk(chunk + b"=" * (-len(chunk) % 4)) + total += len(decoded_chunk) + output.write(decoded_chunk) + return total, encoded_size, padding + + +def _write_escaped_base64( + uri: str, payload_start: int, output: Any +) -> tuple[int, int, int]: + total = 0 + encoded_size = 0 + padding = 0 + saw_padding = False + encoded_chunk = bytearray() + for value in _iter_base64_payload_bytes(uri, payload_start): + encoded_size += 1 + if value == ord("="): + saw_padding = True + padding += 1 + if padding > 2: + raise ValueError("material URI has invalid base64 padding") + elif saw_padding: + raise ValueError("material URI has data after base64 padding") + encoded_chunk.append(value) + if len(encoded_chunk) == MINIMAX_H3_BASE64_DECODE_CHUNK_CHARS: + decoded_chunk = _decode_base64_chunk(encoded_chunk) + total += len(decoded_chunk) + output.write(decoded_chunk) + encoded_chunk.clear() + _check_base64_size(encoded_size, padding) + if encoded_chunk: + encoded_chunk.extend(b"=" * (-len(encoded_chunk) % 4)) + decoded_chunk = _decode_base64_chunk(encoded_chunk) + total += len(decoded_chunk) + output.write(decoded_chunk) + return total, encoded_size, padding + + def _stream_base64_material( batch: Any, uri: str, @@ -601,37 +666,14 @@ def _stream_base64_material( condition_index=condition_index, media_type=media_type, ) - total = 0 - encoded_size = 0 - padding = 0 - saw_padding = False - encoded_chunk = bytearray() + write_payload = ( + _write_plain_base64 + if _PLAIN_BASE64_PAYLOAD.fullmatch(uri, payload_start) + else _write_escaped_base64 + ) try: with partial_path.open("wb") as output: - for value in _iter_base64_payload_bytes(uri, payload_start): - encoded_size += 1 - if value == ord("="): - saw_padding = True - padding += 1 - if padding > 2: - raise ValueError("material URI has invalid base64 padding") - elif saw_padding: - raise ValueError("material URI has data after base64 padding") - encoded_chunk.append(value) - if len(encoded_chunk) == MINIMAX_H3_BASE64_DECODE_CHUNK_CHARS: - decoded_chunk = _decode_base64_chunk(encoded_chunk) - total += len(decoded_chunk) - output.write(decoded_chunk) - encoded_chunk.clear() - if encoded_size == 0: - raise ValueError("material URI base64 payload is empty") - if encoded_size % 4 == 1 or (padding and encoded_size % 4): - raise ValueError("material URI has an invalid base64 payload length") - if encoded_chunk: - encoded_chunk.extend(b"=" * (-len(encoded_chunk) % 4)) - decoded_chunk = _decode_base64_chunk(encoded_chunk) - total += len(decoded_chunk) - output.write(decoded_chunk) + total, encoded_size, padding = write_payload(uri, payload_start, output) decoded_size = (encoded_size * 3) // 4 - padding if decoded_size <= 0: raise ValueError("material URI decoded payload is empty") diff --git a/python/sglang/multimodal_gen/test/unit/test_minimax_h3_media.py b/python/sglang/multimodal_gen/test/unit/test_minimax_h3_media.py index 48862032ca..8af0bc3af4 100644 --- a/python/sglang/multimodal_gen/test/unit/test_minimax_h3_media.py +++ b/python/sglang/multimodal_gen/test/unit/test_minimax_h3_media.py @@ -1,10 +1,13 @@ # SPDX-License-Identifier: Apache-2.0 """Numerical boundaries for the one-pass Ref2VA media path.""" +import base64 +import io import json import os import subprocess import sys +from pathlib import Path from types import SimpleNamespace import numpy as np @@ -306,3 +309,82 @@ def test_reference_audio_encode_sets_forward_context(monkeypatch): assert result["rows"].shape == (8, 32) assert result["ref_audio_t"] == 4 + + +def _decode_base64_payload(write, uri): + output = io.BytesIO() + result = write(uri, uri.index(",") + 1, output) + return output.getvalue(), result + + +@pytest.mark.parametrize("size", [1, 2, 3, 11, 12, 13, 47, 48, 49]) +@pytest.mark.parametrize("alphabet", ["standard", "urlsafe", "unpadded"]) +def test_plain_base64_material_matches_per_character_path(monkeypatch, size, alphabet): + # 16-character windows, so every size crosses window boundaries. + monkeypatch.setattr(material_io, "MINIMAX_H3_BASE64_DECODE_CHUNK_CHARS", 16) + data = np.random.default_rng(size).integers(0, 256, size, dtype=np.uint8).tobytes() + encode = base64.urlsafe_b64encode if alphabet == "urlsafe" else base64.b64encode + payload = encode(data).decode() + if alphabet == "unpadded": + payload = payload.rstrip("=") + uri = "data:image/png;base64," + payload + + assert material_io._PLAIN_BASE64_PAYLOAD.fullmatch(uri, uri.index(",") + 1) + plain = _decode_base64_payload(material_io._write_plain_base64, uri) + assert plain == _decode_base64_payload(material_io._write_escaped_base64, uri) + assert plain[0] == data + + +@pytest.mark.parametrize( + "payload, message", + [ + ("", "payload is empty"), + ("A", "invalid base64 payload length"), + ("QQ=", "invalid base64 payload length"), + ("QQ===", "invalid base64 padding"), + ("QQ==QQ==", "data after base64 padding"), + ("QU*D", "invalid base64 character"), + ], +) +def test_base64_material_rejects_invalid_payloads( + tmp_path, monkeypatch, payload, message +): + monkeypatch.setattr(material_io.tempfile, "mkdtemp", lambda prefix: str(tmp_path)) + with pytest.raises(ValueError, match=message): + material_io._stream_base64_material( + SimpleNamespace(extra={}), + "data:image/png;base64," + payload, + condition_type="image", + condition_index=0, + ) + assert list(tmp_path.iterdir()) == [] + + +def test_base64_material_decodes_escapes_and_whitespace(tmp_path, monkeypatch): + monkeypatch.setattr(material_io.tempfile, "mkdtemp", lambda prefix: str(tmp_path)) + data = bytes(range(256)) * 4 + payload = base64.b64encode(data).decode() + escaped = f"%{ord(payload[0]):02X}" + payload[1:20] + "\n " + payload[20:] + path = material_io._stream_base64_material( + SimpleNamespace(extra={}), + "data:image/png;base64," + escaped, + condition_type="image", + condition_index=0, + ) + assert Path(path).read_bytes() == data + + +def test_plain_base64_material_skips_the_per_character_loop(tmp_path, monkeypatch): + def per_character(*_args): + raise AssertionError("a plain base64 payload took the per-character path") + + monkeypatch.setattr(material_io.tempfile, "mkdtemp", lambda prefix: str(tmp_path)) + monkeypatch.setattr(material_io, "_iter_base64_payload_bytes", per_character) + data = np.random.default_rng(0).integers(0, 256, 3 << 20, dtype=np.uint8).tobytes() + path = material_io._stream_base64_material( + SimpleNamespace(extra={}), + "data:image/png;base64," + base64.b64encode(data).decode(), + condition_type="image", + condition_index=0, + ) + assert Path(path).read_bytes() == data