# DDUF

    
     

## 개요

DDUF (**D**DUF, **D**iffusion **U**nified **F**ormat)는 다양한 모델 배포 방식과 가중치 저장 형식을 단일 파일로 통합하는 것을 목표로 하는 diffusion 모델용 단일 파일 형식입니다. 이 형식은 모델의 모든 구성 요소를 하나의 파일에 패키징하며, 언어에 독립적이며 전체 파일을 다운로드하지 않고 원격 위치에서 파싱할 수 있도록 설계되었습니다.

이 작업은 [GGUF](https://github.com/ggerganov/ggml/blob/master/docs/gguf.md) 형식에서 영감을 받았습니다.

DDUF에서 가장 인기 있는 확산 모델 중 일부를 사용하기 시작하려면 [DDUF](https://huggingface.co/DDUF) 조직을 확인해 보세요.

> [!TIP]
> 기여를 진심으로 환영합니다!
>
> 광범위하게 채택되는 파일 포맷을 만들기 위해서는 커뮤니티의 초기 피드백이 필요합니다. 아직 확정된 사항은 없으며, 모든 분의 의견을 소중히 생각합니다. 사용 사례가 포함되지 않은 경우, DDUF 조직의 [discussions](https://huggingface.co/spaces/DDUF/README/discussions/2)에서 알려 주시기 바랍니다.

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

1. **단일 파일** 패키징.
2. 기존 도구 활용을 위해 **ZIP 파일 형식** 기반.
3. 압축을 사용하지 않아 **`mmap` 호환성**을 보장하고, 이를 통해 빠른 로딩과 저장을 지원합니다.
4. **언어 비종속적**: Python, JavaScript, Rust, C++ 등으로 툴링을 구현할 수 있습니다.
5. **HTTP 친화적**: 메타데이터와 파일 구조를 HTTP Range 요청을 사용하여 원격으로 가져올 수 있습니다.
6. **유연성**: 각 모델 구성 요소는 현재 Diffusers 구조를 따르며 자체 디렉터리에 저장됩니다.
7. **Safe**: [Safetensors](https://huggingface.co/docs/diffusers/using-diffusers/other-formats#safetensors)를 가중치 저장 형식으로 사용하며, ZIP 폭탄을 방지하기 위해 중첩 디렉터리를 금지합니다.

## 기술 사양

기술적으로 `.dduf` 파일은 **실제로** [`.zip` 아카이브입니다](https://en.wikipedia.org/wiki/ZIP_(file_format)). 범용적으로 지원되는 파일 형식을 기반으로 함으로써 이미 견고한 툴링이 존재한다는 것을 보장합니다. 그러나 확산 모델의 요구 사항을 충족하기 위해 몇 가지 제약 사항이 적용됩니다:
- 데이터는 압축되지 않은 상태로 저장되어야 하며(플래그 `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`](https://huggingface.co/DDUF/FLUX.1-dev-DDUF/blob/main/FLUX.1-dev.dduf) 파일을 로컬로 다운로드했다고 가정합니다.

```python
>>> 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`의 내용을 로드하는 방법은 다음과 같습니다:
```python
>>> 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 가중치를 로드하는 방법은 다음과 같습니다:

```python
>>> 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
```

> [!TIP]
> `as_mmap`은 메모리 매핑의 이점을 활용하려면 컨텍스트 매니저 내에서 사용해야 합니다.

### DDUF 파일을 작성하는 방법

`export_folder_as_dduf`에 폴더 경로를 전달하여 DDUF 파일을 내보냅니다.

```python
# 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`를 사용하세요:

```python
# 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`를 제공함으로써 이를 가능하게 합니다:

```python
(...)

# 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에 저장된 체크포인트에서 파이프라인을 로드하는 예시는 다음과 같습니다:

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

이 [댓글](https://github.com/huggingface/huggingface_hub/pull/2692#issuecomment-2519863726)의 설명을 참조하세요.

### 왜 압축이 없나요?

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

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

아니요. 현재 DDUF 파일은 불변(immutable)으로 설계되어 있습니다. 모델을 업데이트하려면 새로운 DDUF 파일을 생성하세요.
	
### DDUF을 지원하는 프레임워크/앱은 무엇인가요?
	
- [Diffusers](https://github.com/huggingface/diffusers)
	
우리는 지속적으로 다른 라이브러리와 프레임워크에 접근하고 있습니다. 프로젝트에 지원을 추가하는 데 관심이 있으시다면 [DDUF org](https://huggingface.co/spaces/DDUF/README/discussions)에서 Discussion을 열어 주세요.

