[docs] Model formats by stevhliu · Pull Request #12256 · huggingface/diffusers

stevhliu · 2025-08-28T22:18:59Z

Refactors the Model files and layouts guide to from a more top-down approach, beginning with the formats (Diffusers/single-file) and then discussing the individual file types.

HuggingFaceDocBuilderDev · 2025-08-28T22:26:00Z

The docs for this PR live here. All of your documentation changes will be reflected on that endpoint. The docs are available until 30 days after the last update.

sayakpaul

Thank you!

sayakpaul · 2025-09-03T03:30:10Z

+pipeline = DiffusionPipeline.from_single_file(
+ "https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0/blob/main/sd_xl_base_1.0.safetensors",
+ torch_dtype=torch.float16,
+ device_map="cuda"


I don't think we support device_map="cuda" in from_single_file yet. Cc: @DN6 should we add support?

Supported now
diffusers/src/diffusers/loaders/single_file_model.py
Line 423 in 843355f
device_map=_determine_device_map(model, device_map, None, torch_dtype, keep_in_fp32_modules, hf_quantizer)
Snippet looks good 👍🏽

sayakpaul · 2025-09-03T03:36:00Z

-pipeline = StableDiffusionPipeline.from_single_file(
- "https://huggingface.co/stable-diffusion-v1-5/stable-diffusion-v1-5/blob/main/v1-5-pruned.ckpt"
+ckpt_path = "https://huggingface.co/lightx2v/Qwen-Image-Lightning/blob/main/Qwen-Image-Lightning-8steps-V1.1-bf16.safetensors"
+original_config = "https://raw.githubusercontent.com/Wan-Video/Wan2.2/refs/heads/main/wan/configs/wan_ti2v_5B.py"


A Python file as a config? 💡

Oops, just realized Wan doesn't support from_single_file. Reverted to the original code example!

sayakpaul · 2025-09-03T03:37:10Z

+## File types

-## Single-file layout usage
+Models can be stored in several file types. Safetensors is the most common file type but you may encounter other file types on the Hub or diffusion community.


Should safetensors be hyperlinked?

Hyperlinked in the Safetensors section below :)

sayakpaul

@DN6 please give it a review as well.

DN6 · 2025-09-22T05:51:00Z

+pipeline = DiffusionPipeline.from_single_file(
+ "https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0/blob/main/sd_xl_base_1.0.safetensors",
+ torch_dtype=torch.float16,
+ device_map="cuda"


Supported now
diffusers/src/diffusers/loaders/single_file_model.py
Line 423 in 843355f
device_map=_determine_device_map(model, device_map, None, torch_dtype, keep_in_fp32_modules, hf_quantizer)
Snippet looks good 👍🏽

DN6 · 2025-09-22T06:06:28Z

+- Easier to download and share a single file.

-Use the [`~loaders.FromSingleFileMixin.from_single_file`] method to load a model with all the weights stored in a single safetensors file.
+Use [`~loaders.FromSingleFileMixin.from_single_file`] to load a single file. Pass `"cuda"` to the `device_map` argument to pre-allocate GPU memory and reduce model loading time (refer to the [parallel loading](../using-diffusers/loading#parallel-loading) docs for more details).


Single file does support pre-allocating GPU memory to reduce model loading time, but parallel loading only works for sharded checkpoints (one more spread over multiple files).

I thought with #12305, it is supported for from_single_file now?

Parallel loading only works for multiple files (sharded checkpoints) since you load them simultaneously. Since single file is just one file, you won't see any advantage.

Ah, I see! Ok, removed mention of pre-allocating :)

DN6

LGTM 👍🏽

stevhliu marked this pull request as ready for review September 2, 2025 23:41

stevhliu requested review from DN6 and sayakpaul September 2, 2025 23:41

sayakpaul reviewed Sep 3, 2025
View reviewed changes

stevhliu requested a review from sayakpaul September 4, 2025 21:07

sayakpaul approved these changes Sep 5, 2025
View reviewed changes

stevhliu force-pushed the formats branch from 693db7d to 4eb4c84Compare September 9, 2025 15:35

stevhliu mentioned this pull request Sep 9, 2025
[feat] cache allocator warmup for from_single_model#12305
Merged

DN6 reviewed Sep 22, 2025
View reviewed changes

stevhliu added 7 commits September 22, 2025 12:47

init
a21ad39

config
e580f32

lora metadata
7ac5bb5

feedback
826a71f

fix
ba45c25

cache allocator warmup for from_single_file
4434750

feedback
27e92c5

stevhliu force-pushed the formats branch from 4eb4c84 to 27e92c5Compare September 22, 2025 19:47

feedback
efc17ab

stevhliu requested a review from DN6 September 26, 2025 21:45

DN6 approved these changes Sep 29, 2025
View reviewed changes

stevhliu merged commit c07fcf7 into huggingface:mainSep 29, 2025
1 check passed

stevhliu deleted the formats branch September 29, 2025 18:36

Uh oh!

Conversation

stevhliu commented Aug 28, 2025

Uh oh!

HuggingFaceDocBuilderDev commented Aug 28, 2025

Uh oh!

sayakpaul left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

sayakpaul left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

DN6 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants