Uso de imágenes de Docker

Cada Job se ejecuta dentro de una imagen de Docker, que proporciona su entorno de software, incluidas las herramientas del sistema y las bibliotecas instaladas. Con hf jobs run, proporcionas una imagen y un comando. Con hf jobs uv run, uv prepara el entorno de Python para tu script, y Jobs selecciona una imagen predeterminada a menos que especifiques una.

Elija cómo ejecutar su carga de trabajo

Comience con hf jobs uv run cuando las dependencias de su script de Python se puedan instalar con uv, como se muestra en el Quickstart. Elija una imagen cuando necesite herramientas de sistema adicionales o desee usar un entorno de software preparado.

La imagen predeterminada incluye Python y uv. Consulte Configuración de UV Jobs para conocer la imagen predeterminada actual y las opciones disponibles.

Puede utilizar una imagen existente de un registro como Docker Hub, o construir y alojar su propia imagen con un Docker Space.

Usar una imagen lista para usar

Use hf jobs run con una imagen y el comando para ejecutar dentro de ella. Cualquier imagen pública de Docker Hub u otro registro funciona, incluida una etiqueta específica. Comience con una pequeña:

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

El Job descarga la imagen, ejecuta el comando y finaliza. Para usar software que una imagen ya proporciona, elige una imagen que lo incluya. Por ejemplo, usa una imagen de PyTorch para crear un tensor en una GPU y duplicar sus valores:

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)'

La imagen proporciona PyTorch y su pila de software CUDA. --flavor t4-small selecciona la GPU, --timeout 5m limita el tiempo de ejecución del Job y el comando de Python utiliza el paquete de PyTorch instalado en la imagen. Su salida aparece en los registros del Job.

-- separa las opciones de Jobs del comando y sus argumentos. Por ejemplo, --help después de este separador se pasa a tu comando. Consulta Pasar argumentos.

Ejecuta tu propio script con archivos de entrada y salida

Un script ejecutado por hf jobs run debe estar disponible dentro del Job. Puede usar un script incluido en la imagen o montar un directorio local.

Por ejemplo, supongamos que tienes un script de inferencia que utiliza los paquetes Transformers y PyTorch en la imagen huggingface/trl. Tu directorio local work contiene inference.py y inputs.jsonl, y el script acepta las rutas --input y --output. Después de crear un Storage Bucket para los resultados, ejecútalo con:

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

Reemplaza YOUR_USERNAME con el espacio de nombres del propietario del bucket. La CLI sube el directorio local y lo monta en /work. Tu script lee la entrada allí y escribe los resultados en el bucket montado en /output, donde permanecen disponibles después de que el Job finalice. Adapta los argumentos del comando, el hardware y el timeout a tu script; consulta Volumes para otras opciones de entrada y salida.

Usar una imagen con uv

Usa hf jobs uv run --image cuando tu script necesite herramientas de sistema más allá de la imagen predeterminada, manteniendo el flujo de trabajo de dependencias de Python de uv. La imagen elegida debe tener uv instalado.

El entorno tiene tres partes:

• Las herramientas y bibliotecas del sistema en la imagen, como ffmpeg o el kit de herramientas de CUDA, están disponibles para el Job según la configuración de la imagen.
• Los paquetes de Python instalados en la imagen pertenecen a su entorno de Python existente.
• Dependencias del script. Con una cabecera de dependencias en línea, uv instala tus paquetes de Python en un entorno aislado. Los paquetes preinstalados en la imagen no están disponibles automáticamente.

Por ejemplo, un script de vLLM puede necesitar una imagen con herramientas de CUDA mientras usa uv para instalar sus propias dependencias de Python declaradas. Las herramientas del sistema deben ser compatibles con los paquetes que instala uv.

Si deseas usar directamente el PyTorch, TRL o vLLM preinstalados en una imagen, usa hf jobs run. Si además necesitas uv para instalar dependencias adicionales, consulta Reutiliza los paquetes de la imagen y añade dependencias con uv.

Crea tu propia imagen con un Docker Space

Un Espacio de Docker puede construir y alojar una imagen con las herramientas que necesita su carga de trabajo, incluidos sus propios scripts, y la imagen puede ser privada sin una cuenta de registro. Por ejemplo, agregue FFmpeg a una imagen de Python para preparar un entorno para procesar audio o video.

Crea un Docker Space y añade este Dockerfile en la raíz de su repositorio:

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 proporciona Python. FFmpeg no está incluido en esta imagen base, por lo que RUN lo instala en tiempo de compilación. useradd crea un usuario con un directorio de inicio y UID 1000, coincidiendo con Docker Spaces; USER ejecuta los comandos como ese usuario. CMD establece un comando predeterminado, en este caso, comprueba la instalación de FFmpeg.

