[diffusion] perf: decode plain base64 MiniMax-H3 materials without a per-character loop (#43117)

Co-authored-by: Mick Qian <mickqian@users.noreply.github.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Mick
2026-10-09 13:25:23 +08:00
committed by GitHub
co-authored by Mick Qian Claude Opus 5.5
parent 5d8e98b7fd
commit 33e7b4cc4b
2 changed files with 153 additions and 29 deletions
@@ -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")
@@ -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