Hub documentation

Utilisation des images Docker

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Utilisation des images Docker

Chaque Job s’exécute dans une image Docker, qui fournit son environnement logiciel, y compris les outils système et les bibliothèques installées. Avec hf jobs run, vous fournissez une image et une commande. Avec hf jobs uv run, uv prépare l’environnement Python pour votre script, et Jobs sélectionne une image par défaut à moins que vous n’en spécifiiez une.

Choisissez comment exécuter votre charge de travail

Commencez par hf jobs uv run lorsque les dépendances de votre script Python peuvent être installées avec uv, comme indiqué dans le Démarrage rapide. Choisissez une image lorsque vous avez besoin d’outils système supplémentaires ou souhaitez utiliser un environnement logiciel préparé.

De quoi vous avez besoinPoint de départ
Exécuter un script Python avec ses dépendances déclaréeshf jobs uv run script.py
Utiliser des outils ou des paquets Python déjà installés dans une imagehf jobs run IMAGE COMMAND
Exécuter un script avec des dépendances gérées par uv et des outils système supplémentaireshf jobs uv run --image IMAGE script.py

L’image par défaut inclut Python et uv. Consultez Configuration des jobs UV pour connaître l’image par défaut actuelle et les options disponibles.

Vous pouvez utiliser une image existante depuis un registre tel que Docker Hub, ou construire et héberger votre propre image avec un Docker Space.

Utiliser une image prête à l'emploi

Utilisez hf jobs run avec une image et la commande à exécuter à l’intérieur. Toute image publique de Docker Hub ou d’un autre registre fonctionne, y compris avec un tag spécifique. Commencez par une petite image :

hf jobs run ubuntu echo 'Hello from the cloud!'

Le Job récupère l'image, exécute la commande et se termine. Pour utiliser un logiciel déjà fourni par une image, choisissez une image qui l'inclut. Par exemple, utilisez une image PyTorch pour créer un tenseur sur un GPU et doubler ses valeurs :

hf jobs run --flavor t4-small --timeout 5m \
    pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel \
    -- python -c 'import torch; x = torch.ones(3, device="cuda"); print(x * 2)'

L’image fournit PyTorch et sa pile logicielle CUDA. --flavor t4-small sélectionne le GPU, --timeout 5m limite la durée d’exécution du Job, et la commande Python utilise le paquet PyTorch installé dans l’image. Sa sortie apparaît dans les journaux du Job.

-- sépare les options des Jobs de la commande et de ses arguments. Par exemple, --help placé après ce séparateur est transmis à votre commande. Voir Passage d’arguments.

Exécuter votre propre script avec des fichiers d'entrée et de sortie

Un script exécuté par hf jobs run doit être disponible à l’intérieur du Job. Vous pouvez utiliser un script inclus dans l’image ou monter un répertoire local.

Par exemple, supposez que vous disposiez d'un script d'inférence utilisant les packages Transformers et PyTorch dans l'image huggingface/trl. Votre répertoire local work contient inference.py et inputs.jsonl, et le script accepte les chemins --input et --output. Après avoir créé un Storage Bucket pour les résultats, exécutez-le avec :

hf jobs run --flavor t4-small --timeout 10m \
    -v ./work:/work \
    -v hf://buckets/YOUR_USERNAME/results:/output \
    huggingface/trl \
    -- python /work/inference.py --input /work/inputs.jsonl --output /output/results.jsonl

Remplacez YOUR_USERNAME par l’espace de noms du propriétaire du bucket. Le CLI télécharge le répertoire local et le monte sur /work. Votre script lit l’entrée à cet endroit et écrit les résultats dans le bucket monté sur /output, où ils restent disponibles après la fin du Job. Adaptez les arguments de la commande, le matériel et le délai d’expiration à votre script ; consultez Volumes pour d’autres options d’entrée et de sortie.

Utiliser une image avec uv

Utilisez hf jobs uv run --image lorsque votre script a besoin d’outils système au-delà de l’image par défaut, tout en conservant le flux de travail de dépendances Python de uv. L’image choisie doit avoir uv installé.

