Hub

API docs

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

Início rápido

Execute seu código Python em CPUs e GPUs da Hugging Face. Neste guia, você executará um comando simples em uma CPU e, em seguida, gerará texto com um pequeno modelo de linguagem em uma GPU.

Você precisará de uma conta do Hugging Face com créditos pré-pagos. Consulte Pricing and Billing para os custos de computação.

1. Configure o CLI

Instale o Hugging Face CLI e, em seguida, faça login na sua conta:

>>> hf auth login

2. Execute Hello World

Execute este comando no seu terminal:

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

hf jobs uv run executa o comando em um ambiente Python na infraestrutura do Hugging Face. Ele usa uma CPU por padrão e transmite os logs do Job para o seu terminal. Após a inicialização, você verá:

Hello from the cloud!

A CLI também exibe o ID do seu Job e um link para a página dele. Abra o link para visualizar seu status e logs no navegador. Você pode encontrar seus Jobs novamente na sua página de Jobs ou usar o ID com os comandos de CLI abaixo.

Os jobs também podem executar um comando em qualquer imagem Docker:

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

O restante deste guia usa hf jobs uv run. Consulte Usando imagens Docker para saber quando e como usar uma imagem.

3. Executar um modelo em uma GPU

Execute este script preparado para gerar um nome de robô. Você pode visualizá-lo no GitHub ou ler o código abaixo.

hf jobs uv run \
    --flavor t4-small \
    --timeout 5m \
    https://raw.githubusercontent.com/huggingface/hub-docs/main/examples/jobs/hello_gpu.py

--flavor t4-small seleciona uma máquina com uma GPU NVIDIA T4.
--timeout 5m define um limite de cinco minutos para o Job.

O Job baixa o modelo e imprime sua resposta nos logs. Por exemplo:

RoboLearnbot

Aqui está o script completo:

# /// script
# dependencies = ["torch", "transformers"]
# ///

from transformers import pipeline

generator = pipeline(
    "text-generation",
    model="HuggingFaceTB/SmolLM2-360M-Instruct",
    dtype="float16",
)
messages = [{
    "role": "user",
    "content": "Suggest a name for a robot that helps people learn Python. Answer with only the name.",
}]
outputs = generator(messages, max_new_tokens=48, do_sample=False, return_full_text=False)
print(outputs[0]["generated_text"])

O cabeçalho de dependências informa ao uv para instalar torch e transformers no Job. Você também pode especificar dependências com --with. Você só precisa do CLI hf localmente.

O script executa o SmolLM2-360M-Instruct na GPU do Job. max_new_tokens limita o comprimento da resposta.

O tempo de inicialização varia conforme a disponibilidade de hardware, a instalação de dependências e os downloads de modelos.

Pressionar Ctrl+C interrompe o streaming de logs; o Job continua em execução. Para parar o Job, use hf jobs cancel JOB_ID, substituindo JOB_ID pelo ID exibido pelo CLI.

Você também pode iniciar o mesmo Job a partir do Python com o cliente huggingface_hub:

from huggingface_hub import run_uv_job

job = run_uv_job(
    "https://raw.githubusercontent.com/huggingface/hub-docs/main/examples/jobs/hello_gpu.py",
    flavor="t4-small",
    timeout="5m",
)
print(job.url)

4. Verifique seu resultado

Use o ID do Job de GPU para verificar seu status e ler seus logs novamente:

>>> hf jobs inspect JOB_ID
>>> hf jobs logs JOB_ID

Uma execução bem-sucedida tem o status COMPLETED e seus logs contêm a resposta gerada.

A resposta continua disponível nos logs do Job após a conclusão. Ao adaptar o script para gerar arquivos, salve esses resultados em um bucket ou repositório do Hub para que eles persistam após o Job.

Tente o seu próprio script (opcional)

Copie o código acima para hello_gpu.py, edite o prompt em messages e execute seu arquivo local:

hf jobs uv run --flavor t4-small --timeout 5m hello_gpu.py

O CLI faz o upload do seu script editado automaticamente. Substitua hello_gpu.py pelo seu caminho, caso você o tenha salvo em outro local.

Próximas etapas

Construa sobre este exemplo com uma carga de trabalho maior:

Update on GitHub

←Visão geral dos trabalhos Preços e Cobranças→