"""Load the dflow_2b denoiser and text adapter weights from a release directory. A release directory holds ``model.safetensors`` (every weight, public names, see ``precision``), ``config.json`` (architecture constants) and ``release.json`` (version and counts). Loading checks, before any weight reaches a module: the config against this package's architecture, the version, the tensor and parameter counts, every name (none missing, none extra), every shape and every storage dtype. The denoiser then loads with ``strict=True``. Public names: ``denoiser.`` for the denoiser (``DFlowModel``'s own ``state_dict`` names, e.g. ``denoiser.prefix_layers.0.attn.qkv.weight``) and ``text_adapter.`` for the text adapter (its keys come from the text adapter module, ``text_conditioning.TEXT_ADAPTER_KEY_MAP``). """ from __future__ import annotations import json from pathlib import Path import torch from safetensors.torch import load_file from torch import Tensor from .configuration import DFLOW_2B_CONFIG, DFlowConfig, read_denoiser_config from .modeling import DFlowModel from .precision import ( DENOISER_PREFIX, TEXT_ADAPTER_PREFIX, StoredDType, denoiser_storage_dtype, text_adapter_storage_dtypes, ) from .version import MODEL_VERSION MODEL_FILENAME = "model.safetensors" CONFIG_FILENAME = "config.json" RELEASE_FILENAME = "release.json" def expected_denoiser_shapes(config: DFlowConfig) -> dict[str, tuple[int, ...]]: """Public name -> shape of every denoiser tensor of ``config``.""" with torch.device("meta"): model = DFlowModel(config) return { DENOISER_PREFIX + name: tuple(tensor.shape) for name, tensor in model.state_dict().items() } def expected_storage(config: DFlowConfig) -> dict[str, StoredDType]: """Public name -> storage dtype of every tensor in ``model.safetensors``.""" storage = { name: denoiser_storage_dtype(name) for name in expected_denoiser_shapes(config) } storage.update(text_adapter_storage_dtypes()) return storage def validate_public_tensors(tensors: dict[str, Tensor], config: DFlowConfig) -> None: """Check names, denoiser shapes and storage dtypes of a public weight file. Raises: ValueError: If a name is missing or unexpected, a denoiser shape differs from ``config``'s, or a dtype differs from the policy. """ storage = expected_storage(config) missing = sorted(set(storage) - set(tensors)) unexpected = sorted(set(tensors) - set(storage)) if missing or unexpected: raise ValueError( f"{MODEL_FILENAME} does not match this package: missing={missing}, " f"unexpected={unexpected}" ) for name, shape in expected_denoiser_shapes(config).items(): if tuple(tensors[name].shape) != shape: raise ValueError( f"{name} has shape {tuple(tensors[name].shape)}; expected {shape}" ) for name, stored in storage.items(): if tensors[name].dtype != stored.torch_dtype: raise ValueError( f"{name} is stored as {tensors[name].dtype}; the storage policy " f"requires {stored.torch_dtype}" ) def _validate_release_metadata(path: Path, tensors: dict[str, Tensor]) -> None: """Check ``release.json``'s version and counts against the weight file. Raises: FileNotFoundError: If ``release.json`` is missing. ValueError: If the version or a count differs. """ if not path.is_file(): raise FileNotFoundError(f"Missing release metadata: {path}") match json.loads(path.read_text(encoding="utf-8")): case { "version": str() as version, "tensor_count": int() as tensor_count, "parameter_count": int() as parameter_count, }: pass case _: raise ValueError( f"{path} must hold version, tensor_count and parameter_count" ) if version != MODEL_VERSION: raise ValueError( f"{path} is release {version}; this package loads {MODEL_VERSION}" ) found_parameters = sum(tensor.numel() for tensor in tensors.values()) if (tensor_count, parameter_count) != (len(tensors), found_parameters): raise ValueError( f"{MODEL_FILENAME} holds {len(tensors)} tensors and {found_parameters} " f"parameters; {RELEASE_FILENAME} declares {tensor_count} and " f"{parameter_count}" ) def read_release_tensors(directory: Path, config: DFlowConfig) -> dict[str, Tensor]: """Read and validate every tensor of a release directory (on the CPU). Raises: FileNotFoundError: If a release file is missing. ValueError: If the config, metadata or tensors do not match. """ read_denoiser_config(directory / CONFIG_FILENAME, config) weights = directory / MODEL_FILENAME if not weights.is_file(): raise FileNotFoundError(f"Missing weights: {weights}") tensors = load_file(weights, device="cpu") _validate_release_metadata(directory / RELEASE_FILENAME, tensors) validate_public_tensors(tensors, config) return tensors def _with_prefix(tensors: dict[str, Tensor], prefix: str) -> dict[str, Tensor]: """The entries of ``tensors`` under ``prefix``, with the prefix removed.""" return { name.removeprefix(prefix): tensor for name, tensor in tensors.items() if name.startswith(prefix) } def load_dflow_denoiser( directory: Path, *, device: torch.device, compile_model: bool, config: DFlowConfig = DFLOW_2B_CONFIG, ) -> DFlowModel: """Build the denoiser and load a release directory's weights. Weights keep their storage dtypes on the device (bfloat16 with FP32 islands). With ``compile_model`` every block is compiled (``DFlowModel.compile_blocks(dynamic=True)``); graphs build on first use. Args: directory: Release directory (``model.safetensors``, ``config.json``, ``release.json``). device: CUDA device for the model. compile_model: Compile the blocks, or run eagerly. config: The architecture to expect (the released model's by default). Returns: The eval-mode denoiser without gradients. Raises: FileNotFoundError: If a release file is missing. ValueError: If ``device`` is not CUDA or the release does not match. """ if device.type != "cuda": raise ValueError(f"dflow runs on CUDA (bfloat16 autocast), got {device}") tensors = read_release_tensors(directory, config) with torch.device("meta"): model = DFlowModel(config) model.load_state_dict( _with_prefix(tensors, DENOISER_PREFIX), strict=True, assign=True ) model.to(device=device) model.eval() model.requires_grad_(False) if compile_model: model.compile_blocks(dynamic=True) return model def load_text_adapter_tensors( directory: Path, *, config: DFlowConfig = DFLOW_2B_CONFIG ) -> dict[str, Tensor]: """The text adapter's validated tensors, keyed relative to the adapter module (the ``text_adapter.`` prefix removed), on the CPU. Raises: FileNotFoundError: If a release file is missing. ValueError: If the release does not match. """ return _with_prefix(read_release_tensors(directory, config), TEXT_ADAPTER_PREFIX)