Buckets:

hf-doc-build
/

doc

Files

xet

hf-doc-build/doc / diffusers /main /es /installation.md

mishig

1 day ago

preview code

download

raw

8.09 kB

# Instalación

Diffusers requiere Python 3.10+ y se prueba con PyTorch 2.6+. Instala [PyTorch](https://pytorch.org/get-started/locally/) según tu sistema y configuración.

Cree un [entorno virtual](https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/) para gestionar proyectos de forma independiente y evitar problemas de compatibilidad entre dependencias. Utilice [uv](https://docs.astral.sh/uv/), un gestor de paquetes y proyectos de Python basado en Rust, para crear un entorno virtual e instalar Diffusers.

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

Instala Diffusers con uno de los siguientes métodos.

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

Para instalar Diffusers con PyTorch en dispositivos NVIDIA Spark (como un portátil RTX Spark) que ejecutan ARM64, instale PyTorch desde el índice PyPI de NVIDIA. Estos dispositivos requieren las compilaciones ARM64 de PyTorch de NVIDIA, que no están disponibles en el índice PyPI predeterminado ni en el índice estándar de ruedas de PyTorch.

Ejecuta el siguiente comando para comprobar si tu sistema detecta una GPU de NVIDIA.

```bash
nvidia-smi
```

Instale PyTorch desde el índice PyPI de NVIDIA y luego instale Diffusers.

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

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

Una instalación desde el código fuente instala la versión `main` en lugar de la versión `stable` más reciente. La versión `main` es útil para mantenerse al día con los últimos cambios, pero no siempre es estable. Si te encuentras con un problema, abre un [Issue](https://github.com/huggingface/diffusers/issues/new/choose) y trataremos de resolverlo lo antes posible.

Asegúrate de que [Accelerate](https://huggingface.co/docs/accelerate/index) esté instalado.

```bash
uv pip install accelerate
```

Instala Diffusers desde el código fuente con el siguiente comando.

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

Instala con extras cuando los necesites. `diffusers["torch"]` descarga PyTorch y Accelerate. Otros extras cubren backends de cuantización, entrenamiento y documentación. Consulta [`setup.py`](https://github.com/huggingface/diffusers/blob/main/setup.py) para la lista completa.

## Dispositivos

Diffusers se ejecuta en cualquier acelerador compatible con PyTorch. Los ejemplos de la documentación utilizan `"cuda"` porque es la configuración más común, pero nada es específico de CUDA. Sustituya la cadena de dispositivo por la de su hardware, como `"xpu"` para GPUs de Intel, `"mps"` para Apple silicon o `"cpu"`.

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

Para seleccionar el dispositivo en tiempo de ejecución en lugar de codificarlo de forma fija, 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"
```

## Instalación editable

Se recomienda una instalación editable para flujos de trabajo de desarrollo o si estás usando la versión `main` del código fuente. Se crea un enlace especial entre el repositorio clonado y las rutas de la biblioteca de Python. Esto evita reinstalar un paquete después de cada cambio.

Clona el repositorio e instala Diffusers con los siguientes comandos.

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

> [!WARNING]
> Debes conservar la carpeta `diffusers` si quieres seguir usando la biblioteca con la instalación editable.

Actualiza tu repositorio clonado a la última versión de Diffusers con el siguiente comando.

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

## Caché

Los pesos y archivos del modelo se descargan desde el Hub en un caché, que normalmente es tu directorio de inicio. Cambia la ubicación del caché con las variables de entorno [HF_HOME](https://huggingface.co/docs/huggingface_hub/package_reference/environment_variables#hfhome) o [HF_HUB_CACHE](https://huggingface.co/docs/huggingface_hub/package_reference/environment_variables#hfhubcache) o configurando el parámetro `cache_dir` en métodos como [from_pretrained()](/docs/diffusers/main/es/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"
)
```

Los archivos en caché le permiten usar Diffusers sin conexión. Establezca la variable de entorno [HF_HUB_OFFLINE](https://huggingface.co/docs/huggingface_hub/package_reference/environment_variables#hfhuboffline) en `1` para evitar que Diffusers se conecte a internet.

```shell
export HF_HUB_OFFLINE=1
```

Para más detalles sobre la gestión y limpieza de la caché, consulte la guía [Comprender la caché](https://huggingface.co/docs/huggingface_hub/guides/manage-cache).

### Compartir archivos entre repositorios

La cachet conserva una copia de un archivo incluso cuando varios repositorios de Hub lo contienen. Muchas tuberías utilizan el mismo codificador de texto, como T5. Si el repositorio de una segunda tubería tiene los mismos archivos de codificador de texto que uno que ya has descargado, [from_pretrained()](/docs/diffusers/main/es/api/pipelines/overview#diffusers.DiffusionPipeline.from_pretrained) utiliza la copia en el disco en lugar de volver a descargarla. Diffusers requiere `huggingface_hub>=1.32.0`, que activa el intercambio de archivos de forma predeterminada.

La caché coincide con los archivos por su hash [Xet](https://huggingface.co/docs/hub/xet/index), no por el nombre del repositorio o del modelo. Un punto de control fragmentado se coincide fragmento por fragmento, por lo que los fragmentos que coinciden se comparten incluso si los demás difieren.

Un archivo se comparte solo cuando se cumplen todas estas condiciones:

- Ambos repositorios almacenan el archivo con Xet.
- Ambas descargas utilizan el mismo directorio de caché, definido por `HF_HUB_CACHE` o `cache_dir`.
- El sistema de archivos admite enlaces simbólicos.
- Los archivos son idénticos byte a byte. Convertir a un dtype diferente, guardar en un formato diferente o redividir en shards cambia el hash.

> [!NOTE]
> Los archivos que descargaste con una versión anterior de `huggingface_hub` no se comparten con las nuevas descargas. Solo se añaden al almacén compartido los archivos descargados con la versión 1.32.0 o posterior.
El intercambio de archivos ahorra tiempo de descarga y espacio en disco, pero no memoria. Para usar un modelo cargado en varios pipelines, consulte [Reutilización de modelos en múltiples pipelines](./using-diffusers/loading#reusing-models-in-multiple-pipelines).
Para desactivar el intercambio de archivos, establezca `HF_HUB_DISABLE_SHARED_BLOBS=1`. La carga sigue funcionando y cada repositorio conserva su propia copia.
```shell
export HF_HUB_DISABLE_SHARED_BLOBS=1
```
## Registro de telemetría
Diffusers recopila información de telemetría durante las solicitudes de [from_pretrained()](/docs/diffusers/main/es/api/pipelines/overview#diffusers.DiffusionPipeline.from_pretrained). Los datos recopilados incluyen la versión de Diffusers y PyTorch, la clase de modelo o pipeline solicitada y la ruta a un checkpoint preentrenado si está alojado en el Hub.
Estos datos de uso nos ayudan a depurar problemas y a priorizar nuevas funciones. La telemetría solo se envía al cargar modelos y pipelines desde el Hub, y no se recopila si estás cargando archivos locales.
Desactive y deshabilite la recopilación de telemetría con la variable de entorno [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:: 8.09 kB
Xet hash:: 8d34eef7630c4b139aadbbfe73e74589c75d812eb0e4f2fd73346315af4c17cb

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

	# Instalación

	Diffusers requiere Python 3.10+ y se prueba con PyTorch 2.6+. Instala [PyTorch](https://pytorch.org/get-started/locally/) según tu sistema y configuración.

	Cree un [entorno virtual](https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/) para gestionar proyectos de forma independiente y evitar problemas de compatibilidad entre dependencias. Utilice [uv](https://docs.astral.sh/uv/), un gestor de paquetes y proyectos de Python basado en Rust, para crear un entorno virtual e instalar Diffusers.

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

	Instala Diffusers con uno de los siguientes métodos.

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

	Para instalar Diffusers con PyTorch en dispositivos NVIDIA Spark (como un portátil RTX Spark) que ejecutan ARM64, instale PyTorch desde el índice PyPI de NVIDIA. Estos dispositivos requieren las compilaciones ARM64 de PyTorch de NVIDIA, que no están disponibles en el índice PyPI predeterminado ni en el índice estándar de ruedas de PyTorch.

	Ejecuta el siguiente comando para comprobar si tu sistema detecta una GPU de NVIDIA.

	```bash
	nvidia-smi
	```

	Instale PyTorch desde el índice PyPI de NVIDIA y luego instale Diffusers.

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

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

	Una instalación desde el código fuente instala la versión `main` en lugar de la versión `stable` más reciente. La versión `main` es útil para mantenerse al día con los últimos cambios, pero no siempre es estable. Si te encuentras con un problema, abre un [Issue](https://github.com/huggingface/diffusers/issues/new/choose) y trataremos de resolverlo lo antes posible.

	Asegúrate de que [Accelerate](https://huggingface.co/docs/accelerate/index) esté instalado.

	```bash
	uv pip install accelerate
	```

	Instala Diffusers desde el código fuente con el siguiente comando.

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

	Instala con extras cuando los necesites. `diffusers["torch"]` descarga PyTorch y Accelerate. Otros extras cubren backends de cuantización, entrenamiento y documentación. Consulta [`setup.py`](https://github.com/huggingface/diffusers/blob/main/setup.py) para la lista completa.

	## Dispositivos

	Diffusers se ejecuta en cualquier acelerador compatible con PyTorch. Los ejemplos de la documentación utilizan `"cuda"` porque es la configuración más común, pero nada es específico de CUDA. Sustituya la cadena de dispositivo por la de su hardware, como `"xpu"` para GPUs de Intel, `"mps"` para Apple silicon o `"cpu"`.

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

	Para seleccionar el dispositivo en tiempo de ejecución en lugar de codificarlo de forma fija, 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"
	```

	## Instalación editable

	Se recomienda una instalación editable para flujos de trabajo de desarrollo o si estás usando la versión `main` del código fuente. Se crea un enlace especial entre el repositorio clonado y las rutas de la biblioteca de Python. Esto evita reinstalar un paquete después de cada cambio.

	Clona el repositorio e instala Diffusers con los siguientes comandos.

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

	> [!WARNING]
	> Debes conservar la carpeta `diffusers` si quieres seguir usando la biblioteca con la instalación editable.

	Actualiza tu repositorio clonado a la última versión de Diffusers con el siguiente comando.

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

	## Caché

	Los pesos y archivos del modelo se descargan desde el Hub en un caché, que normalmente es tu directorio de inicio. Cambia la ubicación del caché con las variables de entorno [HF_HOME](https://huggingface.co/docs/huggingface_hub/package_reference/environment_variables#hfhome) o [HF_HUB_CACHE](https://huggingface.co/docs/huggingface_hub/package_reference/environment_variables#hfhubcache) o configurando el parámetro `cache_dir` en métodos como [from_pretrained()](/docs/diffusers/main/es/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"
	)
	```

	Los archivos en caché le permiten usar Diffusers sin conexión. Establezca la variable de entorno [HF_HUB_OFFLINE](https://huggingface.co/docs/huggingface_hub/package_reference/environment_variables#hfhuboffline) en `1` para evitar que Diffusers se conecte a internet.

	```shell
	export HF_HUB_OFFLINE=1
	```

	Para más detalles sobre la gestión y limpieza de la caché, consulte la guía [Comprender la caché](https://huggingface.co/docs/huggingface_hub/guides/manage-cache).

	### Compartir archivos entre repositorios

	La cachet conserva una copia de un archivo incluso cuando varios repositorios de Hub lo contienen. Muchas tuberías utilizan el mismo codificador de texto, como T5. Si el repositorio de una segunda tubería tiene los mismos archivos de codificador de texto que uno que ya has descargado, [from_pretrained()](/docs/diffusers/main/es/api/pipelines/overview#diffusers.DiffusionPipeline.from_pretrained) utiliza la copia en el disco en lugar de volver a descargarla. Diffusers requiere `huggingface_hub>=1.32.0`, que activa el intercambio de archivos de forma predeterminada.

	La caché coincide con los archivos por su hash [Xet](https://huggingface.co/docs/hub/xet/index), no por el nombre del repositorio o del modelo. Un punto de control fragmentado se coincide fragmento por fragmento, por lo que los fragmentos que coinciden se comparten incluso si los demás difieren.

	Un archivo se comparte solo cuando se cumplen todas estas condiciones:

	- Ambos repositorios almacenan el archivo con Xet.
	- Ambas descargas utilizan el mismo directorio de caché, definido por `HF_HUB_CACHE` o `cache_dir`.
	- El sistema de archivos admite enlaces simbólicos.
	- Los archivos son idénticos byte a byte. Convertir a un dtype diferente, guardar en un formato diferente o redividir en shards cambia el hash.

	> [!NOTE]
	> Los archivos que descargaste con una versión anterior de `huggingface_hub` no se comparten con las nuevas descargas. Solo se añaden al almacén compartido los archivos descargados con la versión 1.32.0 o posterior.

	El intercambio de archivos ahorra tiempo de descarga y espacio en disco, pero no memoria. Para usar un modelo cargado en varios pipelines, consulte [Reutilización de modelos en múltiples pipelines](./using-diffusers/loading#reusing-models-in-multiple-pipelines).

	Para desactivar el intercambio de archivos, establezca `HF_HUB_DISABLE_SHARED_BLOBS=1`. La carga sigue funcionando y cada repositorio conserva su propia copia.

	```shell
	export HF_HUB_DISABLE_SHARED_BLOBS=1
	```

	## Registro de telemetría

	Diffusers recopila información de telemetría durante las solicitudes de [from_pretrained()](/docs/diffusers/main/es/api/pipelines/overview#diffusers.DiffusionPipeline.from_pretrained). Los datos recopilados incluyen la versión de Diffusers y PyTorch, la clase de modelo o pipeline solicitada y la ruta a un checkpoint preentrenado si está alojado en el Hub.

	Estos datos de uso nos ayudan a depurar problemas y a priorizar nuevas funciones. La telemetría solo se envía al cargar modelos y pipelines desde el Hub, y no se recopila si estás cargando archivos locales.

	Desactive y deshabilite la recopilación de telemetría con la variable de entorno [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
	```