# DiffusionPipeline

Модели диффузии состоят из нескольких компонентов, таких как UNet или диффузионные трансформеры (DiT), текстовые энкодеры, вариационные автоэнкодеры (VAE) и планировщики. [DiffusionPipeline](/docs/diffusers/main/ru/api/pipelines/overview#diffusers.DiffusionPipeline) объединяет все эти компоненты в единый простой в использовании API, не теряя при этом гибкости для модификации отдельных компонентов.

В этом руководстве показано, как загрузить [DiffusionPipeline](/docs/diffusers/main/ru/api/pipelines/overview#diffusers.DiffusionPipeline).

## Загрузка конвейера

[DiffusionPipeline](/docs/diffusers/main/ru/api/pipelines/overview#diffusers.DiffusionPipeline) — это базовый класс конвейера, который автоматически выбирает и возвращает экземпляр подкласса конвейера модели, например [QwenImagePipeline](/docs/diffusers/main/ru/api/pipelines/qwenimage#diffusers.QwenImagePipeline), сканируя файл `model_index.json` в поисках имени класса.

Передайте идентификатор модели в [from_pretrained()](/docs/diffusers/main/ru/api/pipelines/overview#diffusers.DiffusionPipeline.from_pretrained), чтобы загрузить конвейер.

```py
import torch
from diffusers import DiffusionPipeline

pipeline = DiffusionPipeline.from_pretrained(
  "Qwen/Qwen-Image", dtype=torch.bfloat16, device_map="cuda"  # or "mps", "xpu", "cpu"
)
```

Каждая модель имеет собственный подкласс пайплайна, наследующий от [DiffusionPipeline](/docs/diffusers/main/ru/api/pipelines/overview#diffusers.DiffusionPipeline). Как правило, подкласс имеет узкую специализацию и предназначен для конкретной задачи. Пример приведён в таблице ниже.

| подкласс pipeline | задача |
|---|---|
| [QwenImagePipeline](/docs/diffusers/main/ru/api/pipelines/qwenimage#diffusers.QwenImagePipeline) | text-to-image |
| [QwenImageImg2ImgPipeline](/docs/diffusers/main/ru/api/pipelines/qwenimage#diffusers.QwenImageImg2ImgPipeline) | image-to-image |
| [QwenImageInpaintPipeline](/docs/diffusers/main/ru/api/pipelines/qwenimage#diffusers.QwenImageInpaintPipeline) | inpaint |

Вы можете использовать подкласс напрямую, передав идентификатор модели в [from_pretrained()](/docs/diffusers/main/ru/api/pipelines/overview#diffusers.DiffusionPipeline.from_pretrained).

```py
import torch
from diffusers import QwenImagePipeline

pipeline = QwenImagePipeline.from_pretrained(
  "Qwen/Qwen-Image", dtype=torch.bfloat16, device_map="cuda"  # or "mps", "xpu", "cpu"
)
```

> [!TIP]
> См. документацию [Формат одного файла](./other-formats#single-file-format), чтобы узнать, как загружать модели в формате одного файла.

### Локальные конвейеры

Пайплайны также можно запускать локально. Используйте [snapshot_download](https://huggingface.co/docs/huggingface_hub/main/en/package_reference/file_download#huggingface_hub.snapshot_download) для загрузки репозитория модели.

```py
from huggingface_hub import snapshot_download

local_dir = snapshot_download(repo_id="Qwen/Qwen-Image")
```

Передайте этот путь в [from_pretrained()](/docs/diffusers/main/ru/api/pipelines/overview#diffusers.DiffusionPipeline.from_pretrained), чтобы загрузить его.

```py
import torch
from diffusers import QwenImagePipeline

pipeline = QwenImagePipeline.from_pretrained(
  local_dir, dtype=torch.bfloat16, device_map="cuda"  # or "mps", "xpu", "cpu"
)
```

Метод [from_pretrained()](/docs/diffusers/main/ru/api/pipelines/overview#diffusers.DiffusionPipeline.from_pretrained) не скачивает файлы с Hub, если обнаруживает локальный путь. Однако это также означает, что он не скачает и не закэширует какие-либо обновления, внесённые в модель.

## Типы данных Pipeline

Используйте аргумент `dtype` в [from_pretrained()](/docs/diffusers/main/ru/api/pipelines/overview#diffusers.DiffusionPipeline.from_pretrained), чтобы загрузить модель с конкретным типом данных. Это позволяет загружать разные модели с разной точностью. Например, загрузка большой трансформерной модели в полупrecisии уменьшает требуемый объём памяти.

Передайте типы данных для каждой модели в виде словаря в `dtype`. Используйте ключ `default`, чтобы задать тип данных по умолчанию. Если модель отсутствует в словаре и `default` не указан, она загружается с полной точностью (`torch.float32`).

```py
import torch
from diffusers import QwenImagePipeline

pipeline = QwenImagePipeline.from_pretrained(
  "Qwen/Qwen-Image",
  dtype={"transformer": torch.bfloat16, "default": torch.float16},
)
print(pipeline.transformer.dtype, pipeline.vae.dtype)
```

Вам не нужно использовать словарь, если вы загружаете все модели в одном и том же типе данных.

```py
import torch
from diffusers import QwenImagePipeline

pipeline = QwenImagePipeline.from_pretrained(
  "Qwen/Qwen-Image", dtype=torch.bfloat16
)
print(pipeline.transformer.dtype, pipeline.vae.dtype)
```

## Размещение на устройствах

Аргумент `device_map` размещает пайплайн на устройствах. Во время выполнения Diffusers принимает значения `"balanced"`, `"cpu"` и строку ускорителя для вашей машины (обычно `"cuda"`, `"mps"` или `"xpu"`).

| параметр | Описание |
|---|---|
| строка accelerator | Размещает конвейер на указанном устройстве. Передайте акселератор, поддерживаемый вашим устройством, например `"cuda"`, `"mps"` или `"xpu"`. |
| `"balanced"` | Распределяет компоненты конвейера по видимым GPU. Используйте вместе с `max_memory`, когда нужны ограничения по памяти для каждого устройства. |
| `"cpu"` | Размещает конвейер на CPU. |

Используйте аргумент `max_memory` в [from_pretrained()](/docs/diffusers/main/ru/api/pipelines/overview#diffusers.DiffusionPipeline.from_pretrained), чтобы задать максимальный объём памяти, выделяемый на каждом устройстве. По умолчанию Diffusers использует весь доступный объём памяти.

```py
import torch
from diffusers import DiffusionPipeline

max_memory = {0: "16GB", 1: "16GB"}
pipeline = DiffusionPipeline.from_pretrained(
  "Qwen/Qwen-Image",
  dtype=torch.bfloat16,
  device_map="balanced",
  max_memory=max_memory,
)
```

Атрибут `hf_device_map` позволяет получить доступ к `device_map` и просмотреть его.

```py
print(pipeline.hf_device_map)
# {'transformer': 1, 'vae': 1, 'text_encoder': 0}
```

Сбросьте `device_map` конвейера с помощью метода [reset_device_map()](/docs/diffusers/main/ru/api/pipelines/overview#diffusers.DiffusionPipeline.reset_device_map). Это необходимо, если вы хотите использовать методы, такие как `.to()`, [enable_sequential_cpu_offload()](/docs/diffusers/main/ru/api/pipelines/overview#diffusers.DiffusionPipeline.enable_sequential_cpu_offload) и [enable_model_cpu_offload()](/docs/diffusers/main/ru/api/pipelines/overview#diffusers.DiffusionPipeline.enable_model_cpu_offload).

```py
pipeline.reset_device_map()
```

## Параллельная загрузка

Крупные модели часто [разбиваются](../optimization/memory#sharded-checkpoints) на более мелкие файлы, чтобы их было проще загружать. Diffusers поддерживает параллельную загрузку фрагментов для ускорения процесса загрузки.

Установите `HF_ENABLE_PARALLEL_LOADING` в значение `"YES"`, чтобы включить параллельную загрузку шардов.

Аргумент `device_map` следует установить в значение `"cuda"`, чтобы предварительно выделить большой блок памяти в соответствии с размером модели. Это значительно сокращает время загрузки модели, поскольку прогрев аллокатора памяти позволяет избежать множества мелких обращений к аллокатору на более поздних этапах.

```py
import os
import torch
from diffusers import DiffusionPipeline

os.environ["HF_ENABLE_PARALLEL_LOADING"] = "YES"

pipeline = DiffusionPipeline.from_pretrained(
  "Wan-AI/Wan2.2-I2V-A14B-Diffusers", dtype=torch.bfloat16, device_map="cuda"  # or "mps", "xpu", "cpu"
)
```

## Замена моделей в конвейере

[DiffusionPipeline](/docs/diffusers/main/ru/api/pipelines/overview#diffusers.DiffusionPipeline) гибко настраивается и поддерживает загрузку других моделей или планировщиков. Вы можете экспериментировать с различными планировщиками, чтобы оптимизировать скорость или качество генерации, а также заменять модели на более производительные.

Приведённый ниже пример использует более стабильную версию VAE.

```py
import torch
from diffusers import DiffusionPipeline, AutoModel

vae = AutoModel.from_pretrained(
  "madebyollin/sdxl-vae-fp16-fix", dtype=torch.float16
)

pipeline = DiffusionPipeline.from_pretrained(
  "stabilityai/stable-diffusion-xl-base-1.0",
  vae=vae,
  dtype=torch.float16,
  device_map="cuda"  # or "mps", "xpu", "cpu"
)
```

## Повторное использование моделей в нескольких конвейерах

При работе с несколькими конвейерами, использующими одну и ту же модель, метод [from_pipe()](/docs/diffusers/main/ru/api/pipelines/overview#diffusers.DiffusionPipeline.from_pipe) позволяет переиспользовать модель, а не загружать её заново каждый раз. Это позволяет использовать несколько конвейеров без увеличения потребления памяти.

Объём используемой памяти определяется пайплайном с наибольшими требованиями к памяти, независимо от количества пайплайнов.

[from_pipe()](/docs/diffusers/main/ru/api/pipelines/overview#diffusers.DiffusionPipeline.from_pipe) разделяет модели в памяти. Отдельные вызовы [from_pretrained()](/docs/diffusers/main/ru/api/pipelines/overview#diffusers.DiffusionPipeline.from_pretrained) разделяют файлы на диске, если два репозитория содержат идентичные файлы, например, один и тот же текстовый энкодер. Подробности — в разделе [Разделение файлов между репозиториями](../installation#share-files-across-repositories).

The example below loads a pipeline and then loads a second pipeline with [from_pipe()](/docs/diffusers/main/ru/api/pipelines/overview#diffusers.DiffusionPipeline.from_pipe) to use [perturbed-attention guidance (PAG)](../api/pipelines/pag) to improve generation quality.

> [!WARNING]
> Используйте [AutoPipelineForText2Image](/docs/diffusers/main/ru/api/pipelines/auto_pipeline#diffusers.AutoPipelineForText2Image), так как [DiffusionPipeline](/docs/diffusers/main/ru/api/pipelines/overview#diffusers.DiffusionPipeline) не поддерживает PAG. Подробнее см. в документации [AutoPipeline](../tutorials/autopipeline).

```py
import torch
from diffusers import AutoPipelineForText2Image

pipeline_sdxl = AutoPipelineForText2Image.from_pretrained(
  "stabilityai/stable-diffusion-xl-base-1.0", dtype=torch.float16, device_map="cuda"  # or "mps", "xpu", "cpu"
)
prompt = """
cinematic film still of a cat sipping a margarita in a pool in Palm Springs, California
highly detailed, high budget hollywood movie, cinemascope, moody, epic, gorgeous, film grain
"""
image = pipeline_sdxl(prompt).images[0]
print(f"Max memory reserved: {torch.cuda.max_memory_allocated() / 1024**3:.2f} GB")
# Max memory reserved: 10.47 GB
```

Установите `enable_pag=True` во втором пайплайне, чтобы включить PAG. Второй пайплайн использует тот же объём памяти, так как разделяет веса модели с первым.

```py
pipeline = AutoPipelineForText2Image.from_pipe(
  pipeline_sdxl, enable_pag=True
)
prompt = """
cinematic film still of a cat sipping a margarita in a pool in Palm Springs, California
highly detailed, high budget hollywood movie, cinemascope, moody, epic, gorgeous, film grain
"""
image = pipeline(prompt).images[0]
print(f"Max memory reserved: {torch.cuda.max_memory_allocated() / 1024**3:.2f} GB")
# Max memory reserved: 10.47 GB
```

> [!WARNING]
> Пайплайны, созданные с помощью [from_pipe()](/docs/diffusers/main/ru/api/pipelines/overview#diffusers.DiffusionPipeline.from_pipe), используют одни и те же модели и *state*. Изменение состояния модели в одном пайплайне влияет на все остальные пайплайны, которые используют эту же модель.

Some methods may not work correctly on pipelines created with [from_pipe()](/docs/diffusers/main/ru/api/pipelines/overview#diffusers.DiffusionPipeline.from_pipe). For example, [enable_model_cpu_offload()](/docs/diffusers/main/ru/api/pipelines/overview#diffusers.DiffusionPipeline.enable_model_cpu_offload) relies on a unique model execution order, which may differ in the new pipeline. To ensure proper functionality, reapply these methods on the new pipeline.

## Дальнейшие шаги

После загрузки конвейера обычно настраивают расписание удаления шума, меняют формат весов или подключают адаптеры.

- [Schedulers](./schedulers) описывает замену и настройку алгоритма удаления шума.
- [Форматы моделей](./other-formats) описывает GGUF, контрольные точки в одном файле и другие схемы расположения весов.
- [Сокращение использования памяти](../optimization/memory) описывает выгрузку данных и другие инструменты для работы с памятью.
- [LoRA](../tutorials/using_peft_for_inference) описывает загрузку адаптеров в конвейер.
- [Устаревшие контрольные точки](./legacy_checkpoints#safety-checker) описывает модуль проверки безопасности для старых контрольных точек Stable Diffusion.