dflow_2b / dflow /loading.py
data-archetype's picture
dflow_2b 0.2
6daffc2
Raw History Blame Contribute Delete
7.46 kB
"""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.<module path>`` for the denoiser (``DFlowModel``'s
own ``state_dict`` names, e.g. ``denoiser.prefix_layers.0.attn.qkv.weight``)
and ``text_adapter.<key>`` 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)