Buckets:

hf-doc-build
/

doc

Files

xet

hf-doc-build/doc / diffusers /v0.43.0 /ru /optimization /coreml.md

mishig

2 days ago

preview code

download

raw

17 kB

# Как запустить Stable Diffusion с Core ML

[Core ML](https://developer.apple.com/documentation/coreml) — это формат моделей и библиотека машинного обучения, поддерживаемая фреймворками Apple. Если вы хотите запускать модели Stable Diffusion в своих приложениях для macOS или iOS/iPadOS, это руководство покажет, как преобразовать существующие контрольные точки PyTorch в формат Core ML и использовать их для инференса на Python или Swift.

Модели Core ML могут использовать все вычислительные движки, доступные в устройствах Apple: CPU, GPU и Apple Neural Engine (или ANE, тензорный ускоритель, доступный в Mac на Apple Silicon и современных iPhone/iPad). В зависимости от модели и устройства, на котором она выполняется, Core ML также может комбинировать вычислительные движки, поэтому, например, часть модели может выполняться на CPU, а другая — на GPU.

> [!TIP]
> Вы также можете запускать кодовую базу `diffusers` на Python на Mac с Apple Silicon, используя акселератор `mps`, встроенный в PyTorch. Этот подход подробно описан в [руководстве по mps](mps), но он несовместим с нативными приложениями.

## Чекпоинты Stable Diffusion Core ML

Веса Stable Diffusion (или контрольные точки) хранятся в формате PyTorch, поэтому перед использованием в нативных приложениях их необходимо преобразовать в формат Core ML.

К счастью, инженеры Apple разработали [инструмент для конвертации](https://github.com/apple/ml-stable-diffusion#-converting-models-to-core-ml) на основе `diffusers`, который позволяет преобразовывать контрольные точки PyTorch в формат Core ML.

Прежде чем конвертировать модель, уделите время изучению Hugging Face Hub – скорее всего, интересующая вас модель уже доступна в формате Core ML:

- Организация [Apple](https://huggingface.co/apple) включает версии Stable Diffusion 1.4, 1.5, 2.0 base и 2.1 base
- [coreml community](https://huggingface.co/coreml-community) включает в себя кастомные дообученные модели
- используйте этот [фильтр](https://huggingface.co/models?pipeline_tag=text-to-image&library=coreml&p=2&sort=likes), чтобы вернуть все доступные контрольные точки Core ML

Если вы не можете найти интересующую вас модель, мы рекомендуем следовать инструкциям Apple по [конвертации моделей в Core ML](https://github.com/apple/ml-stable-diffusion#-converting-models-to-core-ml).

## Выбор варианта Core ML

Модели Stable Diffusion можно преобразовать в различные варианты Core ML, предназначенные для разных целей:

- Тип используемых блоков внимания. Операция внимания используется, чтобы «обращать внимание» на взаимосвязи между различными областями в представлениях изображения и понимать, как связаны представления изображения и текста. Внимание требует значительных вычислительных ресурсов и памяти, поэтому существуют различные реализации, учитывающие аппаратные характеристики разных устройств. Для моделей Stable Diffusion для Core ML существуют два варианта внимания:
    * `split_einsum` ([предложенный Apple](https://machinelearning.apple.com/research/neural-engine-transformers)) оптимизирован для устройств ANE, которые доступны в современных iPhone, iPad и компьютерах серии M.
    * «Оригинальное» внимание (базовая реализация, используемая в `diffusers`) совместимо только с CPU/GPU, но не с ANE. Запуск модели на CPU + GPU с использованием внимания `original` может оказаться *быстрее*, чем на ANE. Дополнительные сведения см. в [этом бенчмарке производительности](https://huggingface.co/blog/fast-mac-diffusers#performance-benchmarks) и в [дополнительных замерах, предоставленных сообществом](https://github.com/huggingface/swift-coreml-diffusers/issues/31).

- Поддерживаемый фреймворк для инференса.
    * `packages` подходят для инференса на Python. Их можно использовать для тестирования сконвертированных моделей Core ML перед попыткой интеграции в нативные приложения или если вы хотите исследовать производительность Core ML, но не поддерживаете нативные приложения. Например, приложение с веб-интерфейсом может вполне использовать Python-бэкенд Core ML.
    * Модели `compiled` необходимы для кода на Swift. Модели `compiled` в Hub разделяют веса большой модели UNet на несколько файлов для совместимости с устройствами iOS и iPadOS. Это соответствует параметру конвертации [`--chunk-unet`](https://github.com/apple/ml-stable-diffusion#-converting-models-to-core-ml). Если вы хотите поддерживать нативные приложения, вам нужно выбрать вариант `compiled`.

Официальные модели Stable Diffusion для Core ML [включают](https://huggingface.co/apple/coreml-stable-diffusion-v1-4/tree/main) следующие варианты, но варианты сообщества могут отличаться:

```
coreml-stable-diffusion-v1-4
├── README.md
├── original
│   ├── compiled
│   └── packages
└── split_einsum
    ├── compiled
    └── packages
```

Вы можете скачать и использовать нужный вам вариант, как показано ниже.

## Вывод в Core ML на Python

Установите следующие библиотеки для выполнения инференса Core ML в Python:

```bash
pip install huggingface_hub
pip install git+https://github.com/apple/ml-stable-diffusion
```

### Загрузка контрольных точек модели

Для выполнения инференса на Python используйте одну из версий, хранящихся в папках `packages`, так как версии из `compiled` совместимы только со Swift. Вы можете выбрать, использовать ли вам `original` или `split_einsum` attention.

Вот как скачать вариант `original` внимания из Hub в каталог `models`:

```Python
from huggingface_hub import snapshot_download
from pathlib import Path
repo_id = "apple/coreml-stable-diffusion-v1-4"
variant = "original/packages"
model_path = Path("./models") / (repo_id.split("/")[-1] + "_" + variant.replace("/", "_"))
snapshot_download(repo_id, allow_patterns=f"{variant}/*", local_dir=model_path, local_dir_use_symlinks=False)
print(f"Model downloaded at {model_path}")
```

### Вывод[[python-inference]]

После загрузки снимка модели вы можете протестировать её с помощью Python-скрипта Apple.

```shell
python -m python_coreml_stable_diffusion.pipeline --prompt "a photo of an astronaut riding a horse on mars" -i ./models/coreml-stable-diffusion-v1-4_original_packages/original/packages -o </path/to/output/image> --compute-unit CPU_AND_GPU --seed 93
```

Передайте путь к скачанной контрольной точке в скрипт с флагом `-i`. Флаг `--compute-unit` указывает на аппаратное обеспечение, которое разрешено использовать для инференса. Он должен быть одним из следующих вариантов: `ALL`, `CPU_AND_GPU`, `CPU_ONLY`, `CPU_AND_NE`. Также можно указать необязательный путь для вывода и seed для воспроизводимости.

Скрипт для инференса предполагает, что вы используете исходную версию модели Stable Diffusion, `CompVis/stable-diffusion-v1-4`. Если вы используете другую модель, вам *необходимо* указать её Hub id в командной строке инференса с помощью опции `--model-version`. Это работает как для уже поддерживаемых моделей, так и для собственных моделей, которые вы обучили или дообучили.

Например, если вы хотите использовать [`stable-diffusion-v1-5/stable-diffusion-v1-5`](https://huggingface.co/stable-diffusion-v1-5/stable-diffusion-v1-5):

```shell
python -m python_coreml_stable_diffusion.pipeline --prompt "a photo of an astronaut riding a horse on mars" --compute-unit ALL -o output --seed 93 -i models/coreml-stable-diffusion-v1-5_original_packages --model-version stable-diffusion-v1-5/stable-diffusion-v1-5
```

## Вывод Core ML на Swift

Запуск инференса на Swift немного быстрее, чем на Python, поскольку модели уже скомпилированы в формате `mlmodelc`. Это заметно при запуске приложения, когда модель загружается, но не должно быть заметно, если после этого выполнить несколько генераций.

### Загрузить

Чтобы выполнить инференс на Swift на вашем Mac, вам нужна одна из `compiled` версий контрольных точек. Мы рекомендуем скачать их локально с помощью Python-кода, похожего на предыдущий пример, но с одним из `compiled` вариантов:

```Python
from huggingface_hub import snapshot_download
from pathlib import Path
repo_id = "apple/coreml-stable-diffusion-v1-4"
variant = "original/compiled"
model_path = Path("./models") / (repo_id.split("/")[-1] + "_" + variant.replace("/", "_"))
snapshot_download(repo_id, allow_patterns=f"{variant}/*", local_dir=model_path, local_dir_use_symlinks=False)
print(f"Model downloaded at {model_path}")
```

### Вывод[[swift-inference]]

Для запуска инференса клонируйте репозиторий Apple:

```bash
git clone https://github.com/apple/ml-stable-diffusion
cd ml-stable-diffusion
```

Затем используйте командную утилиту Apple [Swift Package Manager](https://www.swift.org/package-manager/#):

```bash
swift run StableDiffusionSample --resource-path models/coreml-stable-diffusion-v1-4_original_compiled --compute-units all "a photo of an astronaut riding a horse on mars"
```

В параметре `--resource-path` необходимо указать один из контрольных точек, загруженных на предыдущем шаге, поэтому убедитесь, что он содержит скомпилированные пакеты Core ML с расширением `.mlmodelc`. Значение параметра `--compute-units` должно быть одним из следующих: `all`, `cpuOnly`, `cpuAndGPU`, `cpuAndNeuralEngine`.

Для получения подробной информации обратитесь к [инструкциям в репозитории Apple](https://github.com/apple/ml-stable-diffusion).

## Поддерживаемые функции Diffusers

Модели Core ML и код для инференса не поддерживают многие функции, опции и возможности 🧨 Diffusers. Вот некоторые ограничения, о которых стоит помнить:

- Модели Core ML подходят только для инференса. Их нельзя использовать для обучения или дообучения.
- В Swift были перенесены только два планировщика: планировщик по умолчанию, используемый в Stable Diffusion, и `DPMSolverMultistepScheduler`, который мы перенесли в Swift из нашей реализации `diffusers`. Мы рекомендуем использовать `DPMSolverMultistepScheduler`, поскольку он обеспечивает то же качество примерно за половину шагов.
- Негативные промпты, масштаб classifier-free guidance и задачи image-to-image доступны в коде инференса. Продвинутые функции, такие как depth guidance, ControlNet и latent upscalers, пока не поддерживаются.

Репозиторий Apple [conversion and inference repo](https://github.com/apple/ml-stable-diffusion) и наш собственный репозиторий [swift-coreml-diffusers](https://github.com/huggingface/swift-coreml-diffusers) предназначены в качестве демонстраций технологий, чтобы другие разработчики могли использовать их как основу для собственных проектов.

Если вы считаете, что не хватает каких-либо функций, пожалуйста, не стесняйтесь создавать запрос на добавление функции или, что ещё лучше, PR с вкладом 🙂.

## Нативное приложение Diffusers на Swift

Один из простых способов запустить Stable Diffusion на собственном оборудовании Apple — использовать [наш репозиторий с открытым исходным кодом на Swift](https://github.com/huggingface/swift-coreml-diffusers), основанный на `diffusers` и репозитории Apple для конвертации и инференса. Вы можете изучить код, скомпилировать его с помощью [Xcode](https://developer.apple.com/xcode/) и адаптировать под собственные задачи. Для вашего удобства также доступно [автономное приложение для Mac в App Store](https://apps.apple.com/app/diffusers/id1666309574), так что вы можете поэкспериментировать с ним, не прибегая к работе с кодом или IDE. Если вы разработчик и пришли к выводу, что Core ML — лучшее решение для создания вашего приложения Stable Diffusion, то остальная часть этого руководства поможет вам начать работу над проектом. Мы с нетерпением ждём, что вы создадите 🙂.

Xet Storage Details

Size:: 17 kB
Xet hash:: 80aa04697bf2d7f39e1a51520b17fa9745645fe4658e05164fe56a3ceef7889b

Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.

	# Как запустить Stable Diffusion с Core ML

	[Core ML](https://developer.apple.com/documentation/coreml) — это формат моделей и библиотека машинного обучения, поддерживаемая фреймворками Apple. Если вы хотите запускать модели Stable Diffusion в своих приложениях для macOS или iOS/iPadOS, это руководство покажет, как преобразовать существующие контрольные точки PyTorch в формат Core ML и использовать их для инференса на Python или Swift.

	Модели Core ML могут использовать все вычислительные движки, доступные в устройствах Apple: CPU, GPU и Apple Neural Engine (или ANE, тензорный ускоритель, доступный в Mac на Apple Silicon и современных iPhone/iPad). В зависимости от модели и устройства, на котором она выполняется, Core ML также может комбинировать вычислительные движки, поэтому, например, часть модели может выполняться на CPU, а другая — на GPU.

	> [!TIP]
	> Вы также можете запускать кодовую базу `diffusers` на Python на Mac с Apple Silicon, используя акселератор `mps`, встроенный в PyTorch. Этот подход подробно описан в [руководстве по mps](mps), но он несовместим с нативными приложениями.

	## Чекпоинты Stable Diffusion Core ML

	Веса Stable Diffusion (или контрольные точки) хранятся в формате PyTorch, поэтому перед использованием в нативных приложениях их необходимо преобразовать в формат Core ML.

	К счастью, инженеры Apple разработали [инструмент для конвертации](https://github.com/apple/ml-stable-diffusion#-converting-models-to-core-ml) на основе `diffusers`, который позволяет преобразовывать контрольные точки PyTorch в формат Core ML.

	Прежде чем конвертировать модель, уделите время изучению Hugging Face Hub – скорее всего, интересующая вас модель уже доступна в формате Core ML:

	- Организация [Apple](https://huggingface.co/apple) включает версии Stable Diffusion 1.4, 1.5, 2.0 base и 2.1 base
	- [coreml community](https://huggingface.co/coreml-community) включает в себя кастомные дообученные модели
	- используйте этот [фильтр](https://huggingface.co/models?pipeline_tag=text-to-image&library=coreml&p=2&sort=likes), чтобы вернуть все доступные контрольные точки Core ML

	Если вы не можете найти интересующую вас модель, мы рекомендуем следовать инструкциям Apple по [конвертации моделей в Core ML](https://github.com/apple/ml-stable-diffusion#-converting-models-to-core-ml).

	## Выбор варианта Core ML

	Модели Stable Diffusion можно преобразовать в различные варианты Core ML, предназначенные для разных целей:

	- Тип используемых блоков внимания. Операция внимания используется, чтобы «обращать внимание» на взаимосвязи между различными областями в представлениях изображения и понимать, как связаны представления изображения и текста. Внимание требует значительных вычислительных ресурсов и памяти, поэтому существуют различные реализации, учитывающие аппаратные характеристики разных устройств. Для моделей Stable Diffusion для Core ML существуют два варианта внимания:
	* `split_einsum` ([предложенный Apple](https://machinelearning.apple.com/research/neural-engine-transformers)) оптимизирован для устройств ANE, которые доступны в современных iPhone, iPad и компьютерах серии M.
	* «Оригинальное» внимание (базовая реализация, используемая в `diffusers`) совместимо только с CPU/GPU, но не с ANE. Запуск модели на CPU + GPU с использованием внимания `original` может оказаться быстрее, чем на ANE. Дополнительные сведения см. в [этом бенчмарке производительности](https://huggingface.co/blog/fast-mac-diffusers#performance-benchmarks) и в [дополнительных замерах, предоставленных сообществом](https://github.com/huggingface/swift-coreml-diffusers/issues/31).

	- Поддерживаемый фреймворк для инференса.
	* `packages` подходят для инференса на Python. Их можно использовать для тестирования сконвертированных моделей Core ML перед попыткой интеграции в нативные приложения или если вы хотите исследовать производительность Core ML, но не поддерживаете нативные приложения. Например, приложение с веб-интерфейсом может вполне использовать Python-бэкенд Core ML.
	* Модели `compiled` необходимы для кода на Swift. Модели `compiled` в Hub разделяют веса большой модели UNet на несколько файлов для совместимости с устройствами iOS и iPadOS. Это соответствует параметру конвертации [`--chunk-unet`](https://github.com/apple/ml-stable-diffusion#-converting-models-to-core-ml). Если вы хотите поддерживать нативные приложения, вам нужно выбрать вариант `compiled`.

	Официальные модели Stable Diffusion для Core ML [включают](https://huggingface.co/apple/coreml-stable-diffusion-v1-4/tree/main) следующие варианты, но варианты сообщества могут отличаться:

	```
	coreml-stable-diffusion-v1-4
	├── README.md
	├── original
	│ ├── compiled
	│ └── packages
	└── split_einsum
	├── compiled
	└── packages
	```

	Вы можете скачать и использовать нужный вам вариант, как показано ниже.

	## Вывод в Core ML на Python

	Установите следующие библиотеки для выполнения инференса Core ML в Python:

	```bash
	pip install huggingface_hub
	pip install git+https://github.com/apple/ml-stable-diffusion
	```

	### Загрузка контрольных точек модели

	Для выполнения инференса на Python используйте одну из версий, хранящихся в папках `packages`, так как версии из `compiled` совместимы только со Swift. Вы можете выбрать, использовать ли вам `original` или `split_einsum` attention.

	Вот как скачать вариант `original` внимания из Hub в каталог `models`:

	```Python
	from huggingface_hub import snapshot_download
	from pathlib import Path

	repo_id = "apple/coreml-stable-diffusion-v1-4"
	variant = "original/packages"

	model_path = Path("./models") / (repo_id.split("/")[-1] + "_" + variant.replace("/", "_"))
	snapshot_download(repo_id, allow_patterns=f"{variant}/*", local_dir=model_path, local_dir_use_symlinks=False)
	print(f"Model downloaded at {model_path}")
	```

	### Вывод[[python-inference]]

	После загрузки снимка модели вы можете протестировать её с помощью Python-скрипта Apple.

	```shell
	python -m python_coreml_stable_diffusion.pipeline --prompt "a photo of an astronaut riding a horse on mars" -i ./models/coreml-stable-diffusion-v1-4_original_packages/original/packages -o </path/to/output/image> --compute-unit CPU_AND_GPU --seed 93
	```

	Передайте путь к скачанной контрольной точке в скрипт с флагом `-i`. Флаг `--compute-unit` указывает на аппаратное обеспечение, которое разрешено использовать для инференса. Он должен быть одним из следующих вариантов: `ALL`, `CPU_AND_GPU`, `CPU_ONLY`, `CPU_AND_NE`. Также можно указать необязательный путь для вывода и seed для воспроизводимости.

	Скрипт для инференса предполагает, что вы используете исходную версию модели Stable Diffusion, `CompVis/stable-diffusion-v1-4`. Если вы используете другую модель, вам необходимо указать её Hub id в командной строке инференса с помощью опции `--model-version`. Это работает как для уже поддерживаемых моделей, так и для собственных моделей, которые вы обучили или дообучили.

	Например, если вы хотите использовать [`stable-diffusion-v1-5/stable-diffusion-v1-5`](https://huggingface.co/stable-diffusion-v1-5/stable-diffusion-v1-5):

	```shell
	python -m python_coreml_stable_diffusion.pipeline --prompt "a photo of an astronaut riding a horse on mars" --compute-unit ALL -o output --seed 93 -i models/coreml-stable-diffusion-v1-5_original_packages --model-version stable-diffusion-v1-5/stable-diffusion-v1-5
	```

	## Вывод Core ML на Swift

	Запуск инференса на Swift немного быстрее, чем на Python, поскольку модели уже скомпилированы в формате `mlmodelc`. Это заметно при запуске приложения, когда модель загружается, но не должно быть заметно, если после этого выполнить несколько генераций.

	### Загрузить

	Чтобы выполнить инференс на Swift на вашем Mac, вам нужна одна из `compiled` версий контрольных точек. Мы рекомендуем скачать их локально с помощью Python-кода, похожего на предыдущий пример, но с одним из `compiled` вариантов:

	```Python
	from huggingface_hub import snapshot_download
	from pathlib import Path

	repo_id = "apple/coreml-stable-diffusion-v1-4"
	variant = "original/compiled"

	model_path = Path("./models") / (repo_id.split("/")[-1] + "_" + variant.replace("/", "_"))
	snapshot_download(repo_id, allow_patterns=f"{variant}/*", local_dir=model_path, local_dir_use_symlinks=False)
	print(f"Model downloaded at {model_path}")
	```

	### Вывод[[swift-inference]]

	Для запуска инференса клонируйте репозиторий Apple:

	```bash
	git clone https://github.com/apple/ml-stable-diffusion
	cd ml-stable-diffusion
	```

	Затем используйте командную утилиту Apple [Swift Package Manager](https://www.swift.org/package-manager/#):

	```bash
	swift run StableDiffusionSample --resource-path models/coreml-stable-diffusion-v1-4_original_compiled --compute-units all "a photo of an astronaut riding a horse on mars"
	```

	В параметре `--resource-path` необходимо указать один из контрольных точек, загруженных на предыдущем шаге, поэтому убедитесь, что он содержит скомпилированные пакеты Core ML с расширением `.mlmodelc`. Значение параметра `--compute-units` должно быть одним из следующих: `all`, `cpuOnly`, `cpuAndGPU`, `cpuAndNeuralEngine`.

	Для получения подробной информации обратитесь к [инструкциям в репозитории Apple](https://github.com/apple/ml-stable-diffusion).

	## Поддерживаемые функции Diffusers

	Модели Core ML и код для инференса не поддерживают многие функции, опции и возможности 🧨 Diffusers. Вот некоторые ограничения, о которых стоит помнить:

	- Модели Core ML подходят только для инференса. Их нельзя использовать для обучения или дообучения.
	- В Swift были перенесены только два планировщика: планировщик по умолчанию, используемый в Stable Diffusion, и `DPMSolverMultistepScheduler`, который мы перенесли в Swift из нашей реализации `diffusers`. Мы рекомендуем использовать `DPMSolverMultistepScheduler`, поскольку он обеспечивает то же качество примерно за половину шагов.
	- Негативные промпты, масштаб classifier-free guidance и задачи image-to-image доступны в коде инференса. Продвинутые функции, такие как depth guidance, ControlNet и latent upscalers, пока не поддерживаются.

	Репозиторий Apple [conversion and inference repo](https://github.com/apple/ml-stable-diffusion) и наш собственный репозиторий [swift-coreml-diffusers](https://github.com/huggingface/swift-coreml-diffusers) предназначены в качестве демонстраций технологий, чтобы другие разработчики могли использовать их как основу для собственных проектов.

	Если вы считаете, что не хватает каких-либо функций, пожалуйста, не стесняйтесь создавать запрос на добавление функции или, что ещё лучше, PR с вкладом 🙂.

	## Нативное приложение Diffusers на Swift

	Один из простых способов запустить Stable Diffusion на собственном оборудовании Apple — использовать [наш репозиторий с открытым исходным кодом на Swift](https://github.com/huggingface/swift-coreml-diffusers), основанный на `diffusers` и репозитории Apple для конвертации и инференса. Вы можете изучить код, скомпилировать его с помощью [Xcode](https://developer.apple.com/xcode/) и адаптировать под собственные задачи. Для вашего удобства также доступно [автономное приложение для Mac в App Store](https://apps.apple.com/app/diffusers/id1666309574), так что вы можете поэкспериментировать с ним, не прибегая к работе с кодом или IDE. Если вы разработчик и пришли к выводу, что Core ML — лучшее решение для создания вашего приложения Stable Diffusion, то остальная часть этого руководства поможет вам начать работу над проектом. Мы с нетерпением ждём, что вы создадите 🙂.