Hub documentation
Utilisation des images Docker
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 besoin | Point de départ |
|---|---|
| Exécuter un script Python avec ses dépendances déclarées | hf jobs uv run script.py |
| Utiliser des outils ou des paquets Python déjà installés dans une image | hf jobs run IMAGE COMMAND |
| Exécuter un script avec des dépendances gérées par uv et des outils système supplémentaires | hf 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,--helpplacé 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.jsonlRemplacez 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
ffmpegou 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 -versionLa 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.
| Image | Ce qu'il fournit |
|---|---|
pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel | PyTorch et un environnement de développement CUDA, utilisés dans l’exemple ci-dessus. |
huggingface/trl | TRL, Transformers, PyTorch et uv pour le post-entraînement et les charges de travail Python associées. |
vllm/vllm-openai | vLLM, 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--pythoncré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 vllmde 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.PYTHONPATHest 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 pasPYTHONPATHpour 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-packagesqui permettrait de passer l’étapePYTHONPATHest 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.pyCes 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.pyuv 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