Configuração

Autenticação

Você precisa estar autenticado com hf auth login para executar Jobs e usar um token com permissão para iniciar e gerenciar Jobs.

Alternativamente, passe um token do Hugging Face manualmente com --token na CLI, ou o argumento token em Python.

Passando argumentos

Use -- para separar as opções de Jobs do seu comando ou script e de seus argumentos. Opções após --, como --help ou --timeout, são transmitidas em vez de serem interpretadas pelos Jobs. Isso se aplica tanto aos Jobs UV quanto aos Jobs Docker.

hf jobs uv run --flavor t4-small -- script.py --early-stopping-patience 3
               └─ Jobs option ┘    └─ script + arguments ─────────────┘

UV Jobs

Especifique o script UV ou o comando python a ser executado, como você faria com o UV:

>>> hf jobs uv run train.py

>>> hf jobs uv run python -c 'print("Hello from the cloud!")'

O comando hf jobs uv run aceita um argumento UV como --with e --python. O argumento --with permite especificar dependências do python, e --python permite escolher a versão do python a ser usada:

>>> hf jobs uv run --with trl train.py
>>> hf jobs uv run --python 3.12 train.py

Por exemplo, passe argumentos para um comando usando --:

>>> hf jobs uv run --with trl-jobs -- trl-jobs sft --model_name Qwen/Qwen3-0.6B --dataset_name trl-lib/Capybara

Encontre a lista de todos os argumentos na documentação da CLI e na documentação dos Comandos UV.

Por padrão, os UV Jobs são executados com a imagem Docker ghcr.io/astral-sh/uv:python3.12-bookworm, mas você pode usar outra imagem, desde que tenha o UV instalado, usando --image <docker-image>.

Consulte Usando imagens Docker para escolher uma imagem e entender como seu ambiente interage com as dependências do UV.

Defina a configuração de lançamento no script

Um script que só é executado corretamente em um runtime específico (uma determinada imagem, tipo de GPU ou interpretador de sistema) pode carregar essa configuração com ele, em uma tabela opcional [tool.hf-jobs] no cabeçalho PEP 723:

# /// script
# requires-python = ">=3.11"
# dependencies = ["vllm", "datasets"]
#
# [tool.hf-jobs]
# image   = "vllm/vllm-openai:unlimited-ocr"
# flavor  = "l4x1"
# python  = "/usr/bin/python3"
# secrets = ["HF_TOKEN"]
# ///

hf jobs uv run ocr.py em seguida inicia na imagem e no hardware correspondentes. Um simples uv run ignora a tabela, pois as tabelas [tool.*] fazem parte do PEP 723 e as ferramentas ignoram as que não são delas.

Chaves suportadas, todas opcionais: image, flavor, python, timeout, name, namespace, env, secrets, labels, volumes, network_group e network_aliases. Elas correspondem às flags de mesmo nome. Os valores do script são padrões: uma flag explícita sempre prevalece, e env, secrets, labels e volumes são mesclados entrada por entrada, de modo que -e e -v adicionam ao que o script declara. Uma chave desconhecida é um erro, e secrets lista apenas nomes: os valores vêm do ambiente de quem executa o script, e um segredo que não está definido localmente também é um erro.

Use --dry-run para exibir a configuração resolvida sem enviar; os valores que vêm do script são marcados como (from script). Consulte o guia da CLI hf para as regras de mesclagem completas.

A tabela é lida apenas pelo CLI hf. run_uv_job() e create_scheduled_uv_job() a ignoram, portanto, passe image=, flavor=, … explicitamente a partir do Python.

Docker Jobs

Especifique a imagem do Docker e o comando a ser executado, como você faria com o docker:

>>> hf jobs run ubuntu echo "Hello from the cloud!"

Aqui, --help atinge o Python em vez de exibir a ajuda dos Jobs:

>>> hf jobs run --flavor cpu-basic python:3.12 -- python --help

Encontre a lista de todos os argumentos na documentação da CLI.

Veja Usando imagens Docker para exemplos usando imagens existentes e imagens criadas por Docker Spaces.

Variáveis de ambiente e Segredos

Variáveis de ambiente integradas

Assim como as variáveis de ambiente integradas em Spaces, os Jobs fornecem automaticamente as seguintes variáveis de ambiente dentro do contêiner:

