DDUF

概述

DDUF (DDUF's Diffusion Unified Format) 是一种用于扩散模型的单文件格式，旨在通过将所有模型组件打包到一个文件中，来统一不同的模型分发方法和权重保存格式。它与语言无关，并且构建为无需下载整个文件即可从远程位置进行解析。

这项工作受到了 GGUF 格式的启发。

请访问 DDUF 组织，开始使用一些最流行的 DDUF 格式扩散模型。

我们张开双臂欢迎贡献！

为了创建一个被广泛采用的文件格式，我们需要社区的早期反馈。一切尚未定论，我们珍视每个人的意见。您的用例没有被覆盖到吗？请在 DDUF 组织的讨论区告诉我们。

它的主要特性包括：

单文件打包。
基于 ZIP 文件格式，以利用现有工具。
无压缩，确保 mmap 兼容性，以实现快速加载和保存。
与语言无关：可以在 Python、JavaScript、Rust、C++ 等语言中实现工具。
HTTP 友好：可以使用 HTTP Range 请求远程获取元数据和文件结构。
灵活：每个模型组件都存储在其自己的目录中，遵循当前的 Diffusers 结构。
安全：使用 Safetensors 作为权重保存格式，并禁止嵌套目录以防止 ZIP 炸弹。

技术规范

从技术上讲，一个 .dduf 文件就是一个 .zip 归档文件。通过建立在一个普遍支持的文件格式之上，我们确保了已有强大的工具可用。然而，为满足扩散模型的需求，强制执行了一些约束：

数据必须以未压缩方式存储（标志 0），允许使用内存映射进行惰性加载。
数据必须使用 ZIP64 协议存储，允许保存大于 4GB 的文件。
归档文件只能包含 .json、.safetensors、.model 和 .txt 文件。
归档文件的根目录下必须存在一个 model_index.json 文件。它必须包含一个键值映射，其中包含有关模型及其组件的元数据。
每个组件必须存储在各自的目录中（例如，vae/、text_encoder/）。嵌套文件必须使用 UNIX 风格的路径分隔符（/）。
每个目录必须对应于 model_index.json 索引中的一个组件。
每个目录必须包含一个 JSON 配置文件（config.json、tokenizer_config.json、preprocessor_config.json、scheduler_config.json 之一）。
禁止使用子目录。

想检查您的文件是否有效？请使用此 Space 进行检查：https://huggingface.co/spaces/DDUF/dduf-check。

使用方法

huggingface_hub 提供了在 Python 中处理 DDUF 文件的工具。它包括内置的规则来验证文件完整性，以及用于读取和导出 DDUF 文件的辅助函数。我们的目标是看到这些工具被 Python 生态系统采纳，例如在 diffusers 的集成中。类似的功能也可以为其他语言（JavaScript、Rust、C++ 等）开发。

如何读取 DDUF 文件？

将一个路径传递给 read_dduf_file 以读取一个 DDUF 文件。只会读取元数据，这意味着这是一个轻量级的调用，不会耗尽您的内存。在下面的例子中，我们假设您已经将 FLUX.1-dev.dduf 文件下载到本地。

>>> from huggingface_hub import read_dduf_file

# Read DDUF metadata
>>> dduf_entries = read_dduf_file("FLUX.1-dev.dduf")

read_dduf_file 返回一个映射，其中每个条目对应于 DDUF 归档中的一个文件。一个文件由一个 DDUFEntry 数据类表示，其中包含文件名、偏移量和条目在原始 DDUF 文件中的长度。这些信息对于读取其内容而无需加载整个文件非常有用。实际上，您不需要处理底层读取，而是依赖于辅助函数。

例如，以下是如何加载 model_index.json 内容的方法：

>>> import json
>>> json.loads(dduf_entries["model_index.json"].read_text())
{'_class_name': 'FluxPipeline', '_diffusers_version': '0.32.0.dev0', '_name_or_path': 'black-forest-labs/FLUX.1-dev', ...

对于二进制文件，您会希望使用 as_mmap 来访问原始字节。这将返回一个对原始文件的内存映射字节。内存映射允许您只读取您需要的字节，而无需将所有内容加载到内存中。例如，以下是如何加载 safetensors 权重的方法：

>>> import safetensors.torch
>>> with dduf_entries["vae/diffusion_pytorch_model.safetensors"].as_mmap() as mm:
...     state_dict = safetensors.torch.load(mm) # `mm` is a bytes object

as_mmap 必须在上下文管理器中使用，以利用内存映射的特性。

如何写入 DDUF 文件？

将一个文件夹路径传递给 export_folder_as_dduf 以导出一个 DDUF 文件。

# Export a folder as a DDUF file
>>> from huggingface_hub import export_folder_as_dduf
>>> export_folder_as_dduf("FLUX.1-dev.dduf", folder_path="path/to/FLUX.1-dev")

此工具会扫描文件夹，添加相关条目，并确保导出的文件是有效的。如果在过程中出现任何问题，将会引发一个 DDUFExportError。

为了更灵活，可以使用 [export_entries_as_dduf] 来明确指定要包含在最终 DDUF 文件中的文件列表：

# Export specific files from the local disk.
>>> from huggingface_hub import export_entries_as_dduf
>>> export_entries_as_dduf(
...     dduf_path="stable-diffusion-v1-4-FP16.dduf",
...     entries=[ # List entries to add to the DDUF file (here, only FP16 weights)
...         ("model_index.json", "path/to/model_index.json"),
...         ("vae/config.json", "path/to/vae/config.json"),
...         ("vae/diffusion_pytorch_model.fp16.safetensors", "path/to/vae/diffusion_pytorch_model.fp16.safetensors"),
...         ("text_encoder/config.json", "path/to/text_encoder/config.json"),
...         ("text_encoder/model.fp16.safetensors", "path/to/text_encoder/model.fp16.safetensors"),
...         # ... add more entries here
...     ]
... )

export_entries_as_dduf 在您已经将模型保存在磁盘上的情况下工作得很好。但是，如果您在内存中加载了一个模型，并希望将其直接序列化为一个 DDUF 文件，该怎么办呢？export_entries_as_dduf 允许您通过提供一个 Python `generator` 来实现这一点，它告诉您如何迭代地序列化数据：

(...)

# Export state_dicts one by one from a loaded pipeline
>>> def as_entries(pipe: DiffusionPipeline) -> Generator[Tuple[str, bytes], None, None]:
...     # Build a generator that yields the entries to add to the DDUF file.
...     # The first element of the tuple is the filename in the DDUF archive. The second element is the content of the file.
...     # Entries will be evaluated lazily when the DDUF file is created (only 1 entry is loaded in memory at a time)
...     yield "vae/config.json", pipe.vae.to_json_string().encode()
...     yield "vae/diffusion_pytorch_model.safetensors", safetensors.torch.save(pipe.vae.state_dict())
...     yield "text_encoder/config.json", pipe.text_encoder.config.to_json_string().encode()
...     yield "text_encoder/model.safetensors", safetensors.torch.save(pipe.text_encoder.state_dict())
...     # ... add more entries here

>>> export_entries_as_dduf(dduf_path="my-cool-diffusion-model.dduf", entries=as_entries(pipe))

使用 Diffusers 加载 DDUF 文件

Diffusers 内置了对 DDUF 文件的集成。以下是如何从 Hub 上存储的检查点加载一个 pipeline 的示例：

from diffusers import DiffusionPipeline
import torch

pipe = DiffusionPipeline.from_pretrained(
    "DDUF/FLUX.1-dev-DDUF", dduf_file="FLUX.1-dev.dduf", torch_dtype=torch.bfloat16
).to("cuda")
image = pipe(
    "photo a cat holding a sign that says Diffusers", num_inference_steps=50, guidance_scale=3.5
).images[0]
image.save("cat.png")

常见问题

为什么要建立在 ZIP 之上？

ZIP 提供了几个优点：

普遍支持的文件格式
读取时无需额外依赖
内置文件索引
广泛的语言支持

为什么不使用在归档开头带有目录的 TAR？

请参阅此评论中的解释。

为什么不压缩？

允许直接内存映射大文件
确保一致且可预测的远程文件访问
防止文件读取期间的 CPU 开销
保持与 safetensors 的兼容性

我可以修改 DDUF 文件吗？

不可以。目前，DDUF 文件被设计为不可变的。要更新一个模型，请创建一个新的 DDUF 文件。

哪些框架/应用支持 DDUF？

Diffusers

我们正在不断联系其他库和框架。如果您有兴趣为您的项目添加支持，请在 DDUF 组织中发起一个讨论。

< > 在 GitHub 上更新