L'environnement se compose de trois parties :

  • Les outils système et les bibliothèques de l’image, tels que ffmpeg ou le kit CUDA, sont disponibles pour le Job selon la configuration de l’image.
  • Les paquets Python installés dans l'image appartiennent à son environnement Python existant.
  • Dépendances du script. Avec un en-tête de dépendances en ligne, uv installe vos paquets Python dans un environnement isolé. Les paquets préinstallés dans l’image ne sont pas automatiquement disponibles.

Par exemple, un script vLLM peut nécessiter une image avec les outils CUDA tout en utilisant uv pour installer ses propres dépendances Python déclarées. Les outils système doivent néanmoins rester compatibles avec les paquets installés par uv.

Si vous souhaitez utiliser directement PyTorch, TRL ou vLLM préinstallés dans une image, utilisez hf jobs run. Si vous avez également besoin de uv pour installer des dépendances supplémentaires, consultez Réutiliser les packages de l’image et ajouter des dépendances avec uv.

Créez votre propre image avec un espace Docker

Un Space Docker peut construire et héberger une image dotée des outils nécessaires à votre charge de travail, y compris vos propres scripts, et cette image peut être privée sans compte de registre. Par exemple, ajoutez FFmpeg à une image Python pour préparer un environnement de traitement audio ou vidéo.

Créez un Docker Space et ajoutez ce Dockerfile à la racine de son dépôt :

FROM python:3.12-slim-bookworm

