DDUF

개요

DDUF(Diffusion Diffusion Unified Format)는 다양한 모델 배포 방식과 가중치 저장 형식을 단일 파일로 통합하기 위해 모든 모델 구성 요소를 하나의 파일에 패키징하는 diffusion 모델용 단일 파일 형식입니다. 언어에 종속적이지 않으며, 전체 파일을 다운로드하지 않고 원격 위치에서 파싱할 수 있도록 설계되었습니다.

이 작업은 GGUF 형식에서 영감을 받았습니다.

DDUF에서 가장 인기 있는 확산 모델 중 일부를 사용하기 시작하려면 DDUF 조직을 확인해 보세요.

기여를 진심으로 환영합니다!

광범위하게 채택되는 파일 포맷을 만들기 위해서는 커뮤니티의 초기 피드백이 필요합니다. 아직 확정된 사항은 없으며, 모든 분의 의견을 소중히 생각합니다. 사용 사례가 포함되지 않은 경우, DDUF 조직의 discussions에서 알려 주시기 바랍니다.

주요 기능은 다음과 같습니다.

1. 단일 파일 패키징.
2. 기존 도구 활용을 위해 ZIP 파일 형식 기반.
3. 압축을 사용하지 않아 mmap 호환성을 보장하고, 이를 통해 빠른 로딩과 저장을 지원합니다.
4. 언어 비종속적: Python, JavaScript, Rust, C++ 등으로 툴링을 구현할 수 있습니다.
5. HTTP 친화적: 메타데이터와 파일 구조를 HTTP Range 요청을 사용하여 원격으로 가져올 수 있습니다.
6. 유연성: 각 모델 구성 요소는 현재 Diffusers 구조를 따르며 자체 디렉터리에 저장됩니다.
7. Safe: 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 파일을 읽고 내보내는 헬퍼를 포함합니다. 이 도구가 diffusers 통합과 같은 Python 생태계에서 채택되기를 목표로 합니다. 유사한 도구는 다른 언어(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 아카이브의 각 파일에 해당하는 항목을 포함하는 매핑을 반환합니다. 파일은 원본 DDUF 파일 내 항목의 파일명, 오프셋, 길이를 포함하는 DDUFEntry dataclass로 표현됩니다. 이 정보는 전체 파일을 로드하지 않고도 해당 내용을 읽는 데 유용합니다. 실제로는 저수준 읽기를 직접 처리할 필요 없이 헬퍼에 의존하면 됩니다.

예를 들어, 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가 발생됩니다.

더 많은 유연성을 위해, 최종 DDUF 파일에 포함할 파일 목록을 명시적으로 지정하려면 export_entries_as_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에 저장된 체크포인트에서 파이프라인을 로드하는 예시는 다음과 같습니다:

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을 사용하지 않는 이유는 무엇인가요?

이 댓글의 설명을 참조하세요.

왜 압축이 없나요?

• 대용량 파일의 직접 메모리 매핑을 활성화합니다
• 일관되고 예측 가능한 원격 파일 액세스를 보장합니다
• Prevents CPU overhead during file reading
• safetensors와의 호환성을 유지합니다

DDUF 파일을 수정할 수 있나요?

아니요. 현재 DDUF 파일은 불변(immutable)으로 설계되어 있습니다. 모델을 업데이트하려면 새로운 DDUF 파일을 생성하세요.

DDUF을 지원하는 프레임워크/앱은 무엇인가요?

• Diffusers

우리는 지속적으로 다른 라이브러리와 프레임워크에 접근하고 있습니다. 프로젝트에 지원을 추가하는 데 관심이 있으시다면 DDUF org에서 Discussion을 열어 주세요.