Usando imagens Docker

Cada Job é executado dentro de uma imagem Docker, que fornece seu ambiente de software, incluindo ferramentas de sistema e bibliotecas instaladas. Com hf jobs run, você fornece uma imagem e um comando. Com hf jobs uv run, o uv prepara o ambiente Python para o seu script, e o Jobs seleciona uma imagem padrão, a menos que você especifique uma.

Escolha como executar sua carga de trabalho

Comece com hf jobs uv run quando as dependências do seu script Python puderem ser instaladas com uv, conforme mostrado no Quickstart. Escolha uma imagem quando precisar de ferramentas de sistema adicionais ou quiser usar um ambiente de software preparado.

A imagem padrão inclui Python e uv. Consulte Configuração de Jobs UV para a imagem padrão atual e as opções disponíveis.

Você pode usar uma imagem existente de um registro, como o Docker Hub, ou construir e hospedar sua própria imagem com um Docker Space.

Use uma imagem pronta

Use hf jobs run com uma imagem e o comando a ser executado dentro dela. Qualquer imagem pública do Docker Hub ou de outro registro funciona, incluindo uma tag específica. Comece com uma pequena:

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

O Job faz o pull da imagem, executa o comando e encerra. Para usar um software que uma imagem já fornece, escolha uma imagem que o inclua. Por exemplo, use uma imagem do PyTorch para criar um tensor em uma GPU e dobrar seus 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)'

A imagem fornece o PyTorch e sua pilha de software CUDA. --flavor t4-small seleciona a GPU, --timeout 5m limita o tempo de execução do Job e o comando Python usa o pacote PyTorch instalado na imagem. Sua saída aparece nos logs do Job.

-- separa as opções de Jobs do comando e seus argumentos. Por exemplo, --help após esse separador é passado ao seu comando. Consulte Passando argumentos.

Execute seu próprio script com arquivos de entrada e saída

Um script executado por hf jobs run deve estar disponível dentro do Job. Você pode usar um script incluído na imagem ou montar um diretório local.

Por exemplo, suponha que você tenha um script de inferência que usa os pacotes Transformers e PyTorch na imagem huggingface/trl. Seu diretório local work contém inference.py e inputs.jsonl, e o script aceita os caminhos --input e --output. Após criar um Storage Bucket para os resultados, execute-o com:

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

Substitua YOUR_USERNAME pelo namespace do proprietário do bucket. O CLI faz o upload do diretório local e o monta em /work. Seu script lê a entrada ali e grava os resultados no bucket montado em /output, onde eles permanecem disponíveis após a conclusão do Job. Adapte os argumentos do comando, o hardware e o timeout ao seu script; consulte Volumes para outras opções de entrada e saída.

Use uma imagem com uv

Use hf jobs uv run --image quando o seu script precisar de ferramentas de sistema além da imagem padrão, mantendo o fluxo de trabalho de dependências Python do uv. A imagem escolhida deve ter o uv instalado.

O ambiente é composto por três partes:

• Ferramentas e bibliotecas de sistema na imagem, como ffmpeg ou o toolkit CUDA, estão disponíveis para o Job de acordo com a configuração da imagem.
• Os pacotes Python instalados na imagem pertencem ao seu ambiente Python existente.
• Dependências do script. Com um cabeçalho de dependência inline, o uv instala seus pacotes Python em um ambiente isolado. Pacotes pré-instalados na imagem não estão automaticamente disponíveis.

Por exemplo, um script do vLLM pode precisar de uma imagem com as ferramentas da CUDA, ao mesmo tempo em que usa o uv para instalar suas próprias dependências Python declaradas. As ferramentas do sistema ainda devem ser compatíveis com os pacotes que o uv instala.

Se você deseja usar diretamente o PyTorch, TRL ou vLLM pré-instalados em uma imagem, use hf jobs run. Se você também precisar do uv para instalar dependências extras, consulte Reutilize os pacotes da imagem e adicione dependências com uv.

Crie sua própria imagem com um Espaço Docker

Um Docker Space pode compilar e hospedar uma imagem com as ferramentas necessárias para a sua carga de trabalho, incluindo os seus próprios scripts, e a imagem pode ser privada sem uma conta de registro. Por exemplo, adicione FFmpeg a uma imagem Python para preparar um ambiente para processar áudio ou vídeo.

Crie um Docker Space e adicione este Dockerfile na raiz do repositório dele:

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 fornece o Python. O FFmpeg não está incluído nesta imagem base, portanto RUN o instala no momento da compilação. useradd cria um usuário com um diretório home e UID 1000, correspondente ao Docker Spaces; USER executa os comandos como esse usuário. CMD define um comando padrão, aqui verificando a instalação do FFmpeg.