Você pode usar essas variáveis para acompanhar as saídas, adaptar seu código aos recursos disponíveis ou referenciar o trabalho atual programaticamente:

# Access job environment information
>>> hf jobs run python:3.12 python -c "import os; print(f'Job: {os.environ.get(\"JOB_ID\")}, CPU: {os.environ.get(\"CPU_CORES\")}, Mem: {os.environ.get(\"MEMORY\")}')"

Variáveis de ambiente definidas pelo usuário

Você pode passar variáveis de ambiente para seu trabalho usando

# Pass environment variables
>>> hf jobs uv run -e FOO=foo -e BAR=bar python -c 'import os; print(os.environ["FOO"], os.environ["BAR"])'

# Pass an environment from a local .env file
>>> hf jobs uv run --env-file .env python -c 'import os; print(os.environ["FOO"], os.environ["BAR"])'

# Pass secrets - they will be encrypted server side
>>> hf jobs uv run -s MY_SECRET=psswrd python -c 'import os; print(os.environ["MY_SECRET"])'

# Pass secrets from a local .env.secrets file - they will be encrypted server side
>>> hf jobs uv run --secrets-file .env.secrets python -c 'import os; print(os.environ["MY_SECRET"])'

Use --secrets HF_TOKEN para passar seu token local do Hugging Face implicitamente. Com essa sintaxe, o segredo é recuperado da variável de ambiente. Para HF_TOKEN, ele pode ler o arquivo de token localizado na pasta home do Hugging Face se a variável de ambiente não estiver definida.

Volumes

Monte repositórios do Hugging Face (modelos, conjuntos de dados), Storage Buckets ou diretórios locais como volumes no contêiner do seu job usando -v ou --volume. As fontes do Hub usam o esquema de URL hf://: hf://[TYPE/]SOURCE:/MOUNT_PATH[:ro]; um diretório local é passado diretamente como a fonte.

Como os arquivos montados são obtidos de forma preguiçosa, a montagem permite que um Job trabalhe com conjuntos de dados muito maiores do que o disco local. Consulte Process Large Datasets para obter informações sobre montagem, streaming e processamento de grandes volumes de dados em Jobs.

Tipos de volume:

Em seguida, use o volume montado como um diretório local dentro do contêiner:

# Mount a dataset and query it with DuckDB
>>> hf jobs run -v hf://datasets/stanfordnlp/imdb:/dataset \
...     duckdb/duckdb duckdb -c "SELECT * FROM '/dataset/**/*.parquet' LIMIT 5"

# Mount a bucket to save training checkpoints
>>> hf jobs uv run -v hf://buckets/username/my-bucket:/training-outputs \
...     sft.py --output-dir /training-outputs/training-v3-final

Vários volumes podem ser montados repetindo a flag -v:

>>> hf jobs run -v hf://datasets/username/my-dataset:/data -v hf://buckets/username/my-bucket:/output \
...     python:3.12 python script.py

Modelos e conjuntos de dados são sempre montados em modo somente leitura. Os buckets de armazenamento são leitura e escrita por padrão, o que é útil para salvar saídas, checkpoints ou resultados intermediários. Use :ro para montar um bucket em modo somente leitura:

>>> hf jobs run -v hf://buckets/username/my-bucket:/mnt:ro python:3.12 ls /mnt

Diretórios locais

Ao passar um diretório local como origem, ele é sincronizado para o seu Storage Bucket privado jobs-artifacts (criado automaticamente) antes de o Job iniciar e, em seguida, montado no container. Diretórios locais são montados somente leitura por padrão; use :rw para gravar saídas:

>>> hf jobs uv run -v ./pdfs:/input -v ./md-out:/output:rw ocr.py

A re-sincronização do mesmo diretório faz upload apenas de novos ou arquivos modificados. Para recuperar os arquivos que um Job escreveu em um volume de leitura e escrita, sincronize a pasta do bucket de volta quando o Job terminar — a CLI exibe o comando exato hf buckets sync quando o Job inicia. Jobs agendados também funcionam: o diretório é sincronizado uma vez quando o agendamento é criado, e cada acionamento monta a mesma pasta. Em Python, use sync_job_volume.

Em Python, use a classe Volume:

from huggingface_hub import Volume, run_job

job = run_job(
    image="python:3.12",
    command=["python", "-c", "import os; print(os.listdir('/data'))"],
    volumes=[
        Volume(type="dataset", source="username/my-dataset", mount_path="/data"),
        Volume(type="bucket", source="username/my-bucket", mount_path="/output"),
    ],
)

O montamento de volumes requer huggingface_hub >= 1.8.0. Consulte a documentação do cliente Python e o guia de instalação para mais detalhes.

Flavor de hardware

Execute jobs em GPUs ou TPUs com o argumento flavor. Por exemplo, para executar um job do PyTorch em uma GPU A10G:

>>> hf jobs uv run --with torch --flavor a10g-small python -c "import torch; print(f'This code ran with the following GPU: {torch.cuda.get_device_name()}')"

Ao executar isso, a seguinte saída será exibida!

This code ran with the following GPU: NVIDIA A10G

Aqui está outro exemplo para executar um script de ajuste fino como trl/scripts/sft.py:

>>> hf jobs uv run --with trl --flavor a10g-small -s HF_TOKEN -- sft.py --model_name_or_path Qwen/Qwen2-0.5B ...

Para orientações completas sobre a execução de trabalhos de treinamento de modelos com TRL na infraestrutura do Hugging Face, consulte a documentação de Treinamento de Jobs do TRL. Ela aborda receitas de fine-tuning, seleção de hardware e melhores práticas para treinar modelos de forma eficiente.

Veja a lista de opções de --flavor disponíveis usando o comando hf jobs hardware (o padrão é cpu-basic):

>>> hf jobs hardware
name             pretty name             cpu       ram      storage   accelerator               cost/min  cost/hour
cpu-basic        CPU Basic               2 vCPU    16 GB    50 GB                               $0.0002   $0.01
cpu-upgrade      CPU Upgrade             8 vCPU    32 GB    50 GB                               $0.0005   $0.03
cpu-performance  CPU Performance         32 vCPU   256 GB   1024 GB                             $0.0317   $1.90
cpu-xl           CPU XL                  16 vCPU   124 GB   1000 GB                             $0.0167   $1.00
t4-small         Nvidia T4 - small       4 vCPU    15 GB    50 GB     1x T4 (16 GB)             $0.0067   $0.40
t4-medium        Nvidia T4 - medium      8 vCPU    30 GB    100 GB    1x T4 (16 GB)             $0.0100   $0.60
a10g-small       Nvidia A10G - small     4 vCPU    15 GB    110 GB    1x A10G (24 GB)           $0.0167   $1.00
a10g-large       Nvidia A10G - large     12 vCPU   46 GB    200 GB    1x A10G (24 GB)           $0.0250   $1.50
a10g-largex2     2x Nvidia A10G - large  24 vCPU   92 GB    1000 GB   2x A10G (48 GB)           $0.0500   $3.00
a10g-largex4     4x Nvidia A10G - large  48 vCPU   184 GB   2000 GB   4x A10G (96 GB)           $0.0833   $5.00
a100-large       Nvidia A100 - large     12 vCPU   142 GB   1000 GB   1x A100 (80 GB)           $0.0417   $2.50
a100x4           4x Nvidia A100          48 vCPU   568 GB   4000 GB   4x A100 (320 GB)          $0.1667   $10.00
a100x8           8x Nvidia A100          96 vCPU   1136 GB  8000 GB   8x A100 (640 GB)          $0.3333   $20.00
h200             Nvidia H200             23 vCPU   256 GB   3000 GB   1x H200 (141 GB)          $0.0833   $5.00
h200x2           Nvidia H200             46 vCPU   512 GB   6000 GB   2x H200 (282 GB)          $0.1667   $10.00
h200x4           Nvidia H200             92 vCPU   1024 GB  12000 GB  4x H200 (564 GB)          $0.3333   $20.00
h200x8           Nvidia H200             184 vCPU  2048 GB  24000 GB  8x H200 (1128 GB)         $0.6667   $40.00
rtx-pro-6000     Nvidia RTX PRO 6000     23 vCPU   256 GB   475 GB    1x RTX PRO 6000 (96 GB)   $0.0458   $2.75
rtx-pro-6000x2   Nvidia RTX PRO 6000     46 vCPU   512 GB   950 GB    2x RTX PRO 6000 (192 GB)  $0.0917   $5.50
rtx-pro-6000x4   Nvidia RTX PRO 6000     92 vCPU   1024 GB  1900 GB   4x RTX PRO 6000 (384 GB)  $0.1833   $11.00
rtx-pro-6000x8   Nvidia RTX PRO 6000     184 vCPU  2048 GB  3800 GB   8x RTX PRO 6000 (768 GB)  $0.3667   $22.00
l4x1             1x Nvidia L4            8 vCPU    30 GB    400 GB    1x L4 (24 GB)             $0.0133   $0.80
l4x4             4x Nvidia L4            48 vCPU   186 GB   3200 GB   4x L4 (96 GB)             $0.0633   $3.80
l40sx1           1x Nvidia L40S          8 vCPU    62 GB    380 GB    1x L40S (48 GB)           $0.0300   $1.80
l40sx4           4x Nvidia L40S          48 vCPU   382 GB   3200 GB   4x L40S (192 GB)          $0.1383   $8.30
l40sx8           8x Nvidia L40S          192 vCPU  1534 GB  6500 GB   8x L40S (384 GB)          $0.3917   $23.50

