[LoRA] feat: support loading regular Flux LoRAs into Flux Control, and Fill

docs/source/en/api/pipelines/flux.md

@@ -268,6 +268,43 @@ images = pipe(
 images[0].save("flux-redux.png")
 ```
 
+## Combining Flux Turbo LoRAs with Flux Control, Fill, and Redux
+
+We can combine Flux Turbo LoRAs with Flux Control and other pipelines like Fill and Redux to enable few-steps' inference. The example below shows how to do that for Flux Control LoRA for depth and turbo LoRA from [`ByteDance/Hyper-SD`](https://hf.co/ByteDance/Hyper-SD).
+
+```py
+from diffusers import FluxControlPipeline
+from image_gen_aux import DepthPreprocessor
+from diffusers.utils import load_image
+from huggingface_hub import hf_hub_download
+import torch
+
+control_pipe = FluxControlPipeline.from_pretrained("black-forest-labs/FLUX.1-dev", torch_dtype=torch.bfloat16)
+control_pipe.load_lora_weights("black-forest-labs/FLUX.1-Depth-dev-lora", adapter_name="depth")
+control_pipe.load_lora_weights(
+ hf_hub_download("ByteDance/Hyper-SD", "Hyper-FLUX.1-dev-8steps-lora.safetensors"), adapter_name="hyper-sd"
+)
+control_pipe.set_adapters(["depth", "hyper-sd"], adapter_weights=[0.85, 0.125])
+control_pipe.enable_model_cpu_offload()
+
+prompt = "A robot made of exotic candies and chocolates of different kinds. The background is filled with confetti and celebratory gifts."
+control_image = load_image("https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/robot.png")
+
+processor = DepthPreprocessor.from_pretrained("LiheYoung/depth-anything-large-hf")
+control_image = processor(control_image)[0].convert("RGB")
+
+image = control_pipe(
+ prompt=prompt,
+ control_image=control_image,
+ height=1024,
+ width=1024,
+ num_inference_steps=8,
+ guidance_scale=10.0,
+ generator=torch.Generator().manual_seed(42),
+).images[0]
+image.save("output.png")
+```
+
 ## Running FP16 inference
 
 Flux can generate high-quality images with FP16 (i.e. to accelerate inference on Turing/Volta GPUs) but produces different outputs compared to FP32/BF16. The issue is that some activations in the text encoders have to be clipped when running in FP16, which affects the overall image. Forcing text encoders to run with FP32 inference thus removes this output difference. See [here](https://github.com/huggingface/diffusers/pull/9097#issuecomment-2272292516) for details.

src/diffusers/loaders/lora_pipeline.py

@@ -1863,6 +1863,9 @@ def load_lora_weights(
  "As a result, the state_dict of the transformer has been expanded to match the LoRA parameter shapes. "
  "To get a comprehensive list of parameter names that were modified, enable debug logging."
  )
+ transformer_lora_state_dict = self._maybe_expand_lora_state_dict(
+ transformer=transformer, lora_state_dict=transformer_lora_state_dict
+ )
 
  if len(transformer_lora_state_dict) > 0:
  self.load_lora_into_transformer(
@@ -2309,16 +2312,17 @@ def _maybe_expand_transformer_param_shape_or_error_(
 
  # Expand transformer parameter shapes if they don't match lora
  has_param_with_shape_update = False
-
+ is_peft_loaded = getattr(transformer, "peft_config", None) is not None
  for name, module in transformer.named_modules():
  if isinstance(module, torch.nn.Linear):
  module_weight = module.weight.data
  module_bias = module.bias.data if module.bias is not None else None
  bias = module_bias is not None
 
- lora_A_weight_name = f"{name}.lora_A.weight"
- lora_B_weight_name = f"{name}.lora_B.weight"
- if lora_A_weight_name not in state_dict.keys():
+ lora_base_name = name.replace(".base_layer", "") if is_peft_loaded else name
+ lora_A_weight_name = f"{lora_base_name}.lora_A.weight"
+ lora_B_weight_name = f"{lora_base_name}.lora_B.weight"
+ if lora_A_weight_name not in state_dict:
  continue
 
  in_features = state_dict[lora_A_weight_name].shape[1]
@@ -2329,56 +2333,105 @@ def _maybe_expand_transformer_param_shape_or_error_(
  continue
 
  module_out_features, module_in_features = module_weight.shape
-if out_features < module_out_features or in_features < module_in_features:
- raise NotImplementedError(
- f"Only LoRAs with input/output features higher than the current module's input/output features "
- f"are currently supported. The provided LoRA contains {in_features=} and {out_features=}, which "
- f"are lower than {module_in_features=} and {module_out_features=}. If you require support for "
- f"this please open an issue at https://github.com/huggingface/diffusers/issues."
+debug_message = ""
+if in_features > module_in_features:
+debug_message += (
+ f'Expanding the nn.Linear input/output features for module="{name}" because the provided LoRA '
+ f"checkpoint contains higher number of features than expected. The number of input_features will be "
+ f"expanded from {module_in_features} to {in_features}"
  )
-
- debug_message = (
- f'Expanding the nn.Linear input/output features for module="{name}" because the provided LoRA '
- f"checkpoint contains higher number of features than expected. The number of input_features will be "
- f"expanded from {module_in_features} to {in_features}"
- )
- if module_out_features != out_features:
+ if out_features > module_out_features:
  debug_message += (
  ", and the number of output features will be "
  f"expanded from {module_out_features} to {out_features}."
  )
  else:
  debug_message += "."
- logger.debug(debug_message)
+ if debug_message:
+ logger.debug(debug_message)
+
+ if out_features > module_out_features or in_features > module_in_features:
+ has_param_with_shape_update = True
+ parent_module_name, _, current_module_name = name.rpartition(".")
+ parent_module = transformer.get_submodule(parent_module_name)
+
+ with torch.device("meta"):
+ expanded_module = torch.nn.Linear(
+ in_features, out_features, bias=bias, dtype=module_weight.dtype
+ )
+ # Only weights are expanded and biases are not. This is because only the input dimensions
+ # are changed while the output dimensions remain the same. The shape of the weight tensor
+ # is (out_features, in_features), while the shape of bias tensor is (out_features,), which
+ # explains the reason why only weights are expanded.
+ new_weight = torch.zeros_like(
+ expanded_module.weight.data, device=module_weight.device, dtype=module_weight.dtype
+ )
+ slices = tuple(slice(0, dim) for dim in module_weight.shape)
+ new_weight[slices] = module_weight
+ tmp_state_dict = {"weight": new_weight}
+ if module_bias is not None:
+ tmp_state_dict["bias"] = module_bias
+ expanded_module.load_state_dict(tmp_state_dict, strict=True, assign=True)
+
+ setattr(parent_module, current_module_name, expanded_module)
+
+ del tmp_state_dict
+
+ if current_module_name in _MODULE_NAME_TO_ATTRIBUTE_MAP_FLUX:
+ attribute_name = _MODULE_NAME_TO_ATTRIBUTE_MAP_FLUX[current_module_name]
+ new_value = int(expanded_module.weight.data.shape[1])
+ old_value = getattr(transformer.config, attribute_name)
+ setattr(transformer.config, attribute_name, new_value)
+ logger.info(
+ f"Set the {attribute_name} attribute of the model to {new_value} from {old_value}."
+ )
 
- has_param_with_shape_update = True
- parent_module_name, _, current_module_name = name.rpartition(".")
- parent_module = transformer.get_submodule(parent_module_name)
+ return has_param_with_shape_update
 
- # TODO: consider initializing this under meta device for optims.
- expanded_module = torch.nn.Linear(
- in_features, out_features, bias=bias, device=module_weight.device, dtype=module_weight.dtype
- )
- # Only weights are expanded and biases are not.
- new_weight = torch.zeros_like(
- expanded_module.weight.data, device=module_weight.device, dtype=module_weight.dtype
+ @classmethod
+ def _maybe_expand_lora_state_dict(cls, transformer, lora_state_dict):
+ expanded_module_names = set()
+ transformer_state_dict = transformer.state_dict()
+ prefix = f"{cls.transformer_name}."
+
+ lora_module_names = [
+ key[: -len(".lora_A.weight")] for key in lora_state_dict if key.endswith(".lora_A.weight")
+ ]
+ lora_module_names = [name[len(prefix) :] for name in lora_module_names if name.startswith(prefix)]
+ lora_module_names = sorted(set(lora_module_names))
+ transformer_module_names = sorted({name for name, _ in transformer.named_modules()})
+ unexpected_modules = set(lora_module_names) - set(transformer_module_names)
+ if unexpected_modules:
+ logger.debug(f"Found unexpected modules: {unexpected_modules}. These will be ignored.")
+
+ is_peft_loaded = getattr(transformer, "peft_config", None) is not None
+ for k in lora_module_names:
+ if k in unexpected_modules:
+ continue
+
+ base_param_name = (
+ f"{k.replace(prefix, '')}.base_layer.weight" if is_peft_loaded else f"{k.replace(prefix, '')}.weight"
+ )
+ base_weight_param = transformer_state_dict[base_param_name]
+ lora_A_param = lora_state_dict[f"{prefix}{k}.lora_A.weight"]
+
+ if base_weight_param.shape[1] > lora_A_param.shape[1]:
+ shape = (lora_A_param.shape[0], base_weight_param.shape[1])
+ expanded_state_dict_weight = torch.zeros(shape, device=base_weight_param.device)
+ expanded_state_dict_weight[:, : lora_A_param.shape[1]].copy_(lora_A_param)
+ lora_state_dict[f"{prefix}{k}.lora_A.weight"] = expanded_state_dict_weight
+ expanded_module_names.add(k)
+ elif base_weight_param.shape[1] < lora_A_param.shape[1]:
+ raise NotImplementedError(
+ f"This LoRA param ({k}.lora_A.weight) has an incompatible shape {lora_A_param.shape}. Please open an issue to file for a feature request - https://github.com/huggingface/diffusers/issues/new."
  )
- slices = tuple(slice(0, dim) for dim in module_weight.shape)
- new_weight[slices] = module_weight
- expanded_module.weight.data.copy_(new_weight)
- if module_bias is not None:
- expanded_module.bias.data.copy_(module_bias)
-
- setattr(parent_module, current_module_name, expanded_module)
 
- if current_module_name in _MODULE_NAME_TO_ATTRIBUTE_MAP_FLUX:
- attribute_name = _MODULE_NAME_TO_ATTRIBUTE_MAP_FLUX[current_module_name]
- new_value = int(expanded_module.weight.data.shape[1])
- old_value = getattr(transformer.config, attribute_name)
- setattr(transformer.config, attribute_name, new_value)
- logger.info(f"Set the {attribute_name} attribute of the model to {new_value} from {old_value}.")
+ if expanded_module_names:
+ logger.info(
+ f"The following LoRA modules were zero padded to match the state dict of {cls.transformer_name}: {expanded_module_names}. Please open an issue if you think this was unexpected - https://github.com/huggingface/diffusers/issues/new."
+ )
 
- return has_param_with_shape_update
+ return lora_state_dict
 
 
 # The reason why we subclass from `StableDiffusionLoraLoaderMixin` here is because Amused initially