Commit o arquivo e aguarde até que os logs de build do Space mostrem que a imagem foi enviada. Em seguida, passe a URL do Space no lugar onde normalmente você colocaria o nome de uma imagem, substituindo YOUR_USERNAME/video-tools pelo ID do seu Space:

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

A versão aparece nos logs do Job. Forneça um comando diferente após a URL do Space para usar FFmpeg ou Python para sua carga de trabalho. Para incluir seu próprio script na imagem, adicione uma linha como COPY --chown=user:user process.py /app/process.py ao Dockerfile e execute python /app/process.py. Consulte arquivos de entrada e saída para montar dados e salvar resultados.

Este exemplo imprime uma versão e sai, então o Space exibe um erro de tempo de execução após o build. Isso é aceitável: os Jobs precisam apenas da imagem construída, não de um Space em execução.

A imagem construída por um Space não é garantida como sempre disponível para download. Ela pode ser perdida devido à manutenção do registro ou a uma mudança de região. Se um Job reportar que a imagem não foi encontrada, reinicie o Space pela fábrica para reconstruí-la. Os Jobs sempre usam a construção mais recente, portanto, um novo commit também substitui a imagem.

Imagens de exemplo

As imagens do registro são mantidas por seus publicadores e podem ser fixadas em uma tag específica.

Use hf jobs run para executar comandos com os pacotes instalados na imagem. Para hf jobs uv run, verifique se a imagem tem o uv instalado e siga as orientações de ambiente acima. Navegue por Exemplos e Tutoriais para encontrar cargas de trabalho para executar e adaptar.

Reutilize os pacotes da imagem e adicione dependências com uv

As imagens de framework fornecem pacotes pré-instalados que podem ser lentos ou difíceis de compilar, como PyTorch, vLLM e suas extensões CUDA. Você ainda pode precisar de pacotes Python adicionais para seu script — por exemplo, para carregar um formato de dados específico ou rastrear experimentos.

Você pode reutilizar a pilha pré-instalada da imagem enquanto usa o uv para instalar esses extras. Declare os pacotes adicionais no cabeçalho de dependências # /// script do seu script, depois aponte o uv para o interpretador da imagem e adicione seus site-packages ao caminho de importação:

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 cria o ambiente do uv com o interpretador da imagem, correspondendo à versão do Python usada pelas extensões compiladas. Ele não expõe os pacotes da imagem por si só.
• -e PYTHONPATH=... faz com que import vllm resolva para a build pré-compilada da imagem para aquela execução.
• Reduza as dependências do seu # /// script para o que a imagem não possui. PYTHONPATH é pesquisado antes do ambiente do uv, portanto a imagem ofusca qualquer coisa que seu cabeçalho declare para o mesmo pacote — incluindo uma versão mais nova que você fixou. As dependências que você retém ainda podem puxar esses pacotes transitivamente; o uv não usa PYTHONPATH para satisfazer a resolução de dependências.

Os caminhos variam para cada imagem, portanto, verifique-os em cpu-basic em vez de codificá-los diretamente:

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

Substitua vllm pela biblioteca que você estiver reutilizando. Os layouts variam — vllm/vllm-openai e lmsysorg/sglang usam o sistema dist-packages acima, unsloth/unsloth usa um virtualenv (/opt/venv/...) e huggingface/trl usa conda (/opt/conda/lib/python3.11/site-packages, herdado de pytorch/pytorch).

Isso seleciona os builds da imagem para imports, não para o resolver de dependências do uv. Reduzir o cabeçalho pode diminuir instalações redundantes, mas não garante que sejam eliminadas. Um uv run --system-site-packages que pularia a etapa PYTHONPATH está solicitado upstream.

Para a imagem huggingface/trl, os caminhos correspondentes do interpretador e dos pacotes são:

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

Estes comandos usam generate-responses.py e train.py como nomes para os seus próprios scripts.

Solução de problemas

Usando imagens de framework para bibliotecas de GPU

Algumas bibliotecas de GPU exigem ferramentas de sistema adicionais, como o compilador CUDA (nvcc), NCCL ou cuDNN. A instalação de seus pacotes Python não garante que a imagem contenha todas as ferramentas necessárias. Por exemplo, o sampler do FlashInfer pode falhar ao tentar compilar um kernel em uma imagem sem o toolkit do CUDA:

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

Passar uma imagem de framework com as ferramentas CUDA necessárias resolve esse erro de toolkit ausente:

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

O uv ainda resolve e instala as dependências do seu script separadamente. A imagem fornece as ferramentas de sistema, mas não garante que os pacotes Python resolvidos sejam compatíveis com ela.