DDUF

Tổng quan

DDUF (Diffusion Diffusion Unified Format) là định dạng tệp đơn cho các mô hình khuếch tán, nhằm thống nhất các phương pháp phân phối mô hình và định dạng lưu trữ trọng số khác nhau bằng cách đóng gói tất cả các thành phần của mô hình vào một tệp duy nhất. Định dạng này không phụ thuộc vào ngôn ngữ và được xây dựng để có thể phân tích từ một vị trí từ xa mà không cần tải xuống toàn bộ tệp.

Công việc này lấy cảm hứng từ định dạng GGUF.

Hãy xem tổ chức DDUF để bắt đầu sử dụng một số mô hình khuếch tán phổ biến nhất trong DDUF.

Chúng tôi luôn chào đón mọi đóng góp!

Để tạo ra một định dạng tệp được áp dụng rộng rãi, chúng ta cần phản hồi sớm từ cộng đồng. Mọi thứ đều chưa được cố định và chúng tôi trân trọng mọi ý kiến đóng góp. Trường hợp sử dụng của bạn chưa được đề cập? Vui lòng cho chúng tôi biết trong phần discussions của tổ chức DDUF.

Các tính năng chính của nó bao gồm những điểm sau.

1. Đóng gói đơn file.
2. Dựa trên định dạng tệp ZIP để tận dụng các công cụ có sẵn.
3. Không nén, đảm bảo tương thích mmap để tải và lưu nhanh chóng.
4. Không phụ thuộc ngôn ngữ: công cụ có thể được triển khai bằng Python, JavaScript, Rust, C++, v.v.
5. Thân thiện với HTTP: metadata và cấu trúc tệp có thể được lấy từ xa bằng các yêu cầu HTTP Range.
6. Linh hoạt: mỗi thành phần của mô hình được lưu trữ trong thư mục riêng, tuân theo cấu trúc Diffusers hiện tại.
7. An toàn: sử dụng Safetensors làm định dạng lưu trọng số và cấm các thư mục lồng nhau để ngăn chặn các vụ tấn công ZIP bomb.

Thông số kỹ thuật

Về mặt kỹ thuật, tệp .dduf là một lưu trữ .zip. Bằng cách xây dựng dựa trên định dạng tệp được hỗ trợ phổ biến, chúng tôi đảm bảo rằng các công cụ mạnh mẽ đã tồn tại. Tuy nhiên, một số ràng buộc được áp đặt để đáp ứng các yêu cầu của mô hình khuếch tán:

• Dữ liệu phải được lưu trữ ở dạng không nén (cờ 0), cho phép nạp dữ liệu theo kiểu lười (lazy-loading) bằng cách ánh xạ bộ nhớ (memory-mapping).
• Dữ liệu phải được lưu trữ bằng giao thức ZIP64, cho phép lưu các tệp lớn hơn 4GB.
• Tệp lưu trữ chỉ có thể chứa các tệp .json, .safetensors, .model và .txt.
• Một tệp model_index.json phải có mặt ở thư mục gốc của tệp lưu trữ. Tệp này phải chứa một ánh xạ khóa-giá trị với các siêu dữ liệu về mô hình và các thành phần của nó.
• Mỗi thành phần phải được lưu trữ trong thư mục riêng của nó (ví dụ: vae/, text_encoder/). Các tệp lồng nhau phải sử dụng ký tự phân tách đường dẫn kiểu UNIX (/).
• Mỗi thư mục phải tương ứng với một thành phần trong chỉ mục model_index.json.
• Mỗi thư mục phải chứa một tệp cấu hình json (một trong số config.json, tokenizer_config.json, preprocessor_config.json, scheduler_config.json).
• Các thư mục con bị cấm.

Bạn muốn kiểm tra xem tệp của mình có hợp lệ không? Hãy kiểm tra bằng cách sử dụng Space này: https://huggingface.co/spaces/DDUF/dduf-check.

Cách sử dụng

huggingface_hub cung cấp các công cụ để xử lý tệp DDUF trong Python. Nó bao gồm các quy tắc tích hợp để xác minh tính toàn vẹn của tệp và các hàm trợ giúp để đọc và xuất tệp DDUF. Mục tiêu là thấy các công cụ này được áp dụng trong hệ sinh thái Python, chẳng hạn như trong tích hợp diffusers. Các công cụ tương tự có thể được phát triển cho các ngôn ngữ khác (JavaScript, Rust, C++, v.v.).