Compite el archivo y espere a que los registros de compilación del Space indiquen que la imagen se ha enviado. Luego, pase la URL del Space donde normalmente colocaría un nombre de imagen, reemplazando YOUR_USERNAME/video-tools con el ID de su Space:

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

La versión aparece en los registros del Job. Proporcione un comando diferente después de la URL del Space para usar FFmpeg o Python para su carga de trabajo. Para incluir su propio script en la imagen, agregue una línea como COPY --chown=user:user process.py /app/process.py al Dockerfile y ejecute python /app/process.py. Consulte archivos de entrada y salida para montar datos y guardar resultados.

Este ejemplo imprime una versión y sale, por lo que el Space muestra un error de tiempo de ejecución después de la compilación. No hay problema: los Jobs solo necesitan la imagen compilada, no un Space en ejecución.

La imagen construida de un Space no está garantizada para permanecer disponible para su descarga. Puede perderse debido al mantenimiento del registro o a un cambio de región. Si un Job informa que la imagen no se encontró, reinicie el Space de fábrica para reconstruirla. Los Jobs siempre utilizan la última compilación, por lo que un nuevo commit también reemplaza la imagen.

Imágenes de ejemplo

Las imágenes del registro son mantenidas por sus editores y pueden fijarse a una etiqueta específica.

Use hf jobs run para ejecutar comandos con los paquetes instalados en la imagen. Para hf jobs uv run, verifique que la imagen tenga uv instalado y siga las indicaciones de entorno anteriores. Consulte Ejemplos y tutoriales para ver cargas de trabajo que puede ejecutar y adaptar.

Reutiliza los paquetes de la imagen y añade dependencias con uv

Las imágenes de framework incluyen paquetes preinstalados que pueden ser lentos o difíciles de compilar, como PyTorch, vLLM y sus extensiones de CUDA. Es posible que aún necesites paquetes adicionales de Python para tu script, por ejemplo, para cargar un formato de datos específico o para hacer seguimiento de experimentos.

Puedes reutilizar el stack preinstalado de la imagen mientras usas uv para instalar esos extras. Declara los paquetes adicionales en la cabecera de dependencias # /// script de tu script, luego apunta uv al intérprete de la imagen y añade sus site-packages a la ruta de importación:

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 crea el entorno de uv con el intérprete de la imagen, coincidiendo con la versión de Python utilizada por sus extensiones compiladas. Por sí solo, no expone los paquetes de la imagen.
• -e PYTHONPATH=... hace que import vllm resuelva en la compilación precompilada de la imagen para esa ejecución.
• Recorta las dependencias de # /// script a lo que la imagen no incluye. PYTHONPATH se busca antes que el entorno de uv, por lo que la imagen oculta cualquier cosa que tu encabezado declare para el mismo paquete, incluida una versión más nueva que fijaste. Las dependencias que conserves aún pueden traer esos paquetes de forma transitoria; uv no usa PYTHONPATH para satisfacer la resolución de dependencias.

Las rutas difieren según la imagen, por lo que es mejor probarlas en cpu-basic en lugar de codificarlas de forma fija:

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

Sustituye vllm por la biblioteca que estés reutilizando. Los diseños varían: vllm/vllm-openai y lmsysorg/sglang utilizan el sistema dist-packages anterior, unsloth/unsloth utiliza un virtualenv (/opt/venv/...) y huggingface/trl utiliza conda (/opt/conda/lib/python3.11/site-packages, heredado de pytorch/pytorch).

Esto selecciona las compilaciones de la imagen para las importaciones, no para el resolutor de dependencias de uv. Recortar el encabezado puede reducir las instalaciones redundantes, pero no garantiza que se eliminen. Se ha solicitado aguas arriba un uv run --system-site-packages que omita el paso de PYTHONPATH.

Para la imagen huggingface/trl, las rutas correspondientes del intérprete y los paquetes son:

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

Estos comandos usan generate-responses.py y train.py como nombres para tus propios scripts.

Solución de problemas

Uso de imágenes de frameworks para bibliotecas de GPU

Algunas bibliotecas de GPU requieren herramientas de sistema adicionales, como el compilador de CUDA (nvcc), NCCL o cuDNN. La instalación de sus paquetes de Python no garantiza que la imagen contenga todas las herramientas que necesitan. Por ejemplo, el muestreador de FlashInfer puede fallar cuando intenta compilar un kernel en una imagen sin el kit de herramientas de CUDA:

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

Pasar una imagen de framework con las herramientas de CUDA necesarias resuelve este error de toolkit ausente:

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

uv sigue resolviendo e instalando las dependencias de tu script por separado. La imagen proporciona las herramientas del sistema, pero no garantiza que los paquetes de Python resueltos sean compatibles con ellas.