Hugging Face's logo

Hub documentation

DDUF

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

DDUF

概述

DDUF（DDDUF 的 Diffusion Unified Format）是一种用于扩散模型的单文件格式，旨在通过将模型的所有组件打包到单个文件中，来统一不同的模型分发方式和权重保存格式。该格式与编程语言无关，并且支持从远程位置解析，而无需下载整个文件。

这项工作借鉴了 GGUF 格式。

查看 DDUF 组织，开始使用 DDUF 中一些最流行的扩散模型。

我们热烈欢迎各种贡献！

为了创建一个被广泛采用的文件格式，我们需要来自社区的早期反馈。一切尚未定论，我们重视每个人的意见。如果您的用例未被涵盖，请在 DDUF 组织的 讨论 中告诉我们。

其主要功能包括以下内容。

  1. 单文件打包。
  2. 基于 ZIP 文件格式，以利用现有的工具。
  3. 无压缩，确保 mmap 兼容性，以实现快速加载和保存。
  4. 语言无关：工具可以用 Python、JavaScript、Rust、C++ 等语言实现。
  5. 支持 HTTP：元数据和文件结构可以通过 HTTP Range 请求远程获取。
  6. 灵活：每个模型组件都存储在自己的目录中，遵循当前的 Diffusers 结构。
  7. 安全：使用 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")

F.A.Q.

为什么要在 ZIP 之上构建？

ZIP 提供了多项优势：

  • 通用支持的文件格式
  • 读取无需额外依赖
  • 内置文件索引
  • 广泛的语言支持

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

请参阅此评论中的说明。

为什么没有压缩？

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

我可以修改 DDUF 文件吗？

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

哪些框架/应用支持 DDUF？

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

Update on GitHub

←在 Ollama 中使用 GGUF 数据集→