Buckets:

hf-doc-build
/

doc

Files

xet

hf-doc-build/doc / diffusers /v0.43.0 /pt /installation.md

mishig

2 days ago

preview code

download

raw

6.05 kB

# Instalação

Diffusers requer Python 3.10+ e é testado com PyTorch 2.6+. Instale [PyTorch](https://pytorch.org/get-started/locally/) de acordo com seu sistema e configuração.

Crie um [ambiente virtual](https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/) para facilitar o gerenciamento de projetos separados e evitar problemas de compatibilidade entre dependências. Use o [uv](https://docs.astral.sh/uv/), um gerenciador de pacotes e projetos Python baseado em Rust, para criar um ambiente virtual e instalar o Diffusers.

```bash
uv venv my-env
source my-env/bin/activate
```

Instale o Diffusers com um dos seguintes métodos.

```bash
uv pip install diffusers["torch"] transformers
```

Para instalar o Diffusers com PyTorch em dispositivos NVIDIA Spark (como um laptop RTX Spark) que executam ARM64, instale o PyTorch a partir do índice PyPI da NVIDIA. Esses dispositivos exigem as compilações ARM64 do PyTorch da NVIDIA, que não estão disponíveis no índice PyPI padrão nem no índice padrão de wheels do PyTorch.

Execute o comando abaixo para verificar se o seu sistema detecta uma GPU da NVIDIA.

```bash
nvidia-smi
```

Instale o PyTorch a partir do índice PyPI da NVIDIA e, em seguida, instale o Diffusers.

```bash
uv pip install torch --index-url https://pypi.nvidia.com
uv pip install diffusers
```

```bash
conda install -c conda-forge diffusers
```

Uma instalação a partir do código-fonte instala a versão `main` em vez da versão `stable` mais recente. A versão `main` é útil para se manter atualizado com as últimas alterações, mas nem sempre é estável. Se você encontrar um problema, abra uma [Issue](https://github.com/huggingface/diffusers/issues/new/choose) e faremos o possível para resolvê-lo o mais rápido possível.

Verifique se o [Accelerate](https://huggingface.co/docs/accelerate/index) está instalado.

```bash
uv pip install accelerate
```

Instale o Diffusers a partir do código-fonte com o comando abaixo.

```bash
uv pip install git+https://github.com/huggingface/diffusers
```

Instale com extras quando precisar deles. `diffusers["torch"]` inclui PyTorch e Accelerate. Outros extras cobrem backends de quantização, treinamento e documentação. Consulte [`setup.py`](https://github.com/huggingface/diffusers/blob/main/setup.py) para a lista completa.

## Dispositivos

Diffusers funciona em qualquer acelerador suportado pelo PyTorch. Os exemplos ao longo da documentação usam `"cuda"` porque é a configuração mais comum, mas nada é específico do CUDA. Substitua a string do dispositivo pelo seu hardware, como `"xpu"` para GPUs da Intel, `"mps"` para Apple silicon ou `"cpu"`.

```py
device = "cuda"  # or "mps", "xpu", "cpu"
pipeline.to(device)
```

Para escolher o dispositivo em tempo de execução em vez de fixá-lo no código, use [torch.accelerator](https://docs.pytorch.org/docs/stable/accelerator.html).

```py
import torch
device = torch.accelerator.current_accelerator().type if torch.accelerator.is_available() else "cpu"
```

## Instalação editável

Uma instalação editável é recomendada para fluxos de trabalho de desenvolvimento ou se você estiver usando a versão `main` do código-fonte. Um link especial é criado entre o repositório clonado e os caminhos da biblioteca Python. Isso evita a reinstalação de um pacote após cada alteração.

Clone o repositório e instale o Diffusers com os seguintes comandos.

```bash
git clone https://github.com/huggingface/diffusers.git
cd diffusers
uv pip install -e ".[torch]"
```

> [!WARNING]
> Você deve manter a pasta `diffusers` se quiser continuar usando a biblioteca com a instalação editável.

Atualize seu repositório clonado para a versão mais recente do Diffusers com o comando abaixo.

```bash
cd ~/diffusers/
git pull
```

## Cache

Os pesos e arquivos do modelo são baixados do Hub para um cache, que geralmente é o seu diretório inicial. Altere a localização do cache com as variáveis de ambiente [HF_HOME](https://huggingface.co/docs/huggingface_hub/package_reference/environment_variables#hfhome) ou [HF_HUB_CACHE](https://huggingface.co/docs/huggingface_hub/package_reference/environment_variables#hfhubcache) ou configurando o parâmetro `cache_dir` em métodos como [from_pretrained()](/docs/diffusers/v0.43.0/pt/api/pipelines/overview#diffusers.DiffusionPipeline.from_pretrained).

```bash
export HF_HOME="/path/to/your/cache"
export HF_HUB_CACHE="/path/to/your/hub/cache"
```

```py
from diffusers import DiffusionPipeline
pipeline = DiffusionPipeline.from_pretrained(
    "black-forest-labs/FLUX.1-dev",
    cache_dir="/path/to/your/cache"
)
```

Arquivos em cache permitem que você use o Diffusers offline. Defina a variável de ambiente [HF_HUB_OFFLINE](https://huggingface.co/docs/huggingface_hub/package_reference/environment_variables#hfhuboffline) como `1` para impedir que o Diffusers se conecte à internet.

```shell
export HF_HUB_OFFLINE=1
```

Para mais detalhes sobre a gestão e a limpeza do cache, consulte o guia [Entenda o cache](https://huggingface.co/docs/huggingface_hub/guides/manage-cache).

## Registro de telemetria

O Diffusers coleta informações de telemetria durante as solicitações de [from_pretrained()](/docs/diffusers/v0.43.0/pt/api/pipelines/overview#diffusers.DiffusionPipeline.from_pretrained). Os dados coletados incluem a versão do Diffusers e do PyTorch, a classe do modelo ou pipeline solicitada e o caminho para um checkpoint pré-treinado, caso ele esteja hospedado no Hub.

Esses dados de uso nos ajudam a depurar problemas e priorizar novos recursos. A telemetria é enviada apenas ao carregar modelos e pipelines do Hub e não é coletada se você estiver carregando arquivos locais.

Desative e desabilite a coleta de telemetria com a variável de ambiente [HF_HUB_DISABLE_TELEMETRY](https://huggingface.co/docs/huggingface_hub/package_reference/environment_variables#hfhubdisabletelemetry).

```bash
export HF_HUB_DISABLE_TELEMETRY=1
```

```bash
set HF_HUB_DISABLE_TELEMETRY=1
```

Xet Storage Details

Size:: 6.05 kB
Xet hash:: e44736f0a32d5ae89ce57e9187f8972e7942489894ba0bb878bd2cca27212b78

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

	# Instalação

	Diffusers requer Python 3.10+ e é testado com PyTorch 2.6+. Instale [PyTorch](https://pytorch.org/get-started/locally/) de acordo com seu sistema e configuração.

	Crie um [ambiente virtual](https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/) para facilitar o gerenciamento de projetos separados e evitar problemas de compatibilidade entre dependências. Use o [uv](https://docs.astral.sh/uv/), um gerenciador de pacotes e projetos Python baseado em Rust, para criar um ambiente virtual e instalar o Diffusers.

	```bash
	uv venv my-env
	source my-env/bin/activate
	```

	Instale o Diffusers com um dos seguintes métodos.

	```bash
	uv pip install diffusers["torch"] transformers
	```

	Para instalar o Diffusers com PyTorch em dispositivos NVIDIA Spark (como um laptop RTX Spark) que executam ARM64, instale o PyTorch a partir do índice PyPI da NVIDIA. Esses dispositivos exigem as compilações ARM64 do PyTorch da NVIDIA, que não estão disponíveis no índice PyPI padrão nem no índice padrão de wheels do PyTorch.

	Execute o comando abaixo para verificar se o seu sistema detecta uma GPU da NVIDIA.

	```bash
	nvidia-smi
	```

	Instale o PyTorch a partir do índice PyPI da NVIDIA e, em seguida, instale o Diffusers.

	```bash
	uv pip install torch --index-url https://pypi.nvidia.com
	uv pip install diffusers
	```

	```bash
	conda install -c conda-forge diffusers
	```

	Uma instalação a partir do código-fonte instala a versão `main` em vez da versão `stable` mais recente. A versão `main` é útil para se manter atualizado com as últimas alterações, mas nem sempre é estável. Se você encontrar um problema, abra uma [Issue](https://github.com/huggingface/diffusers/issues/new/choose) e faremos o possível para resolvê-lo o mais rápido possível.

	Verifique se o [Accelerate](https://huggingface.co/docs/accelerate/index) está instalado.

	```bash
	uv pip install accelerate
	```

	Instale o Diffusers a partir do código-fonte com o comando abaixo.

	```bash
	uv pip install git+https://github.com/huggingface/diffusers
	```

	Instale com extras quando precisar deles. `diffusers["torch"]` inclui PyTorch e Accelerate. Outros extras cobrem backends de quantização, treinamento e documentação. Consulte [`setup.py`](https://github.com/huggingface/diffusers/blob/main/setup.py) para a lista completa.

	## Dispositivos

	Diffusers funciona em qualquer acelerador suportado pelo PyTorch. Os exemplos ao longo da documentação usam `"cuda"` porque é a configuração mais comum, mas nada é específico do CUDA. Substitua a string do dispositivo pelo seu hardware, como `"xpu"` para GPUs da Intel, `"mps"` para Apple silicon ou `"cpu"`.

	```py
	device = "cuda" # or "mps", "xpu", "cpu"
	pipeline.to(device)
	```

	Para escolher o dispositivo em tempo de execução em vez de fixá-lo no código, use [torch.accelerator](https://docs.pytorch.org/docs/stable/accelerator.html).

	```py
	import torch

	device = torch.accelerator.current_accelerator().type if torch.accelerator.is_available() else "cpu"
	```

	## Instalação editável

	Uma instalação editável é recomendada para fluxos de trabalho de desenvolvimento ou se você estiver usando a versão `main` do código-fonte. Um link especial é criado entre o repositório clonado e os caminhos da biblioteca Python. Isso evita a reinstalação de um pacote após cada alteração.

	Clone o repositório e instale o Diffusers com os seguintes comandos.

	```bash
	git clone https://github.com/huggingface/diffusers.git
	cd diffusers
	uv pip install -e ".[torch]"
	```

	> [!WARNING]
	> Você deve manter a pasta `diffusers` se quiser continuar usando a biblioteca com a instalação editável.

	Atualize seu repositório clonado para a versão mais recente do Diffusers com o comando abaixo.

	```bash
	cd ~/diffusers/
	git pull
	```

	## Cache

	Os pesos e arquivos do modelo são baixados do Hub para um cache, que geralmente é o seu diretório inicial. Altere a localização do cache com as variáveis de ambiente [HF_HOME](https://huggingface.co/docs/huggingface_hub/package_reference/environment_variables#hfhome) ou [HF_HUB_CACHE](https://huggingface.co/docs/huggingface_hub/package_reference/environment_variables#hfhubcache) ou configurando o parâmetro `cache_dir` em métodos como [from_pretrained()](/docs/diffusers/v0.43.0/pt/api/pipelines/overview#diffusers.DiffusionPipeline.from_pretrained).

	```bash
	export HF_HOME="/path/to/your/cache"
	export HF_HUB_CACHE="/path/to/your/hub/cache"
	```

	```py
	from diffusers import DiffusionPipeline

	pipeline = DiffusionPipeline.from_pretrained(
	"black-forest-labs/FLUX.1-dev",
	cache_dir="/path/to/your/cache"
	)
	```

	Arquivos em cache permitem que você use o Diffusers offline. Defina a variável de ambiente [HF_HUB_OFFLINE](https://huggingface.co/docs/huggingface_hub/package_reference/environment_variables#hfhuboffline) como `1` para impedir que o Diffusers se conecte à internet.

	```shell
	export HF_HUB_OFFLINE=1
	```

	Para mais detalhes sobre a gestão e a limpeza do cache, consulte o guia [Entenda o cache](https://huggingface.co/docs/huggingface_hub/guides/manage-cache).

	## Registro de telemetria

	O Diffusers coleta informações de telemetria durante as solicitações de [from_pretrained()](/docs/diffusers/v0.43.0/pt/api/pipelines/overview#diffusers.DiffusionPipeline.from_pretrained). Os dados coletados incluem a versão do Diffusers e do PyTorch, a classe do modelo ou pipeline solicitada e o caminho para um checkpoint pré-treinado, caso ele esteja hospedado no Hub.

	Esses dados de uso nos ajudam a depurar problemas e priorizar novos recursos. A telemetria é enviada apenas ao carregar modelos e pipelines do Hub e não é coletada se você estiver carregando arquivos locais.

	Desative e desabilite a coleta de telemetria com a variável de ambiente [HF_HUB_DISABLE_TELEMETRY](https://huggingface.co/docs/huggingface_hub/package_reference/environment_variables#hfhubdisabletelemetry).

	```bash
	export HF_HUB_DISABLE_TELEMETRY=1
	```

	```bash
	set HF_HUB_DISABLE_TELEMETRY=1
	```