Expor Portas

Os jobs podem expor portas de contêiner por meio do proxy público de jobs usando --expose <port> (CLI) ou expose=[<port>] (API Python). Cada porta exposta é acessível em https://<job_id>--<port>.hf.jobs e requer um token HF com acesso read ao namespace do job:

curl -H "Authorization: Bearer $HF_TOKEN" https://<job_id>--<port>.hf.jobs/

Isso funciona em hf jobs run, hf jobs uv run e nas suas variantes agendadas. Repita a flag para expor múltiplas portas (--expose 8000 --expose 8001) ou passe várias portas na lista (expose=[8000, 8001]).

Para tornar uma porta acessível sem um token do HF, use --expose-public <port> (CLI) ou expose_public=[<port>] (API Python) no lugar. Qualquer pessoa que tenha a URL poderá acessar a porta, portanto, use essa opção apenas para um serviço que seja seguro para compartilhar. Você pode combinar ambas as opções: algumas portas então exigem um token do HF e outras são públicas.

As portas expostas são cobradas por uma pequena taxa fixa horária, acrescida ao preço do hardware do job, apenas enquanto o job estiver em execução. Consulte a página de preços para mais detalhes.

CLI

# Expose a web server running on port 8000
>>> hf jobs run --expose 8000 python:3.12 python -m http.server 8000
✓ Job started
  id: 6a2aa7cec4f53f9fc5aa4cff
  url: https://huggingface.co/jobs/Wauplin/6a2aa7cec4f53f9fc5aa4cff
Hint: Exposed ports are reachable at (requires an HF token with read access to the job):
  https://6a2aa7cec4f53f9fc5aa4cff--8000.hf.jobs
Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/) ...

Python

>>> from huggingface_hub import run_job
>>> job = run_job(image="python:3.12", command=["python", "-m", "http.server", "8000"], expose=[8000])
>>> job.status.expose_urls
['https://6a2ab384c4f53f9fc5aa4d4f--8000.hf.jobs']

Alterar as portas de um Job em execução

Use hf jobs expose para alterar as portas expostas, sem reiniciar o Job:

# Expose port 8000 (requires an HF token)
>>> hf jobs expose <job_id> 8000

# Expose port 8000 (requires an HF token) and port 9000 publicly
>>> hf jobs expose <job_id> 8000 --public 9000

# Close all exposed ports
>>> hf jobs expose <job_id> --clear

O comando substitui a lista completa de portas expostas, portanto, uma porta que você deixar de fora será fechada. Em Python, use update_job_expose.

SSH

Você pode abrir uma sessão SSH interativa em um Job em execução para depurar, inspecionar ou trabalhar diretamente dentro do container. Ative-o na criação do job com --ssh (CLI) ou ssh=True (API Python) e, em seguida, conecte-se com hf jobs ssh <job_id>.

Apenas usuários com acesso de escrita ao namespace do Job são permitidos (ou seja, o criador do Job ou membros da organização proprietária com permissões de escrita). A autenticação é realizada por meio de chaves públicas SSH registradas em https://huggingface.co/settings/keys.

