Installation

Diffusers nécessite Python 3.10+ et est testé avec PyTorch 2.6+. Installez PyTorch en fonction de votre système et de votre configuration.

Créez un environnement virtuel pour une gestion plus aisée des projets distincts et pour éviter les problèmes de compatibilité entre les dépendances. Utilisez uv, un gestionnaire de paquets et de projets Python basé sur Rust, pour créer un environnement virtuel et installer Diffusers.

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

Installez Diffusers à l'aide de l'une des méthodes suivantes.

uv pip install diffusers["torch"] transformers

nvidia-smi

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

conda install -c conda-forge diffusers

uv pip install accelerate

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

Installez les extras lorsque vous en avez besoin. diffusers["torch"] installe PyTorch et Accelerate. D’autres extras couvrent les backends de quantification, l’entraînement et la documentation. Consultez setup.py pour la liste complète.

Appareils

Diffusers fonctionne sur tout accélérateur pris en charge par PyTorch. Les exemples tout au long de la documentation utilisent "cuda" car c'est la configuration la plus courante, mais rien n'est spécifique à CUDA. Remplacez la chaîne de caractères du dispositif par celle correspondant à votre matériel, par exemple "xpu" pour les GPU Intel, "mps" pour la puce Apple, ou "cpu".

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

Pour sélectionner l'appareil à l'exécution plutôt que de le coder en dur, utilisez torch.accelerator.

import torch

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

Installation modifiable

Une installation en mode éditable est recommandée pour les flux de travail de développement ou si vous utilisez la version main du code source. Un lien spécial est créé entre le dépôt cloné et les chemins de la bibliothèque Python. Cela évite de réinstaller le paquet après chaque modification.

Clonez le dépôt et installez Diffusers à l'aide des commandes suivantes.

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

Vous devez conserver le dossier diffusers si vous souhaitez continuer à utiliser la bibliothèque avec l'installation en mode éditable.

Mettez à jour votre dépôt cloné vers la dernière version de Diffusers avec la commande ci-dessous.

cd ~/diffusers/
git pull

Cache

Les poids et fichiers du modèle sont téléchargés depuis le Hub vers un cache, généralement situé dans votre répertoire personnel. Modifiez l’emplacement du cache à l’aide des variables d’environnement HF_HOME ou HF_HUB_CACHE, ou en configurant le paramètre cache_dir dans des méthodes telles que from_pretrained().

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

from diffusers import DiffusionPipeline

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

Les fichiers en cache vous permettent d’utiliser Diffusers hors ligne. Définissez la variable d’environnement HF_HUB_OFFLINE sur 1 pour empêcher Diffusers de se connecter à Internet.

export HF_HUB_OFFLINE=1

Pour plus de détails sur la gestion et le nettoyage du cache, consultez le guide Comprendre la mise en cache.

Partager des fichiers entre les dépôts

Le cache conserve une seule copie d’un fichier, même lorsque plusieurs dépôts du Hub le contiennent. De nombreuses pipelines utilisent le même encodeur de texte, comme T5. Si le dépôt d’une seconde pipeline contient les mêmes fichiers d’encodeur de texte que ceux que vous avez déjà téléchargés, from_pretrained() utilise la copie présente sur le disque au lieu de la télécharger à nouveau. Diffusers exige huggingface_hub>=1.32.0, qui active le partage de fichiers par défaut.

Le cache associe les fichiers à leur hachage Xet, et non au nom du dépôt ou du modèle. Un point de contrôle fractionné est associé fraction par fraction, de sorte que les fractions qui correspondent sont partagées, même si les autres diffèrent.

Un fichier est partagé uniquement si toutes ces conditions sont remplies :

• Les deux dépôts stockent le fichier avec Xet.
• Les deux téléchargements utilisent le même répertoire de cache, défini par HF_HUB_CACHE ou cache_dir.
• Le système de fichiers prend en charge les liens symboliques.
• Les fichiers sont identiques octet par octet. Convertir en un autre dtype, enregistrer dans un autre format ou répartitionner modifie l'empreinte.

Les fichiers téléchargés avec une version antérieure de huggingface_hub ne sont pas partagés avec les nouveaux téléchargements. Seuls les fichiers téléchargés avec la version 1.32.0 ou ultérieure sont ajoutés au magasin partagé.

Le partage de fichiers réduit le temps de téléchargement et l’espace disque, mais pas la mémoire. Pour utiliser un modèle chargé dans plusieurs pipelines, consultez Réutilisation de modèles dans plusieurs pipelines.

Pour désactiver le partage de fichiers, définissez HF_HUB_DISABLE_SHARED_BLOBS=1. Le chargement fonctionne toujours et chaque dépôt conserve sa propre copie.

export HF_HUB_DISABLE_SHARED_BLOBS=1

Journalisation de la télémétrie

Diffusers collecte des informations de télémétrie lors des requêtes from_pretrained(). Les données collectées incluent la version de Diffusers et de PyTorch, la classe de modèle ou de pipeline demandée, et le chemin vers un point de contrôle préentraîné s’il est hébergé sur le Hub.

Ces données d’utilisation nous aident à déboguer les problèmes et à prioriser les nouvelles fonctionnalités. La télémétrie n’est envoyée que lors du chargement de modèles et de pipelines depuis le Hub, et elle n’est pas collectée si vous chargez des fichiers locaux.

Désactivez la collecte de télémétrie avec la variable d’environnement HF_HUB_DISABLE_TELEMETRY.

export HF_HUB_DISABLE_TELEMETRY=1

set HF_HUB_DISABLE_TELEMETRY=1