Cách đọc tệp DDUF?

Truyền một đường dẫn vào read_dduf_file để đọc một tệp DDUF. Chỉ có metadata được đọc, nghĩa là đây là một thao tác nhẹ, không làm tràn bộ nhớ. Trong ví dụ bên dưới, chúng ta giả định rằng bạn đã tải tệp FLUX.1-dev.dduf về máy cục bộ.

>>> from huggingface_hub import read_dduf_file

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

read_dduf_file trả về một mapping, trong đó mỗi entry tương ứng với một file trong archive DDUF. Một file được biểu diễn bằng dataclass DDUFEntry, chứa tên file, offset và length của entry trong file DDUF gốc. Thông tin này hữu ích để đọc nội dung mà không cần tải toàn bộ file. Trên thực tế, bạn sẽ không phải xử lý việc đọc ở mức thấp mà thay vào đó sẽ dựa vào các hàm hỗ trợ.

Ví dụ, đây là cách để nạp nội dung của 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', ...

Đối với các tệp nhị phân, bạn sẽ muốn truy cập các byte thô bằng cách sử dụng as_mmap. Hàm này trả về các byte dưới dạng ánh xạ bộ nhớ (memory-mapping) trên tệp gốc. Ánh xạ bộ nhớ cho phép bạn chỉ đọc các byte cần thiết mà không phải nạp toàn bộ vào bộ nhớ. Ví dụ, đây là cách để nạp trọng số 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 phải được sử dụng trong một context manager để tận dụng các thuộc tính memory-mapping.

Cách viết một tệp DDUF?

Truyền đường dẫn thư mục vào export_folder_as_dduf để xuất tệp 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")

Công cụ này quét thư mục, thêm các mục liên quan và đảm bảo tệp xuất hợp lệ. Nếu có bất kỳ lỗi nào xảy ra trong quá trình, một DDUFExportError sẽ được ném ra.

Để có nhiều linh hoạt hơn, hãy sử dụng [export_entries_as_dduf] để chỉ định rõ danh sách các tệp cần đưa vào tệp DDUF cuối cùng:

# 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 hoạt động tốt nếu bạn đã lưu mô hình trên đĩa. Nhưng nếu bạn có một mô hình đang được nạp vào bộ nhớ và muốn serialize nó trực tiếp vào một tệp DDUF thì sao? export_entries_as_dduf cho phép bạn làm điều đó bằng cách cung cấp một generator Python mô tả cách serialize dữ liệu theo từng phần:

(...)

# 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))

Tải tệp DDUF với Diffusers

Diffusers có tích hợp sẵn cho các tệp DDUF. Dưới đây là một ví dụ về cách tải một pipeline từ một checkpoint đã lưu trên Hub:

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.

Tại sao nên xây dựng trên nền tảng ZIP?

ZIP cung cấp một số lợi thế:

• Định dạng tệp được hỗ trợ phổ biến
• Không có phụ thuộc bổ sung nào để đọc
• Chỉ mục tệp tích hợp
• Hỗ trợ ngôn ngữ rộng

Tại sao không sử dụng một tệp TAR có mục lục ở đầu tệp lưu trữ?

Xem giải thích trong bình luận này.

Tại sao không có nén?

• Cho phép ánh xạ bộ nhớ trực tiếp của các tệp lớn
• Đảm bảo truy cập tệp từ xa nhất quán và có thể dự đoán
• Ngăn chặn chi phí CPU trong quá trình đọc tệp
• Duy trì khả năng tương thích với safetensors

Tôi có thể chỉnh sửa tệp DDUF không?

Không. Hiện tại, các tệp DDUF được thiết kế để bất biến. Để cập nhật một mô hình, hãy tạo một tệp DDUF mới.

Các framework/ứng dụng nào hỗ trợ DDUF?

• Diffusers

Chúng tôi liên tục liên hệ với các thư viện và framework khác. Nếu bạn quan tâm đến việc thêm hỗ trợ cho dự án của mình, hãy mở một Discussion trong tổ chức DDUF.