O SSH está disponível em hf jobs run e hf jobs uv run. Não é suportado para agendamentos.

CLI

# Start a job with SSH enabled
>>> hf jobs run --ssh --detach --timeout 10m python:3.12 sleep infinity
✓ Job started
  id: 6a2bd1f1871c005b5352ad31
  url: https://huggingface.co/jobs/Wauplin/6a2bd1f1871c005b5352ad31
Hint: Use `hf jobs ssh 6a2bd1f1871c005b5352ad31` to open an SSH session into the job.

# Open an SSH session into the job
>>> hf jobs ssh 6a2bd1f1871c005b5352ad31

Você também pode imprimir o comando SSH sem executá-lo (--dry-run) ou passar um arquivo de identidade específico (-i/--identity-file):

>>> hf jobs ssh 6a2bd1f1871c005b5352ad31 --dry-run
ssh 6a2bd1f1871c005b5352ad31@ssh.hf.jobs

>>> hf jobs ssh 6a2bd1f1871c005b5352ad31 -i ~/.ssh/id_ed25519

Python

>>> from huggingface_hub import run_job
>>> job = run_job(image="python:3.12", command=["sleep", "infinity"], ssh=True)
>>> job.status.ssh_url
'ssh://6a2bd1f1871c005b5352ad31@ssh.hf.jobs'

Em seguida, conecte-se de um terminal com hf jobs ssh <job_id> ou diretamente com ssh <job_id>@ssh.hf.jobs.

Encaminhamento de portas

Como esta é uma conexão SSH comum, você pode usar as flags -L e -R do SSH para encaminhar portas entre sua máquina e o Job. Conecte-se diretamente com ssh (use hf jobs ssh <job_id> --dry-run para obter o destino exato) e adicione as flags de encaminhamento.

Use -L (encaminhamento local) para acessar um serviço em execução dentro do Job a partir da sua máquina. Por exemplo, para acessar um TensorBoard iniciado em um Job de treinamento:

# Forward local port 6006 to the Job's TensorBoard on port 6006
>>> ssh -L 6006:localhost:6006 6a2bd1f1871c005b5352ad31@ssh.hf.jobs

Em seguida, abra http://localhost:6006 no seu navegador.

Use -R (encaminhamento remoto) para permitir que o Job acesse um serviço em execução na sua máquina. Por exemplo, para expor um banco de dados ou API local ao Job:

# Make your local port 8080 reachable from inside the Job on port 8080
>>> ssh -R 8080:localhost:8080 6a2bd1f1871c005b5352ad31@ssh.hf.jobs

Grupos de rede

Os jobs podem entrar em um grupo de rede usando --network-group <name> (CLI) ou network_group="<name>" (API Python). Jobs no mesmo namespace e grupo de recursos que compartilham um grupo podem se alcançar em todas as portas: HF_NETWORK_GROUP_HOSTNAME é resolvido para todos os membros, e ${HF_NETWORK_GROUP_PREFIX}<alias> para os membros que reivindicaram um alias com --network-alias <alias> (CLI) ou network_aliases=[<alias>] (API Python).

Isso funciona em hf jobs run e hf jobs uv run. Os membros são resolúveis antes de ficarem prontos, portanto, conecte-se com novas tentativas. Os nomes de grupo e os aliases são alfanuméricos minúsculos e hífens, com no máximo 46 e 34 caracteres, respectivamente; os aliases de um job devem ser únicos.

CLI

# Start a server, reachable by the other members of the group as "master"
>>> hf jobs run --detach --network-group train --network-alias master python:3.12 python -m http.server 8000

# Start a client in the same group
>>> hf jobs run --detach --network-group train python:3.12 sh -c 'curl --retry 10 --retry-connrefused "http://${HF_NETWORK_GROUP_PREFIX}master:8000/"'

Python

>>> from huggingface_hub import run_job
>>> server = run_job(
...     image="python:3.12",
...     command=["python", "-m", "http.server", "8000"],
...     network_group="train",
...     network_aliases=["master"],
... )
>>> client = run_job(
...     image="python:3.12",
...     command=["sh", "-c", 'curl --retry 10 --retry-connrefused "http://${HF_NETWORK_GROUP_PREFIX}master:8000/"'],
...     network_group="train",
... )