# Install FFmpeg for audio and video processing.
RUN apt-get update \
    && apt-get install -y --no-install-recommends ffmpeg \
    && rm -rf /var/lib/apt/lists/*

# Match the non-root user ID used by Docker Spaces.
RUN useradd --create-home --uid 1000 user
USER user

# Check that FFmpeg is available.
CMD ["ffmpeg", "-version"]

FROM fournit Python. FFmpeg n’est pas inclus dans cette image de base, RUN l’installe donc au moment de la construction. useradd crée un utilisateur avec un répertoire personnel et l’UID 1000, en cohérence avec Docker Spaces ; USER exécute les commandes en tant que cet utilisateur. CMD définit une commande par défaut, ici une vérification de l’installation de FFmpeg.

Committez le fichier et attendez que les journaux de build de l’espace indiquent que l’image a été poussée. Passez ensuite l’URL de l’espace à l’endroit où vous mettriez normalement un nom d’image, en remplaçant YOUR_USERNAME/video-tools par l’identifiant de votre espace :

hf jobs run --flavor cpu-basic --timeout 5m \
    hf.co/spaces/YOUR_USERNAME/video-tools -- ffmpeg -version

La version apparaît dans les journaux du Job. Fournissez une commande différente après l’URL du Space pour utiliser FFmpeg ou Python pour votre charge de travail. Pour inclure votre propre script dans l’image, ajoutez une ligne telle que COPY --chown=user:user process.py /app/process.py au Dockerfile et exécutez python /app/process.py. Consultez fichiers d’entrée et de sortie pour monter les données et enregistrer les résultats.

Cet exemple affiche une version puis se termine, de sorte que le Space affiche une erreur d’exécution après la construction. Ce n’est pas un problème : les Jobs n’ont besoin que de l’image construite, pas d’un Space en cours d’exécution.

L’image construite par un Space n’est pas garantie de rester accessible. Elle peut être perdue lors d’une maintenance du registre ou d’un déplacement de région. Si un Job signale que l’image n’a pas été trouvée, redémarrez le Space en usine pour la reconstruire. Les Jobs utilisent toujours la dernière version construite, de sorte qu’un nouveau commit remplace également l’image.

Images d'exemple

Les images du registre sont maintenues par leurs éditeurs et peuvent être épinglées à un tag spécifique.

ImageCe qu'il fournit
pytorch/pytorch:2.6.0-cuda12.4-cudnn9-develPyTorch et un environnement de développement CUDA, utilisés dans l’exemple ci-dessus.
huggingface/trlTRL, Transformers, PyTorch et uv pour le post-entraînement et les charges de travail Python associées.
vllm/vllm-openaivLLM, uv et les outils CUDA pour l’inférence de LLM.

Utilisez hf jobs run pour exécuter des commandes avec les packages installés dans l’image. Pour hf jobs uv run, vérifiez que l’image a uv installé et suivez les recommandations d’environnement ci-dessus. Parcourez les Exemples et tutoriels pour des charges de travail à exécuter et à adapter.

Réutiliser les paquets de l’image et ajouter des dépendances avec uv

Les images de framework fournissent des paquets préinstallés dont la compilation peut être lente ou difficile, tels que PyTorch, vLLM et leurs extensions CUDA. Il est possible que vous ayez encore besoin de paquets Python supplémentaires pour votre script — par exemple, pour charger un format de données particulier ou suivre des expériences.

Vous pouvez réutiliser la pile préinstallée de l’image tout en utilisant uv pour installer ces extras. Déclarez les paquets supplémentaires dans l’en-tête de dépendances # /// script de votre script, puis indiquez à uv l’interpréteur de l’image et ajoutez ses site-packages au chemin d’importation :

hf jobs uv run \
    --image vllm/vllm-openai \
    --flavor l4x4 \
    --python /usr/bin/python3 \
    -e PYTHONPATH=/usr/local/lib/python3.12/dist-packages \
    -s HF_TOKEN \
    generate-responses.py
  • --python crée l’environnement uv avec l’interpréteur de l’image, correspondant à la version de Python utilisée par ses extensions compilées. Il n’expose pas les paquets de l’image par lui-même.
  • -e PYTHONPATH=... permet à import vllm de résoudre vers la compilation préconstruite de l’image pour cette exécution.
  • Réduisez les dépendances de votre # /// script à ce que l’image ne contient pas. PYTHONPATH est consulté avant l’environnement de uv, de sorte que l’image masque tout ce que votre en-tête déclare pour le même paquet — y compris une version plus récente que vous avez épinglée. Les dépendances que vous conservez peuvent toujours tirer ces paquets de manière transitive ; uv n’utilise pas PYTHONPATH pour résoudre les dépendances.

Les chemins diffèrent d'une image à l'autre, il est donc préférable de les tester sur cpu-basic plutôt que de les coder en dur :

hf jobs run --flavor cpu-basic vllm/vllm-openai bash -c 'which python3; which uv; python3 -m pip show vllm | grep Location'
/usr/bin/python3                              # pass to --python
/usr/local/bin/uv                             # uv is present, so `uv run` works
Location: /usr/local/lib/python3.12/dist-packages   # pass to PYTHONPATH

Remplacez vllm par la bibliothèque que vous réutilisez. Les emplacements varient — vllm/vllm-openai et lmsysorg/sglang utilisent le système dist-packages ci-dessus, unsloth/unsloth utilise un virtualenv (/opt/venv/...), et huggingface/trl utilise conda (/opt/conda/lib/python3.11/site-packages, hérité de pytorch/pytorch).

Cela sélectionne les builds de l’image pour les imports, et non pour le résolveur de dépendances de uv. Réduire l’en-tête peut diminuer les installations redondantes, mais ne garantit pas leur élimination. Une commande uv run --system-site-packages qui permettrait de passer l’étape PYTHONPATH est demandée en amont.

Pour l’image huggingface/trl, les chemins de l’interpréteur et des packages correspondants sont :

hf jobs uv run \
    --image huggingface/trl \
    --flavor a100-large \
    --python /opt/conda/bin/python3 \
    -e PYTHONPATH=/opt/conda/lib/python3.11/site-packages \
    -s HF_TOKEN \
    train.py

Ces commandes utilisent generate-responses.py et train.py comme noms pour vos propres scripts.

Dépannage

Utilisation des images de framework pour les bibliothèques GPU

Certain bibliothèques GPU nécessitent des outils système supplémentaires, tels que le compilateur CUDA (nvcc), NCCL ou cuDNN. L’installation de leurs paquets Python ne garantit pas que l’image contient tous les outils dont elles ont besoin. Par exemple, le sampler de FlashInfer peut échouer lorsqu’il tente de compiler un noyau dans une image sans le kit de développement CUDA :

RuntimeError: Could not find nvcc and default cuda_home='/usr/local/cuda' doesn't exist

Passer une image de framework avec les outils CUDA requis permet de résoudre cette erreur de toolkit manquant :

hf jobs uv run --image vllm/vllm-openai --flavor l4x4 -s HF_TOKEN generate-responses.py

uv résout et installe toujours les dépendances de votre script séparément. L’image fournit les outils système, mais ne garantit pas que les paquets Python résolus sont compatibles avec ceux-ci.

Update on GitHub