Frameworks de treinamento multi-nó podem usar um alias como host de rendezvous, por exemplo, torchrun --master_addr "${HF_NETWORK_GROUP_PREFIX}master".

Timeout

Os jobs possuem um tempo limite padrão (30 minutos), após o qual eles param automaticamente. É importante saber disso ao executar tarefas de longa duração, como o treinamento de modelos.

Você pode especificar um valor de timeout personalizado usando o parâmetro --timeout ao executar um job. O timeout pode ser especificado de duas maneiras:

1. Como um número (interpretado como segundos):

Use --timeout e passe o número em segundos (aqui 2 horas = 7200 segundos):

>>> hf jobs uv run --timeout 7200 --with torch --flavor a10g-large train.py

2. Como uma string com unidades de tempo:

Ou use --timeout e utilize diferentes unidades de tempo:

>>> hf jobs uv run --timeout 2h --with torch --flavor a10g-large train.py

Outros exemplos:

--timeout 30m    # 30 minutes
--timeout 1.5h   # 1.5 hours
--timeout 1d     # 1 day
--timeout 3600s  # 3600 seconds

Unidades de tempo suportadas:

• s - segundos
• m - minutos
• h - horas
• d - dias

Se você não especificar um tempo limite, um tempo limite padrão será aplicado ao seu job. Para tarefas de longa duração, como o treinamento de modelos que podem levar horas, certifique-se de definir um tempo limite adequado para evitar encerramentos inesperados do job.

Tentativas

Por padrão, um Job é executado uma única vez. Use --attempts <n> (CLI) ou attempts=<n> (API Python) para tentar novamente um Job que falha. O número inclui a primeira execução, portanto --attempts 3 permite até duas novas tentativas:

>>> hf jobs uv run --attempts 3 --flavor a10g-large train.py

Isso funciona em hf jobs run, hf jobs uv run e nas suas variantes agendadas.

Uma nova tentativa executa o comando novamente do início, sob o mesmo ID de Job. Para permitir que uma nova tentativa retome de onde a tentativa anterior parou, escreva checkpoints em um bucket montado e faça com que seu script retome a partir deles. Consulte Após o término em Treinar Modelos em Jobs.

Namespace

Execute Jobs na conta da sua organização usando o argumento --namespace. Certifique-se de que você está conectado com um token que tenha permissão para iniciar e gerenciar Jobs na conta da sua organização.

>>> hf jobs uv run --namespace my-org-name python -c "print('Running in an org account')"

Observe que você pode passar manualmente um token com a permissão adequada:

>>> hf jobs uv run --namespace my-org-name --token hf_xxx python -c "print('Running in an org account')"

Rótulos

Adicione um ou mais rótulos a um Job para incluir metadados com -l ou --label. Você pode usar esses metadados posteriormente para filtrar Jobs no site ou na CLI.

Adicione rótulos com --label my-label ou rótulos chave-valor com --label key=value. As chaves e os valores podem conter letras, dígitos, - e _. Por exemplo:

hf jobs uv run --label fine-tuning --label model=Qwen3-06B --label dataset=Capybara ...

Observe que usar a mesma key várias vezes faz com que o último key=value sobrescreva e descarte qualquer rótulo anterior com key.

Nomear um Job

Dê um nome ao Job para facilitar sua localização e identificação na interface. O nome é armazenado como o rótulo name e não precisa ser único. Na interface, os Jobs serão agrupados por nome.

hf jobs run --name daily-report python:3.12 python report.py

Se você não passar --name, o Job recebe o nome da sua imagem Docker ou script mais um hash curto do comando, de modo que reexecuções do mesmo comando compartilham o mesmo nome, enquanto comandos diferentes recebem nomes diferentes (por exemplo, python-3-12-6b9d662c para um Job executado em python:3.12).

Atualizar rótulos

Atualize os rótulos de um Job existente com hf jobs labels. Passar --label substitui todos os rótulos existentes; passar apenas --name os mantém:

# Replace the labels on a Job
hf jobs labels <job_id> --label env=prod --label team=ml

# Name an existing Job (keeps its other labels)
hf jobs labels <job_id> --name daily-report

# Remove all labels from a Job
hf jobs labels <job_id> --clear