Hub Python Library documentation
Interface de Linha de Comando (CLI)
Interface de Linha de Comando (CLI)
O pacote Python huggingface_hub inclui uma CLI integrada chamada hf. Essa ferramenta permite interagir com o Hugging Face Hub diretamente de um terminal. Por exemplo, você pode fazer login na sua conta, criar um repositório, enviar e baixar arquivos, etc. Ela também vem com recursos úteis para configurar sua máquina ou gerenciar seu cache. Neste guia, vamos dar uma olhada nos principais recursos da CLI e em como usá-los.
Este guia aborda os recursos mais importantes da CLI
hf. Para uma referência completa de todos os comandos e opções, consulte a referência da CLI.
Usando o CLI
hfcom agentes de IA? Instale o Skill e confira o guia Hugging Face CLI for AI Agents.# works with Claude Code, Codex, Cursor, OpenCode, Pi and any agent that loads skills from `.agents/skills` hf skills addO instalador independente instala para você (veja abaixo) e
hf updateo atualiza.
Começando
Instalador independente (Recomendado)
Você pode instalar o CLI hf com um único comando:
No macOS e no Linux:
>>> curl -LsSf https://hf.co/cli/install.sh | bashNo Windows:
>>> powershell -ExecutionPolicy ByPass -c "irm https://hf.co/cli/install.ps1 | iex"O instalador também instala a habilidade hf-cli globalmente, para o Claude Code e qualquer agente que leia ~/.agents/skills. Passe --exclude-skill para ignorá-la:
>>> curl -LsSf https://hf.co/cli/install.sh | bash -s -- --exclude-skill>>> powershell -ExecutionPolicy ByPass -c "& ([scriptblock]::Create((irm https://hf.co/cli/install.ps1))) -ExcludeSkill"Depois de instalado, você pode verificar se o CLI está configurado corretamente:
>>> hf --help
Usage: hf [OPTIONS] COMMAND [ARGS]...
Hugging Face Hub CLI
Options:
--skills Print the `hf-cli` SKILL.md to stdout (alias for `hf skills preview`).
--install-completion Install completion for the current shell.
--show-completion Show completion for the current shell, to copy it or customize the installation.
-h, --help Show this message and exit.
Main commands:
auth Manage authentication (login, logout, etc.).
buckets Commands to interact with buckets.
cache Manage local cache directory.
collections Interact with collections on the Hub.
datasets Interact with datasets on the Hub.
download Download files from the Hub.
endpoints Manage Hugging Face Inference Endpoints.
extensions Manage hf CLI extensions.
jobs Run and manage Jobs on the Hub.
models Interact with models on the Hub.
papers Interact with papers on the Hub.
repos Manage repos on the Hub.
skills Manage skills for AI assistants.
spaces Interact with spaces on the Hub.
sync Sync files between local directory and a bucket.
upload Upload a file or a folder to the Hub.
Help commands:
env Print information about the environment.
version Print information about the hf version.Se o CLI estiver instalado corretamente, você deve ver uma lista de todas as opções disponíveis no CLI. Se receber uma mensagem de erro como command not found: hf, consulte o guia de Instalação.
A opção
--helpé muito útil para obter mais detalhes sobre um comando. Você pode usá-la a qualquer momento para listar todas as opções disponíveis e seus detalhes. Por exemplo,hf upload --helpfornece mais informações sobre como enviar arquivos usando a CLI.
Usando uv
A maneira mais fácil de usar o CLI hf é com uvx. Ele sempre executa a versão mais recente em um ambiente isolado - sem necessidade de instalação!
Certifique-se de que o uv está instalado primeiro. Consulte o guia de instalação do uv para obter instruções.
Em seguida, use a CLI diretamente:
>>> uvx hf auth login
>>> uvx hf download
>>> uvx hf ...
uvx hfusa o pacotehfdo PyPI.
Instale com pip
A CLI também é distribuída com o pacote principal huggingface_hub:
>>> pip install -U "huggingface_hub"Usando o Homebrew
Você também pode instalar o CLI usando o Homebrew:
>>> brew install hfConfira a página do huggingface no Homebrew aqui para mais detalhes.
Atualizando
Para atualizar para a versão mais recente, execute:
>>> hf updateIsso detecta como o hf foi instalado (Homebrew, instalador independente ou pip) e executa o comando de atualização correspondente. Se a skill hf-cli estiver instalada globalmente, ela também será atualizada para que os agentes vejam a nova superfície de comandos. Se não estiver, ela permanecerá desinstalada: a atualização nunca a reinstala se você a ignorou ou removeu.
Por padrão, a CLI também exibe um aviso amarelo de uma linha no stderr quando uma versão mais recente está disponível no PyPI. Para silenciá-lo (por exemplo, em CI offline), defina HF_HUB_DISABLE_UPDATE_CHECK=1.
Formatação da saída
A maioria dos comandos hf aceita o mesmo conjunto de flags globais de formatação. Elas são documentadas em uma seção dedicada Formatting options em todas as páginas --help e podem ser adicionadas a qualquer comando sem a necessidade de declará-las por comando:
| Flag | Equivalente | Descrição |
|---|---|---|
--format <value> | — | Escolha explicitamente o formato de saída. Valores aceitos: auto (padrão), human, agent, json, quiet. |
--json | --format json | Imprime JSON estruturado. Útil para encaminhar para jq ou outros scripts. |
-q, --quiet | --format quiet | Imprime apenas os IDs (um por linha). Útil para encaminhar IDs para outros comandos. |
--no-truncate | — | Exibir os valores completos nas tabelas humanas em vez de encurtar valores longos com .... A tabela pode exceder a largura do terminal. Use --format json para saída estruturada de colunas de lista/dicionário. |
auto (o padrão) seleciona human para um terminal interativo e agent quando a CLI é invocada por um agente de IA. human adiciona cores e tabelas formatadas; agent produz valores separados por tabulação sem truncamento; json emite um objeto ou array JSON compacto. Misturar duas flags de modo de saída (por exemplo, --json junto com --format human) gera um erro de uso.
Tabelas humanas se ajustam automaticamente à largura do seu terminal: as colunas mais largas são encurtadas apenas quando as larguras naturais excedem a tela (portanto, em um terminal largo, você geralmente vê os valores completos sem ...). Passe --no-truncate para forçar valores completos independentemente da largura; use --format json para saída estruturada de colunas de lista/dicionário.
# JSON output for scripting
>>> hf models ls --search bert --limit 2 --json | jq '.[].id'
# IDs only, one per line
>>> hf collections ls --owner nvidia -q
nvidia/nemotron-supervised-fine-tuning-69eab9824c9120a3a3b1e25e
nvidia/nvidia-nemotron-v3-69388dda16167bb1607171eahf auth login
Em muitos casos, é necessário estar conectado a uma conta do Hugging Face para interagir com o Hub (baixar repositórios privados, enviar arquivos, criar PRs, etc.). Para isso, execute o seguinte comando no seu terminal:
>>> hf auth loginSe você já estiver conectado, este comando ignorará o prompt e exibirá uma mensagem. Para forçar o relogin (por exemplo, para alternar tokens), use --force:
>>> hf auth login --forcePor padrão, o comando faz login com o seu navegador: ele imprime uma URL e um código curto. Abra a URL, insira o código, aprove a solicitação e o CLI recupera e salva um token de acesso na sua máquina. O token expira após um tempo, mas é renovado automaticamente enquanto você continuar usando-o.
? How would you like to log in? [Use arrows, Enter to confirm]
> Log in with your browser
Paste an access token
Open this URL in your browser:
https://huggingface.co/oauth/device
And enter the code: ABCD-EFGH
Waiting for authorization...
Token is valid.
The token `oauth-wauplin` has been saved to /home/wauplin/.cache/huggingface/stored_tokens
Your token has been saved to /home/wauplin/.cache/huggingface/token
Login successful.Você também pode escolher colar um User Access Token gerado na sua página de Configurações, seja de forma interativa (selecione Paste an access token) ou diretamente pela linha de comando. Para mais segurança, recomendamos passar seu token como uma variável de ambiente para evitar colá-lo no histórico de comandos.
# Or using an environment variable
>>> hf auth login --token $HF_TOKEN --add-to-git-credential
Token is valid (permission: write).
The token `token_name` has been saved to /home/wauplin/.cache/huggingface/stored_tokens
Your token has been saved in your configured git credential helpers (store).
Your token has been saved to /home/wauplin/.cache/huggingface/token
Login successful
The current active token is: `token_name`Quando executado por um agente de IA (detectado automaticamente, ou com --format agent), o comando nunca solicita confirmação: ele executa o fluxo do navegador e imprime instruções simples que o agente pode repassar ao usuário, e então aguarda a autorização:
>>> hf auth login --format agent
Ask the user to open https://huggingface.co/oauth/device in a browser and enter the code ABCD-EFGH. The code expires in 900 seconds. Waiting for authorization...
Login successful: logged in as wauplin (token saved as 'oauth-wauplin').hf auth login é interativo, portanto --format json e --format quiet não são suportados: use --token para logins em scripts, não interativos.
Para mais detalhes sobre autenticação, consulte esta seção.
hf auth whoami
Se você deseja saber se está conectado, pode usar hf auth whoami. Este comando não possui opções e simplesmente exibe seu nome de usuário e as organizações das quais você faz parte no Hub:
hf auth whoami
Wauplin
orgs: huggingface,eu-test,OAuthTesters,hf-accelerate,HFSmolClusterSe você não estiver conectado, uma mensagem de erro será exibida.
hf auth logout
Este comando faz o logout. Na prática, ele excluirá todos os tokens armazenados na sua máquina. Se você deseja remover um token específico, pode especificar o nome do token como argumento.
Este comando não fará logout se você estiver conectado usando a variável de ambiente HF_TOKEN (veja referência). Se esse for o caso, você deve desmarcar a variável de ambiente na configuração da sua máquina.
hf download
Use o comando hf download para baixar arquivos diretamente do Hub. Internamente, ele usa os mesmos auxiliares hf_hub_download() e snapshot_download() descritos no guia Download e imprime o caminho retornado no terminal. Nos exemplos abaixo, passaremos pelos casos de uso mais comuns. Para uma lista completa das opções disponíveis, você pode executar:
hf download --helpBaixar um arquivo único
Para baixar um arquivo único de um repositório, basta fornecer o repo_id e o filename da seguinte forma:
>>> hf download gpt2 config.json
downloading https://huggingface.co/gpt2/resolve/main/config.json to /home/wauplin/.cache/huggingface/hub/tmpwrq8dm5o
(…)ingface.co/gpt2/resolve/main/config.json: 100%|██████████████████████████████████| 665/665 [00:00<00:00, 2.49MB/s]
/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10/config.jsonO comando sempre exibirá na última linha o caminho para o arquivo em sua máquina local.
Para baixar um arquivo localizado em um subdiretório do repositório, você deve fornecer o caminho do arquivo no repositório no formato posix, como este:
>>> hf download HiDream-ai/HiDream-I1-Full text_encoder/model.safetensorsBaixar um repositório inteiro
Em alguns casos, você apenas deseja baixar todos os arquivos de um repositório. Isso pode ser feito simplesmente especificando o id do repositório:
>>> hf download HuggingFaceH4/zephyr-7b-beta
Fetching 23 files: 0%| | 0/23 [00:00<?, ?it/s]
...
...
/home/wauplin/.cache/huggingface/hub/models--HuggingFaceH4--zephyr-7b-beta/snapshots/3bac358730f8806e5c3dc7c7e19eb36e045bf720Baixar vários arquivos
Você também pode baixar um subconjunto dos arquivos de um repositório com um único comando. Isso pode ser feito de duas maneiras. Se você já tiver uma lista precisa dos arquivos que deseja baixar, basta fornecê-los sequencialmente:
>>> hf download gpt2 config.json model.safetensors
Fetching 2 files: 0%| | 0/2 [00:00<?, ?it/s]
downloading https://huggingface.co/gpt2/resolve/11c5a3d5811f50298f278a704980280950aedb10/model.safetensors to /home/wauplin/.cache/huggingface/hub/tmpdachpl3o
(…)8f278a7049802950aedb10/model.safetensors: 100%|██████████████████████████████| 8.09k/8.09k [00:00<00:00, 40.5MB/s]
Fetching 2 files: 100%|████████████████████████████████████████████████████████████████| 2/2 [00:00<00:00, 3.76it/s]
/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10A outra abordagem é fornecer padrões para filtrar quais arquivos você deseja baixar usando --include e --exclude. Por exemplo, se você quiser baixar todos os arquivos safetensors de stabilityai/stable-diffusion-xl-base-1.0, exceto os arquivos em precisão FP16:
>>> hf download stabilityai/stable-diffusion-xl-base-1.0 --include "*.safetensors" --exclude "*.fp16.*"*
Fetching 8 files: 0%| | 0/8 [00:00<?, ?it/s]
...
...
Fetching 8 files: 100%|█████████████████████████████████████████████████████████████████████████| 8/8 (...)
/home/wauplin/.cache/huggingface/hub/models--stabilityai--stable-diffusion-xl-base-1.0/snapshots/462165984030d82259a11f4367a4eed129e94a7bBaixe um conjunto de dados, um Space ou um kernel
Os exemplos acima mostram como fazer o download de um repositório de modelo. Para fazer o download de um dataset, um Space ou um kernel, use a opção --repo-type:
# https://huggingface.co/datasets/HuggingFaceH4/ultrachat_200k
>>> hf download HuggingFaceH4/ultrachat_200k --repo-type dataset
# https://huggingface.co/spaces/HuggingFaceH4/zephyr-chat
>>> hf download HuggingFaceH4/zephyr-chat --repo-type space
...Baixar uma revisão específica
Os exemplos acima mostram como fazer o download do commit mais recente no branch principal. Para fazer o download de uma revisão específica (hash do commit, nome do branch ou tag), use a opção --revision:
>>> hf download bigcode/the-stack --repo-type dataset --revision v1.1
...Use um URI hf://
Em vez de passar o tipo do repositório, a revisão e o caminho do arquivo como argumentos e opções separados, você pode fornecer um único URI hf://. O URI codifica tudo de uma vez, seguindo a gramática hf://[<TYPE>/]<ID>[@<REVISION>][/<PATH>] (consulte a referência de URIs do HF para a sintaxe completa):
# Equivalent to: hf download bigcode/the-stack --repo-type dataset --revision v1.1
>>> hf download hf://datasets/bigcode/the-stack@v1.1
# Download a single file from a specific revision
>>> hf download hf://datasets/HuggingFaceM4/FineVision@refs/pr/1/data/train.parquet
# Download a subfolder (note the trailing slash)
>>> hf download hf://datasets/HuggingFaceM4/FineVision/art/
# A bare id still works and defaults to a model repo
>>> hf download hf://openai-community/gpt2/config.jsonQuando uma URI é fornecida, --repo-type e --revision também não podem ser definidos, pois já fazem parte da URI (caso contrário, um erro é lançado), e um caminho de arquivo embutido na URI não pode ser combinado com nomes de arquivos posicionais. Um / no final do caminho denota uma subpasta (assim como com o argumento posicional). Nomes de branch que contêm um / devem ser codificados em URL como %2F (por exemplo, hf://my-org/my-model@feature%2Ffoo).
Baixar para uma pasta local
A maneira recomendada (e padrão) de baixar arquivos do Hub é usar o sistema de cache. No entanto, em alguns casos, você pode querer baixar arquivos e movê-los para uma pasta específica. Isso é útil para obter um fluxo de trabalho mais próximo do que os comandos git oferecem. Você pode fazer isso usando a opção --local-dir.
A pasta .cache/huggingface/ é criada na raiz do seu diretório local e contém metadados sobre os arquivos baixados. Isso impede o rebaixamento de arquivos que já estão atualizados. Se os metadados tiverem sido alterados, a nova versão do arquivo é baixada. Isso torna o local-dir otimizado para buscar apenas as alterações mais recentes.
Para mais detalhes sobre como o download para um arquivo local funciona, consulte o guia download.
>>> hf download adept/fuyu-8b model-00001-of-00002.safetensors --local-dir fuyu
...
fuyu/model-00001-of-00002.safetensorsModo de simulação
Em alguns casos, você pode querer verificar quais arquivos seriam baixados antes de efetivamente baixá-los. Você pode verificar isso usando o parâmetro --dry-run. Ele lista todos os arquivos a serem baixados no repositório e verifica se eles já foram baixados ou não. Isso dá uma ideia de quantos arquivos precisam ser baixados e de seus tamanhos.
>>> hf download openai-community/gpt2 --dry-run
[dry-run] Fetching 26 files: 100%|█████████████| 26/26 [00:04<00:00, 6.26it/s]
[dry-run] Will download 11 files (out of 26) totalling 5.6G.
File Bytes to download
--------------------------------- -----------------
.gitattributes -
64-8bits.tflite 125.2M
64-fp16.tflite 248.3M
64.tflite 495.8M
README.md -
config.json -
flax_model.msgpack 497.8M
generation_config.json -
merges.txt -
model.safetensors 548.1M
onnx/config.json -
onnx/decoder_model.onnx 653.7M
onnx/decoder_model_merged.onnx 655.2M
onnx/decoder_with_past_model.onnx 653.7M
onnx/generation_config.json -
onnx/merges.txt -
onnx/special_tokens_map.json -
onnx/tokenizer.json -
onnx/tokenizer_config.json -
onnx/vocab.json -
pytorch_model.bin 548.1M
rust_model.ot 702.5M
tf_model.h5 497.9M
tokenizer.json -
tokenizer_config.json -
vocab.json -Para mais detalhes, confira o guia de download.
Especificar diretório de cache
Se não estiver usando --local-dir, todos os arquivos serão baixados por padrão para o diretório de cache definido pela variável de ambiente HF_HOME environment variable. Você pode especificar um cache personalizado usando --cache-dir:
>>> hf download adept/fuyu-8b --cache-dir ./path/to/cache
...
./path/to/cache/models--adept--fuyu-8b/snapshots/ddcacbcf5fdf9cc59ff01f6be6d6662624d9c745Especifique um token
Para acessar repositórios privados ou com acesso restrito, você deve usar um token. Por padrão, o token salvo localmente (usando hf auth login) será utilizado. Se você quiser autenticar explicitamente, use a opção --token:
>>> hf download gpt2 config.json --token=hf_****
/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10/config.jsonModo silencioso
Por padrão, o comando hf download é detalhado. Ele exibe informações como mensagens de aviso, detalhes sobre os arquivos baixados e barras de progresso. Se você deseja silenciar tudo isso, use a opção --quiet. Apenas a última linha (ou seja, o caminho para os arquivos baixados) é exibida. Isso pode ser útil se você quiser passar a saída para outro comando em um script.
>>> hf download gpt2 --quiet
/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10Tempo limite de download
Em máquinas com conexões lentas, você pode encontrar problemas de tempo limite como este:
`httpx2.TimeoutException: (TimeoutException("HTTPSConnectionPool(host='cdn-lfs-us-1.huggingface.co', port=443): Read timed out. (read timeout=10)"), '(Request ID: a33d910c-84c6-4514-8362-c705e2039d38)')`Para mitigar esse problema, você pode definir a variável de ambiente HF_HUB_DOWNLOAD_TIMEOUT para um valor maior (o padrão é 10):
export HF_HUB_DOWNLOAD_TIMEOUT=30Para mais detalhes, consulte a referência de variáveis de ambiente. E execute novamente o comando de download.
hf upload
Use o comando hf upload para enviar arquivos diretamente para o Hub. Internamente, ele usa os mesmos auxiliares upload_file() e upload_folder() descritos no guia Upload. Nos exemplos abaixo, passaremos pelos casos de uso mais comuns. Para uma lista completa das opções disponíveis, você pode executar:
>>> hf upload --helpEnvie uma pasta inteira
O uso padrão para este comando é:
# Usage: hf upload [repo_id] [local_path] [path_in_repo]Para enviar o diretório atual na raiz do repositório, use:
>>> hf upload my-cool-model . .
https://huggingface.co/Wauplin/my-cool-model/tree/main/Se o repositório ainda não existir, ele será criado automaticamente.
Você também pode enviar uma pasta específica:
>>> hf upload my-cool-model ./models .
https://huggingface.co/Wauplin/my-cool-model/tree/main/Por fim, você pode enviar uma pasta para um destino específico no repositório:
>>> hf upload my-cool-model ./path/to/curated/data /data/train
https://huggingface.co/Wauplin/my-cool-model/tree/main/data/trainEnvie um arquivo único
Você também pode enviar um arquivo único definindo local_path para apontar para um arquivo em sua máquina. Nesse caso, path_in_repo é opcional e usará o nome do seu arquivo local por padrão:
>>> hf upload Wauplin/my-cool-model ./models/model.safetensors
https://huggingface.co/Wauplin/my-cool-model/blob/main/model.safetensorsSe você deseja enviar um arquivo único para um diretório específico, defina path_in_repo de acordo:
>>> hf upload Wauplin/my-cool-model ./models/model.safetensors /vae/model.safetensors
https://huggingface.co/Wauplin/my-cool-model/blob/main/vae/model.safetensorsCarregar vários arquivos
Para enviar vários arquivos de uma pasta de uma vez, sem enviar a pasta inteira, use os padrões --include e --exclude. Também pode ser combinado com a opção --delete para excluir arquivos no repositório enquanto envia novos. No exemplo abaixo, sincronizamos o Space local excluindo arquivos remotos e enviando todos os arquivos, exceto os de /logs:
# Sync local Space with Hub (upload new files except from logs/, delete removed files)
>>> hf upload Wauplin/space-example --repo-type=space --exclude="/logs/*" --delete="*" --commit-message="Sync local Space with Hub"
...Enviar para um dataset ou Space
Para enviar para um dataset ou um Space, use a opção --repo-type:
>>> hf upload Wauplin/my-cool-dataset ./data /train --repo-type=dataset
...Upload para uma organização
Para enviar conteúdo para um repositório pertencente a uma organização em vez de um repositório pessoal, você deve especificá-lo explicitamente no repo_id:
>>> hf upload MyCoolOrganization/my-cool-model . .
https://huggingface.co/MyCoolOrganization/my-cool-model/tree/main/Upload para uma revisão específica
Por padrão, os arquivos são enviados para o ramo main. Se você quiser enviar arquivos para outro ramo ou referência, use a opção --revision:
# Upload files to a PR
>>> hf upload bigcode/the-stack . . --repo-type dataset --revision refs/pr/104
...Observação: se revision não existir e --create-pr não estiver definido, um branch será criado automaticamente a partir do branch main.
Use um URI hf://
Assim como no hf download, o destino pode ser expresso como um único URI hf:// seguindo a gramática hf://[<TYPE>/]<ID>[@<REVISION>][/<PATH>] (consulte a referência de URIs do HF para a sintaxe completa). O tipo de repositório, a revisão e o path_in_repo são todos lidos do URI:
# Equivalent to: hf upload Wauplin/my-cool-dataset ./train.csv data/train.csv --repo-type dataset --revision my-branch
>>> hf upload hf://datasets/Wauplin/my-cool-dataset@my-branch/data/train.csv ./train.csv
# Upload a whole folder to the root of a model repo
>>> hf upload hf://Wauplin/my-cool-model ./modelsQuando uma URI é fornecida, --repo-type e --revision também não podem ser definidos, pois já fazem parte da URI (caso contrário, um erro é lançado), e um caminho embutido na URI não pode ser combinado com o argumento path_in_repo.
Envie e crie um PR
Se você não tiver permissão para fazer push em um repositório, deve abrir um PR e informar os autores sobre as alterações que deseja fazer. Isso pode ser feito definindo a opção --create-pr:
# Create a PR and upload the files to it
>>> hf upload bigcode/the-stack . . --repo-type dataset --revision refs/pr/104
https://huggingface.co/datasets/bigcode/the-stack/blob/refs%2Fpr%2F104/Envie em intervalos regulares
Em alguns casos, você pode querer enviar atualizações regulares para um repositório. Por exemplo, isso é útil se você estiver treinando um modelo e quiser enviar a pasta de logs a cada 10 minutos. Você pode fazer isso usando a opção --every:
# Upload new logs every 10 minutes
hf upload training-model logs/ --every=10Especifique uma mensagem de commit
Use o --commit-message e o --commit-description para definir uma mensagem e descrição personalizadas para o seu commit, em vez da padrão
>>> hf upload Wauplin/my-cool-model ./models . --commit-message="Epoch 34/50" --commit-description="Val accuracy: 68%. Check tensorboard for more details."
...
https://huggingface.co/Wauplin/my-cool-model/tree/mainEspecifique um token
Para enviar arquivos, você deve usar um token. Por padrão, o token salvo localmente (usando hf auth login) será utilizado. Se você quiser autenticar explicitamente, use a opção --token:
>>> hf upload Wauplin/my-cool-model ./models . --token=hf_****
...
https://huggingface.co/Wauplin/my-cool-model/tree/mainModo silencioso
Por padrão, o comando hf upload é detalhado. Ele exibe informações como mensagens de aviso, detalhes sobre os arquivos enviados e barras de progresso. Se você deseja silenciar tudo isso, use a opção --quiet. Apenas a última linha (ou seja, a URL dos arquivos enviados) é exibida. Isso pode ser útil se você quiser passar a saída para outro comando em um script.
>>> hf upload Wauplin/my-cool-model ./models . --quiet
https://huggingface.co/Wauplin/my-cool-model/tree/mainhf buckets
Use hf buckets para gerenciar buckets no Hugging Face Hub. Buckets oferecem armazenamento de objetos semelhante ao S3 no Hugging Face, impulsionado pelo backend de armazenamento Xet. Diferentemente dos repositórios (que são baseados em git e rastreiam o histórico de arquivos), buckets são contêineres de armazenamento de objetos remotos projetados para arquivos em larga escala com deduplicação endereçável por conteúdo. Eles são projetados para casos de uso em que você precisa de armazenamento simples, rápido e mutável, como armazenar checkpoints de treinamento, logs, artefatos intermediários ou qualquer grande coleção de arquivos que não necessite de controle de versão. Nos exemplos abaixo, abordaremos os casos de uso mais comuns. Para um guia completo, consulte o guia de Buckets.
Criar um bucket
Para criar um novo bucket, use hf buckets create. O bucket será criado no seu namespace por padrão:
>>> hf buckets create my-bucketVocê também pode criar um bucket privado usando a flag --private:
>>> hf buckets create my-bucket --privateListar e inspecionar buckets
Para listar todos os seus buckets, use hf buckets list (ou sua forma abreviada hf buckets ls). Você também pode listar buckets em uma organização específica:
>>> hf buckets list
ID PRIVATE SIZE TOTAL_FILES CREATED_AT
-------------------- ------- ---------- ----------- ----------
username/my-bucket 32 5 2026-02-16
username/checkpoints 117609095 700 2026-02-13
username/logs 321757477 2000 2026-02-13
# Human-readable sizes
>>> hf buckets list -h
ID PRIVATE SIZE TOTAL_FILES CREATED_AT
-------------------- ------- -------- ----------- ----------
username/my-bucket 32 B 5 2026-02-16
username/checkpoints 117.6 MB 700 2026-02-13
username/logs 321.8 MB 2000 2026-02-13
# List buckets in a specific namespace
>>> hf buckets ls my-org
# Filter buckets by name
>>> hf buckets list --search "checkpoint"Para obter informações detalhadas sobre um bucket específico (retornado como JSON), use hf buckets info:
>>> hf buckets info username/my-bucket
{
"id": "username/my-bucket",
"private": false,
"created_at": "2026-02-16T15:28:32+00:00",
"size": 32,
"total_files": 5
}Alterar a visibilidade do bucket
Para alternar um bucket entre privado e público, use hf buckets settings:
# Make a bucket private
>>> hf buckets settings username/my-bucket --private
# Make it public again
>>> hf buckets settings username/my-bucket --publicExcluir um bucket
Para excluir um bucket, use hf buckets delete. Você será solicitado a confirmar, a menos que passe --yes:
>>> hf buckets delete username/my-bucket --yesRemover arquivos
Use hf buckets remove (ou sua forma abreviada hf buckets rm) para remover arquivos de um bucket.
Para remover um arquivo individual, especifique seu caminho:
>>> hf buckets rm username/my-bucket/old-model.binPara remover todos os arquivos sob um prefixo, use --recursive:
>>> hf buckets rm username/my-bucket/logs/ --recursiveVocê também pode direcionar todos os arquivos em um bucket sem um prefixo:
>>> hf buckets rm username/my-bucket --recursive --include "*.tmp"Use --dry-run para visualizar o que seria excluído sem realmente excluir nada:
>>> hf buckets rm username/my-bucket/checkpoints/ --recursive --dry-runNavegar pelos arquivos
Use hf buckets list com um ID de bucket para listar os arquivos em um bucket:
>>> hf buckets list username/my-bucket
2048 2026-01-15 10:30:00 big.bin
5 2026-01-15 10:30:00 file.txt
2026-01-15 10:30:00 sub/Adicione -R para uma listagem recursiva e -h para tamanhos de arquivo legíveis e datas curtas. Você também pode exibir uma visualização em árvore ASCII com --tree, ou usar --tree --quiet para uma árvore limpa sem metadados:
# Recursive with human-readable sizes
>>> hf buckets list username/my-bucket -R -h
2.0 KB Jan 15 10:30 big.bin
5 B Jan 15 10:30 file.txt
14 B Jan 15 10:30 sub/nested.txt
4 B Jan 15 10:30 sub/deep/file.txt
# Tree with human-readable sizes
>>> hf buckets list username/my-bucket --tree -h -R
2.0 KB Jan 15 10:30 ├── big.bin
5 B Jan 15 10:30 ├── file.txt
└── sub/
├── deep/
4 B Jan 15 10:30 │ └── file.txt
14 B Jan 15 10:30 └── nested.txt
# Clean tree without metadata
>>> hf buckets list username/my-bucket --tree --quiet -R
├── big.bin
├── file.txt
└── sub/
├── deep/
│ └── file.txt
└── nested.txtPara filtrar por prefixo, adicione o prefixo ao caminho do bucket:
>>> hf buckets list username/my-bucket/sub -RCopiar arquivos
Use hf cp para copiar um arquivo único entre sua máquina local, repositórios e buckets. A origem e o destino podem ser, cada um, um caminho local, um URI hf:// (repositório ou bucket) ou - (stdin/stdout).
hf cptambém é exposto comohf repos cpehf buckets cp— os três são exatamente o mesmo comando. Use aquele que fizer mais sentido para o seu fluxo de trabalho.
Para enviar um arquivo (local → repositório ou bucket):
# To a repository
>>> hf cp ./model.safetensors hf://username/my-model/model.safetensors
# To a bucket (uses the local filename when the destination ends with /)
>>> hf cp ./data.csv hf://buckets/username/my-bucket/logs/Para baixar um arquivo (repositório ou bucket → local):
# From a repository
>>> hf cp hf://datasets/username/my-dataset@refs/pr/1/data.csv ./data.csv
# From a bucket, to the current directory (destination omitted)
>>> hf cp hf://buckets/username/my-bucket/config.jsonVocê também pode transmitir para o stdout ou a partir do stdin usando -:
# Download to stdout
>>> hf cp hf://buckets/username/my-bucket/config.json - | jq .
# Upload from stdin
>>> echo "hello" | hf cp - hf://username/my-model/hello.txtPara copiar entre dois locais no Hub (repo/bucket → repo/bucket):
# Repo to repo
>>> hf cp hf://username/source-model/config.json hf://username/dest-model/config.json
# Repo to bucket
>>> hf cp hf://datasets/username/my-dataset/data/train/ hf://buckets/username/my-bucket/datasets/train/
# Bucket to bucket
>>> hf cp hf://buckets/username/source-bucket/logs/ hf://buckets/username/archive-bucket/logs/Ao copiar pastas entre dois locais do Hub, uma barra / no final do caminho de origem controla se a própria pasta é aninhada ou se apenas seu conteúdo é copiado (estilo rsync):
# Without trailing slash: "logs" dir is nested => archive/logs/...
>>> hf cp hf://buckets/username/my-bucket/logs hf://buckets/username/archive-bucket/
# With trailing slash: only contents of "logs" are copied => archive/...
>>> hf cp hf://buckets/username/my-bucket/logs/ hf://buckets/username/archive-bucket/Observações:
hf cpcopia um único arquivo quando um caminho local está envolvido. Para copiar diretórios inteiros para/de locais, usehf upload/hf download(repositórios) ouhf buckets sync(buckets).- A cópia de bucket para repositório ainda não é suportada.
- A cópia local para local não é suportada (use o
cpdo seu shell). - Cópias entre duas localizações do Hub só funcionam dentro da mesma região de armazenamento.
Sincronizar diretórios
Use hf buckets sync para sincronizar diretórios entre sua máquina local e um bucket. Ele compara a origem e o destino e transfere apenas os arquivos alterados.
Para enviar um diretório local para um bucket:
>>> hf buckets sync ./data hf://buckets/username/my-bucketPara baixar de um bucket para um diretório local:
>>> hf buckets sync hf://buckets/username/my-bucket ./dataUse --delete para remover os arquivos de destino que não estão presentes na origem:
>>> hf buckets sync ./data hf://buckets/username/my-bucket --deleteVocê pode filtrar quais arquivos sincronizar usando os padrões --include e --exclude:
>>> hf buckets sync ./data hf://buckets/username/my-bucket --include "*.safetensors" --exclude "*.tmp"Para atualizar apenas os arquivos existentes (ignorar os novos), use --existing. Para criar apenas arquivos novos (ignorar os existentes), use --ignore-existing:
>>> hf buckets sync ./data hf://buckets/username/my-bucket --existing
>>> hf buckets sync ./data hf://buckets/username/my-bucket --ignore-existingPara maior segurança, você pode gerar um plano para revisão antes de executar e, em seguida, aplicá-lo:
# Generate a plan
>>> hf buckets sync ./data hf://buckets/username/my-bucket --plan sync-plan.jsonl
# Review and apply the plan
>>> hf buckets sync --apply sync-plan.jsonlUse --dry-run para imprimir o plano de sincronização como JSONL no stdout sem executar nada. Isso é útil para encaminhar para jq ou outras ferramentas:
>>> hf buckets sync ./data hf://buckets/username/my-bucket --dry-run | jq .
hf syncé um alias de nível superior conveniente parahf buckets sync. Consulte o guia de Buckets para obter todos os detalhes sobre as opções de sincronização.
hf models
Use hf models para listar modelos no Hub e obter informações detalhadas sobre um modelo específico.
Listar modelos
# List trending models
>>> hf models ls
# Search for models
>>> hf models ls --search "lora"
# Filter by author
>>> hf models ls --author Qwen
# Filter by pipeline tag
>>> hf models ls --pipeline-tag summarization
# Filter by parameter count
>>> hf models ls --num-parameters min:6B,max:128B
# Only non-gated models
>>> hf models ls --no-gated --author google
# Only models runnable by a given app
>>> hf models ls --apps llama.cpp
# Sort by downloads
>>> hf models ls --sort downloads --limit 10Quando chamado com um ID de modelo, hf models ls lista os arquivos no repositório desse modelo:
# List files in a model repo
>>> hf models ls meta-llama/Llama-3.2-1B-Instruct
# List files recursively
>>> hf models ls meta-llama/Llama-3.2-1B-Instruct -R
# Tree view with human-readable sizes
>>> hf models ls meta-llama/Llama-3.2-1B-Instruct --tree -h
# List files at a specific revision
>>> hf models ls meta-llama/Llama-3.2-1B-Instruct --revision mainObter informações do modelo
>>> hf models info Lightricks/LTX-2Use --expand para buscar propriedades adicionais como downloads, likes, tags, etc.
Obter o cartão do modelo
Use hf models card para buscar o cartão do modelo (README) de um modelo. Por padrão, imprime o conteúdo completo do cartão no stdout.
# Full card (metadata + text)
>>> hf models card google/gemma-4-31B-it
# Just the metadata (from the YAML frontmatter)
>>> hf models card google/gemma-4-31B-it --metadata
# Metadata as JSON (useful for scripting and agents)
>>> hf models card google/gemma-4-31B-it --metadata --format json
# Just the text body (no YAML frontmatter)
>>> hf models card google/gemma-4-31B-it --texthf datasets
Use hf datasets para listar conjuntos de dados no Hub e obter informações detalhadas sobre um conjunto de dados específico.
Listar conjuntos de dados
# List trending datasets
>>> hf datasets ls
# Search for datasets
>>> hf datasets ls --search "code"
# List official benchmark datasets
>>> hf datasets ls --filter benchmark:official
# Sort by downloads
>>> hf datasets ls --sort downloads --limit 10Quando chamado com um ID de dataset, hf datasets ls lista os arquivos no repositório desse dataset:
# List files in a dataset repo
>>> hf datasets ls HuggingFaceFW/fineweb
# List files recursively with human-readable sizes
>>> hf datasets ls HuggingFaceFW/fineweb -R -h
# Tree view
>>> hf datasets ls HuggingFaceFW/fineweb --treeListar um ranking de conjuntos de dados
Use hf datasets leaderboard para exibir as pontuações de modelos submetidas a um conjunto de dados de benchmark, para que você possa encontrar os melhores modelos para uma tarefa ou comparar modelos por pontuações de benchmark.
>>> hf datasets leaderboard SWE-bench/SWE-bench_Verified
>>> hf datasets leaderboard SWE-bench/SWE-bench_Verified --limit 5 --format jsonObter informações do conjunto de dados
>>> hf datasets info HuggingFaceFW/finewebObter o cartão do conjunto de dados
Use hf datasets card para buscar o card do dataset (README) de um dataset. Por padrão, imprime o conteúdo completo do card no stdout.
# Full card (metadata + text)
>>> hf datasets card HuggingFaceFW/fineweb
# Just the metadata (from the YAML frontmatter)
>>> hf datasets card HuggingFaceFW/fineweb --metadata
# Metadata as JSON (useful for scripting and agents)
>>> hf datasets card HuggingFaceFW/fineweb --metadata --format json
# Just the text body (no YAML frontmatter)
>>> hf datasets card HuggingFaceFW/fineweb --textListar URLs parquet
Use hf datasets parquet para descobrir as URLs dos arquivos parquet de um dataset antes de escrever consultas SQL.
Os datasets no Hub são convertidos automaticamente para Parquet no backend pelo serviço Dataset Viewer (para datasets elegíveis).
Veja o guia de conversão para Parquet para mais detalhes.
>>> hf datasets parquet cfahlgren1/hub-stats
>>> hf datasets parquet cfahlgren1/hub-stats --subset models
>>> hf datasets parquet cfahlgren1/hub-stats --split train
>>> hf datasets parquet cfahlgren1/hub-stats --format jsonA saída padrão da tabela inclui o subconjunto, a divisão e a URL do arquivo parquet da API do Hub.
Executar SQL em parquet de dataset
Use hf datasets sql para executar consultas SQL brutas com DuckDB contra URLs de parquets de datasets.
Descubra as URLs primeiro com hf datasets parquet e, em seguida, consulte-as diretamente com read_parquet(...).
>>> hf datasets sql "SELECT COUNT(*) AS rows FROM read_parquet('https://huggingface.co/api/datasets/cfahlgren1/hub-stats/parquet/models/train/0.parquet')"
>>> hf datasets sql "SELECT * FROM read_parquet('https://huggingface.co/api/datasets/cfahlgren1/hub-stats/parquet/models/train/0.parquet') LIMIT 5" --format jsonInstale o DuckDB primeiro, se necessário:
# Python package
>>> pip install duckdb
# or standalone DuckDB CLI (Homebrew: macOS/Linux)
>>> brew install duckdbhf spaces
Use hf spaces para listar Spaces no Hub e obter informações detalhadas sobre um Space específico.
Listar Spaces
# List trending Spaces
>>> hf spaces ls
# Search for Spaces
>>> hf spaces ls --search "3d"
# Sort by likes
>>> hf spaces ls --sort likes --limit 10Quando chamado com um ID de Space, hf spaces ls lista os arquivos no repositório desse Space:
# List files in a Space repo
>>> hf spaces ls victor/deepsite
# List files recursively with tree view
>>> hf spaces ls victor/deepsite --tree -R -hObter informações do Space
>>> hf spaces info victor/deepsiteObter cartão do Space
Use hf spaces card para buscar o card (README) de um Space. Por padrão, imprime o conteúdo completo do card no stdout.
# Full card (metadata + text)
>>> hf spaces card mteb/leaderboard
# Just the card metadata (from the YAML frontmatter)
>>> hf spaces card mteb/leaderboard --metadata
# Card metadata as JSON
>>> hf spaces card mteb/leaderboard --metadata --format json
# Just the text body (no YAML frontmatter)
>>> hf spaces card mteb/leaderboard --textPausar ou reiniciar um Space desmonta seu contêiner, portanto, qualquer coisa escrita no sistema de arquivos efêmero é perdida. Para persistir dados entre reinícios, monte um Volume ou bucket com
hf spaces volumes set(executehf spaces volumes --helppara mais detalhes).
Pausar um Space
Use hf spaces pause para pausar um Space quando você não estiver usando-o (o tempo em pausa não é cobrado). Reinicie-o mais tarde com hf spaces restart.
>>> hf spaces pause username/my-spaceReiniciar um Space
Use hf spaces restart para reiniciar um Space. Passe --factory-reboot para reconstruir o Space do zero, sem usar o cache de build.
>>> hf spaces restart username/my-space
>>> hf spaces restart username/my-space --factory-rebootAguarde por um Space
Use hf spaces wait para bloquear até que um Space termine de compilar/iniciar e atinja um estágio estável. Encerra com código 0 se o Space estiver RUNNING, ou com um código diferente de zero caso contrário (por exemplo, BUILD_ERROR). Útil para scripts após uma reinicialização ou alteração de hardware.
>>> hf spaces wait username/my-space
# With a timeout
>>> hf spaces wait username/my-space --timeout 5m
# Chain with restart
>>> hf spaces restart username/my-space && hf spaces wait username/my-spaceListar hardware disponível
Use hf spaces hardware para listar todas as opções de hardware disponíveis para Spaces, incluindo preços.
>>> hf spaces hardwareVerifique sua cota de ZeroGPU
Use hf spaces zero-gpu quota para verificar quanto da sua cota de ZeroGPU está disponível e quando ela será redefinida. Isso é útil para acompanhar seu uso ao chamar Spaces ZeroGPU a partir de scripts, aplicativos ou agentes.
>>> hf spaces zero-gpu quota
✓ ZeroGPU quota (in GPU-seconds)
remaining: 1810
base: 2400
resets_at: 2026-09-30T18:12:03+00:00
overquota_used: 0
>>> hf spaces zero-gpu quota --format json
{"remaining": 1810, "base": 2400, "resets_at": "2026-09-30T18:12:03+00:00", "overquota_used": 0}Se sua cota estiver acabando, o comando sugere a compra de créditos em suas configurações de faturamento para continuar usando o ZeroGPU além da cota diária (somente para usuários PRO, Team e Enterprise).
Atualizar configurações do Space
Use hf spaces settings para atualizar as configurações de um Space.
>>> hf spaces settings username/my-space --sleep-time 3600
>>> hf spaces settings username/my-space --hardware t4-medium--sleep-time: tempo ocioso em segundos antes de o Space entrar em modo de espera. Use-1para nunca entrar em modo de espera. Disponível apenas em hardware atualizado (veja a documentação sobre o tempo de espera dos Spaces).--hardware: tipo de hardware (por exemplo,cpu-basic,t4-medium,l4x4). Executehf spaces hardwarepara ver todas as opções.
Gerenciar segredos do Space
Use hf spaces secrets ls para listar segredos em um Space, hf spaces secrets add para adicionar ou atualizar um ou mais segredos e hf spaces secrets delete para remover um. Passe --secrets-file PATH para carregar segredos de um arquivo no estilo .env. Chaves existentes são sobrescritas.
>>> hf spaces secrets ls username/my-space
>>> hf spaces secrets add username/my-space -s OPENAI_API_KEY=sk-...
>>> hf spaces secrets add username/my-space --secrets-file .env.secrets
>>> hf spaces secrets delete username/my-space OPENAI_API_KEY --yesOs valores secretos são somente de gravação, portanto
hf spaces secrets lsexibe as chaves, as descrições e os timestamps de atualização, mas nunca os próprios valores secretos.
Gerenciar variáveis de ambiente do Space
Use hf spaces variables para gerenciar variáveis de ambiente não confidenciais em um Space. Diferente dos segredos, as variáveis são legíveis, portanto ls exibe tanto as chaves quanto os valores. Passe --env-file PATH em add para carregar de um arquivo no estilo .env.
>>> hf spaces variables ls username/my-space
>>> hf spaces variables add username/my-space -e MODEL_ID=gpt2 -e MAX_TOKENS=512
>>> hf spaces variables add username/my-space --env-file .env
>>> hf spaces variables delete username/my-space MAX_TOKENS --yesConectar via SSH a um Space (Modo de desenvolvimento)
Use hf spaces ssh para abrir uma sessão SSH no container do Dev Mode de um Space. Se o Dev Mode não estiver habilitado, o CLI solicitará que você o habilite (ou use --auto para pular o prompt).
Sua chave pública SSH deve estar registrada nas suas configurações. Consulte a documentação do Dev Mode para mais detalhes.
# SSH into a Space
>>> hf spaces ssh username/my-space
# Print the SSH command without running it
>>> hf spaces ssh username/my-space --dry-run
# Auto-enable Dev Mode if disabled
>>> hf spaces ssh username/my-space --auto
# Use a specific SSH key
>>> hf spaces ssh username/my-space -i ~/.ssh/id_ed25519hf papers
Use hf papers para listar, pesquisar, obter informações estruturadas e ler o conteúdo em markdown de papers no Hub.
Listar artigos
# List most recent daily papers
>>> hf papers ls
# List trending papers
>>> hf papers ls --sort=trending
# List papers from a specific date
>>> hf papers ls --date=2025-01-23
# List today's papers
>>> hf papers ls --date=today
# List papers from a specific week
>>> hf papers ls --week=2025-W09
# List papers from a specific month
>>> hf papers ls --month=2025-02
# List papers submitted by a specific user
>>> hf papers ls --submitter=akhaliq
# Limit results
>>> hf papers ls --sort=trending --limit=5Pesquisar artigos
# Search papers by keyword
>>> hf papers search "vision language"
# Limit search results
>>> hf papers search "diffusion models" --limit=10
# Output as JSON
>>> hf papers search "attention" --format=jsonObter informações do paper
# Get structured metadata for a paper (returns JSON)
>>> hf papers info 2601.15621Leia o artigo como markdown
# Read the full paper content as markdown
>>> hf papers read 2601.15621discussões do hf
Use hf discussions para gerenciar discussões e pull requests em repositórios do Hub diretamente do seu terminal. Você pode listar, visualizar, criar, comentar, fechar, reabrir e mesclar tanto discussões quanto PRs. Para um guia completo sobre como os recursos de comunidade do Hub funcionam, consulte o guia de Discussões e Pull Requests.
Listar discussões
Para listar discussões e PRs abertos em um repositório, passe o ID do repositório para hf discussions list (ou sua forma abreviada hf discussions ls):
>>> hf discussions list username/my-modelVocê pode filtrar os resultados por tipo (discussion ou pull_request), status (open, closed, merged ou all) ou autor:
>>> hf discussions list username/my-model --kind pull_request --status merged
>>> hf discussions list username/my-model --author alicePara scripts, use --format json para obter uma saída estruturada, ou --quiet para imprimir apenas os números das discussões (um por linha):
>>> hf discussions list username/my-model --format json
>>> hf discussions ls username/my-model --quietObter informações sobre uma discussão ou PR
Para inspecionar uma discussão ou PR específica, passe o ID do repositório e o número da discussão:
>>> hf discussions info username/my-model 5A saída contém os metadados da discussão (título, status, autor, etc.) junto com a lista completa de eventos da conversa. Para exibir o diff de um pull request, use hf discussions diff em vez disso.
Use --format json para saída legível por máquina e defina NO_COLOR=1 para remover as cores ANSI ao encaminhar para outras ferramentas.
Crie uma discussão ou PR
Para abrir uma nova discussão, forneça um título com --title. Você pode incluir opcionalmente uma descrição inline com --body ou carregá-la de um arquivo com --body-file:
>>> hf discussions create username/my-model --title "Bug report"
>>> hf discussions create username/my-model --title "Feature request" --body "Please add X"
>>> hf discussions create username/my-model --title "Report" --body-file report.mdPara criar um pull request em vez de uma discussão simples, adicione a flag --pull-request:
>>> hf discussions create username/my-model --title "Fix typo" --pull-requestComente em uma discussão ou PR
Adicione um comentário a uma discussão ou PR existente especificando seu número. O corpo do comentário pode ser passado inline com --body, lido de um arquivo com --body-file ou enviado via stdin usando --body-file -:
>>> hf discussions comment username/my-model 5 --body "Thanks for reporting!"
>>> hf discussions comment username/my-model 5 --body-file review.md
>>> echo "LGTM" | hf discussions comment username/my-model 5 --body-file -Editar um comentário
Edite um comentário existente no local, passando o número da discussão e o ID do comentário. Os IDs de comentário podem ser obtidos com hf discussions info:
>>> hf discussions edit username/my-model 5 abc123 --body "Updated comment."
>>> hf discussions edit username/my-model 5 abc123 --body-file fixed.mdAnexar imagens e vídeos
Use --attach em hf discussions create, comment ou edit para enviar um arquivo de imagem, vídeo ou áudio e incorporá-lo ao corpo, como quando você arrasta um arquivo para a caixa de comentários no Hub. Se o corpo já referencia o arquivo, como em , a referência aponta para o arquivo enviado. Caso contrário, o arquivo é adicionado ao corpo. Para definir o texto alternativo de uma imagem adicionada, adicione-o após um #:
>>> hf discussions create username/my-model --title "Fix rendering" --pr --body "Before: " --attach ./before.png --attach "./after.png#After the fix"
>>> hf discussions comment username/my-model 5 --body "Here is a demo:" --attach demo.mp4Os formatos suportados são PNG, JPEG, GIF, WebP, MP4, MOV, WebM, MP3 e WAV, com tamanho máximo de 10MB (50MB para vídeos).
Fechar, reabrir e mesclar
Você pode encerrar uma discussão ou PR com hf discussions close. Por padrão, você será solicitado a confirmar. Passe --yes para pular o prompt e --comment para deixar uma mensagem de encerramento:
>>> hf discussions close username/my-model 5
>>> hf discussions close username/my-model 5 --yes --comment "Resolved"Para reabrir uma discussão previamente fechada, use hf discussions reopen:
>>> hf discussions reopen username/my-model 5 --yesPara mesclar um pull request, use hf discussions merge:
>>> hf discussions merge username/my-model 5 --yesRenomear e comparar
Você pode renomear uma discussão fornecendo o novo título:
>>> hf discussions rename username/my-model 5 "Updated title"Para visualizar a diferença de um pull request diretamente no terminal, use hf discussions diff:
>>> hf discussions diff username/my-model 5hf repos
hf repos permite listar, criar, duplicar, excluir e mover repositórios, atualizar suas configurações e excluir arquivos no Hugging Face Hub. Ele também inclui subcomandos para gerenciar branches e tags.
Listar repositórios
Use hf repos ls para listar todos os seus repositórios (modelos, conjuntos de dados, spaces e buckets) com informações de armazenamento, ordenados pelo uso de armazenamento. Por padrão, apenas os primeiros 30 repositórios são exibidos:
# List all your repos (first 30)
>>> hf repos ls
REPOSITORY TYPE UPDATED VISIBILITY STORAGE % OF TOTAL
------------------------ ------- ---------- ---------- -------- ----------
username/bucket-raw bucket 2026-04-29 public 1.7 TB 72.3%
username/my-model model 2026-05-06 public 4.8 GB 18.1%
username/my-dataset dataset 2024-09-14 private 598.4 MB 5.2%
Hint: Showing 30 of 42 repos. Use `--limit 0` to list all.Filtre pelo tipo de repositório, pesquise pelo nome ou ajuste o limite:
# List only models
>>> hf repos ls --type model
# Search by name
>>> hf repos ls --search "bert"
# List repos from an organization
>>> hf repos ls --namespace my-org
# Combine filters
>>> hf repos ls --namespace my-org --type dataset --search "train"
# List all repos (no limit)
>>> hf repos ls --limit 0Use --format json para scripts ou -q apenas para IDs. Ao usar pipes, use --limit 0 para exportar todos os repositórios:
>>> hf repos ls --limit 0 --format json | jq '.[].id'
>>> hf repos ls -qCriar um repositório
>>> hf repos create Wauplin/my-cool-model
Successfully created Wauplin/my-cool-model on the Hub.
Your repo is now available at https://huggingface.co/Wauplin/my-cool-modelCrie um conjunto de dados privado ou um Space:
>>> hf repos create my-cool-dataset --repo-type dataset --private
>>> hf repos create my-gradio-space --repo-type space --sdk gradioUse --exist-ok se o repositório já pode existir e --resource-group-id para direcionar a um grupo de recursos Enterprise.
Crie um repositório em uma região específica:
>>> hf repos create my-model --region usDuplicar um repositório
Use hf repos duplicate para copiar um modelo, conjunto de dados ou Space existente para sua conta (ou para uma organização). A cópia ocorre no servidor e preserva o histórico do git:
>>> hf repos duplicate openai/gdpval --type dataset
>>> hf repos duplicate openai/gdpval myorg/my-gdpval --type dataset --privateOs arquivos LFS/Xet do novo repositório ainda podem ser copiados em segundo plano após o retorno do comando. Nesse caso, um aviso é exibido e o download desses arquivos do novo repositório pode falhar até que a cópia seja concluída.
Excluir um repositório
>>> hf repos delete Wauplin/my-cool-modelConjuntos de dados e Espaços:
>>> hf repos delete my-cool-dataset --repo-type dataset
>>> hf repos delete my-gradio-space --repo-type spaceMover um repositório
>>> hf repos move old-namespace/my-model new-namespace/my-modelAtualizar configurações do repositório
>>> hf repos settings Wauplin/my-cool-model --gated auto
>>> hf repos settings Wauplin/my-cool-model --private true
>>> hf repos settings Wauplin/my-cool-model --private false--gated: um deauto,manual,false--private true|false: define a privacidade do repositório
Excluir arquivos de um repositório
O subcomando hf repos delete-files <repo_id> permite excluir arquivos de um repositório. Veja alguns exemplos de uso.
Excluir uma pasta:
>>> hf repos delete-files Wauplin/my-cool-model folder/
Files correctly deleted from repo. Commit: https://huggingface.co/Wauplin/my-cool-mo...Excluir vários arquivos:
>>> hf repos delete-files Wauplin/my-cool-model file.txt folder/pytorch_model.bin
Files correctly deleted from repo. Commit: https://huggingface.co/Wauplin/my-cool-mo...Use padrões curinga para excluir conjuntos de arquivos. Os padrões são curingas padrão (padrões de globbing) conforme documentado aqui. A correspondência de padrões é baseada em fnmatch.
Observe que
fnmatchcorresponde*através de fronteiras de caminho, ao contrário do globbing tradicional de shell Unix. Por exemplo,"data/*.json"corresponderá tanto adata/file.jsonquanto adata/subdir/file.json. Para corresponder apenas a arquivos no diretório imediato, é necessário listá-los explicitamente ou usar padrões mais específicos.
>>> hf repos delete-files Wauplin/my-cool-model "*.txt" "folder/*.bin"
Files correctly deleted from repo. Commit: https://huggingface.co/Wauplin/my-cool-mo...Para excluir arquivos de um repositório, você deve estar autenticado e autorizado. Por padrão, o token salvo localmente (usando hf auth login) será utilizado. Se você quiser autenticar explicitamente, use a opção --token:
>>> hf repos delete-files --token=hf_**** Wauplin/my-cool-model file.txthf repos branch
Use hf repos branch para criar e excluir branches para repositórios no Hub.
# Create a branch
>>> hf repos branch create Wauplin/my-cool-model dev
# Create a branch from a specific revision
>>> hf repos branch create Wauplin/my-cool-model release-1 --revision refs/pr/104
# Delete a branch
>>> hf repos branch delete Wauplin/my-cool-model devTodos os comandos aceitam
--repo-type(um demodel,dataset,space) e--tokense você precisar autenticar explicitamente. Use--helpem qualquer comando para ver todas as opções.
hf cache
Use hf cache para gerenciar seu diretório de cache local do Hugging Face. O cache armazena modelos, conjuntos de dados, Spaces e kernels baixados do Hub.
# List cached repositories
>>> hf cache ls
# List cached revisions
>>> hf cache ls --revisions
# Remove specific items from cache
>>> hf cache rm model/gpt2
# Remove unreferenced revisions
>>> hf cache prune
# Verify cached file checksums
>>> hf cache verify gpt2hf cache ls
Use hf cache ls para inspecionar o que está armazenado localmente no seu cache do Hugging Face. Por padrão, ele agrega informações por repositório:
>>> hf cache ls
ID SIZE LAST_ACCESSED LAST_MODIFIED REFS
--------------------------- -------- ------------- ------------- -----------
dataset/nyu-mll/glue 157.4M 2 days ago 2 days ago main script
model/LiquidAI/LFM2-VL-1.6B 3.2G 4 days ago 4 days ago main
model/microsoft/UserLM-8b 32.1G 4 days ago 4 days ago main
Found 3 repo(s) for a total of 5 revision(s) and 35.5G on disk.Adicione --revisions para detalhar snapshots específicos e encadene filtros para focar no que importa:
>>> hf cache ls --filter "size>30g" --revisions
ID REVISION SIZE LAST_MODIFIED REFS
------------------------- ---------------------------------------- -------- ------------- ----
model/microsoft/UserLM-8b be8f2069189bdf443e554c24e488ff3ff6952691 32.1G 4 days ago main
Found 1 repo(s) for a total of 1 revision(s) and 32.1G on disk.O comando suporta vários formatos de saída para scripts: --format json imprime objetos estruturados, --format csv grava linhas separadas por vírgula e --quiet imprime apenas IDs. Use --sort para ordenar as entradas por accessed, modified, name ou size (adicione :asc ou :desc para controlar a ordem) e --limit para restringir os resultados às N primeiras entradas. Combine esses parâmetros com --cache-dir para direcionar a locais alternativos de cache. Consulte o guia Gerenciar seu cache para fluxos de trabalho avançados.
Exclua as entradas de cache selecionadas com hf cache ls --q enviando os IDs para hf cache rm:
>>> hf cache rm $(hf cache ls --filter "accessed>1y" -q) -y
About to delete 2 repo(s) totalling 5.31G.
- model/meta-llama/Llama-3.2-1B-Instruct (entire repo)
- model/hexgrad/Kokoro-82M (entire repo)
Deleted 2 repo(s) and 2 revision(s); freed 5.31G.hf cache rm
hf cache rm remove repositórios em cache, revisões individuais ou arquivos únicos. Passe um ou mais IDs de repositório (model/bert-base-uncased), URIs hf:// ou hashes de revisão:
>>> hf cache rm model/LiquidAI/LFM2-VL-1.6B
About to delete 1 repo(s) totalling 3.2G.
- model/LiquidAI/LFM2-VL-1.6B (entire repo)
Proceed with deletion? [y/N]: y
Deleted 1 repo(s) and 2 revision(s); freed 3.2G.URIs de nível de repositório hf:// também são suportados:
>>> hf cache rm hf://models/openai-community/gpt2 --dry-run
About to delete 1 repo(s) totalling 1.1G.
- model/openai-community/gpt2 (entire repo)
Dry run: no files were deleted.Para remover um arquivo individual em vez de um repositório inteiro, por exemplo, uma quantização GGUF, passe um URI de arquivo hf://. O arquivo é removido de todas as revisões em cache do repositório e seu blob é excluído apenas se nenhum outro arquivo em cache ainda o referenciar:
>>> hf cache rm hf://models/unsloth/gemma-3-27b-it-GGUF/gemma-3-27b-it-Q4_K_M.gguf --dry-run
About to delete 1 file(s) totalling 16.5G.
- model/unsloth/gemma-3-27b-it-GGUF@3f4b5c1d2e6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c/gemma-3-27b-it-Q4_K_M.gguf
Dry run: no files were deleted.A revisão permanece utilizável, e um arquivo excluído é baixado novamente na próxima vez que for necessário. Os caminhos devem corresponder exatamente: pastas e padrões glob não são suportados, e os destinos de arquivo não podem ser misturados com repositórios ou revisões na mesma chamada.
Misture repositórios e revisões específicas na mesma chamada. Use --dry-run para visualizar o impacto ou --yes para pular o prompt de confirmação — útil em scripts automatizados:
>>> hf cache rm model/t5-small 8f3ad1c --dry-run
About to delete 1 repo(s) and 1 revision(s) totalling 1.1G.
- model/t5-small:
8f3ad1c [main] 1.1G
Dry run: no files were deleted.Ao trabalhar fora do local de cache padrão, combine o comando com --cache-dir PATH.
hf cache prune
hf cache prune é um atalho prático que recupera o espaço ocupado por resíduos do cache: todas as revisões desconectadas (sem referências) (mantendo apenas as revisões ainda acessíveis por meio de um branch ou tag), quaisquer arquivos .incomplete remanescentes de downloads interrompidos e blobs compartilhados que não são mais referenciados por nenhum repositório em cache:
>>> hf cache prune
About to delete 3 unreferenced revision(s) and 2 incomplete download(s) (2.4G total).
- model/t5-small:
1c610f6b [refs/pr/1] 820.1M
d4ec9b72 [(detached)] 640.5M
- dataset/google/fleurs:
2b91c8dd [(detached)] 937.6M
Proceed? [y/N]: y
Deleted 3 unreferenced revision(s) and 2 incomplete download(s); freed 2.4G.Arquivos .incomplete são downloads parciais deixados para trás quando um download é interrompido. Eles não são rastreados por hf cache ls/rm (que operam no nível da revisão), portanto hf cache ls os destaca com uma dica e hf cache prune os remove automaticamente.
Assim como nos outros comandos de cache, --dry-run, --yes e --cache-dir estão disponíveis. Consulte o guia Gerenciar seu cache para mais exemplos.
hf cache verify
Use hf cache verify para validar os arquivos locais em relação aos seus checksums no Hub. Você pode verificar um snapshot de cache ou um diretório local regular.
Exemplos:
# Verify main revision of a model in cache
>>> hf cache verify deepseek-ai/DeepSeek-OCR
# Verify a specific revision
>>> hf cache verify deepseek-ai/DeepSeek-OCR --revision refs/pr/5
>>> hf cache verify deepseek-ai/DeepSeek-OCR --revision ef93bf4a377c5d5ed9dca78e0bc4ea50b26fe6a4
# Verify a private repo
>>> hf cache verify me/private-model --token hf_***
# Verify a dataset
>>> hf cache verify karpathy/fineweb-edu-100b-shuffle --repo-type dataset
# Verify files in a local directory
>>> hf cache verify deepseek-ai/DeepSeek-OCR --local-dir /path/to/repoPor padrão, o comando emite avisos sobre arquivos ausentes ou extras. Use as flags para transformar esses avisos em erros:
>>> hf cache verify deepseek-ai/DeepSeek-OCR --fail-on-missing-files --fail-on-extra-filesEm caso de sucesso, você verá um resumo:
✅ Verified 13 file(s) for 'deepseek-ai/DeepSeek-OCR' (model) in ~/.cache/huggingface/hub/models--meta-llama--Llama-3.2-1B-Instruct/snapshots/9213176726f574b556790deb65791e0c5aa438b6 All checksums match.
Se divergências forem detectadas, o comando exibe uma lista detalhada e encerra com um status diferente de zero.
hf repos tag
Use hf repos tag para criar, listar e excluir tags para repositórios no Hub.
# Create a tag
>>> hf repos tag create my-model v1.0
# List tags
>>> hf repos tag list my-model
# Delete a tag
>>> hf repos tag delete my-model v1.0Marcar um modelo
Para marcar um repositório, você precisa fornecer o repo_id e o nome da tag:
>>> hf repos tag create Wauplin/my-cool-model v1.0
You are about to create tag v1.0 on model Wauplin/my-cool-model
Tag v1.0 created on Wauplin/my-cool-modelMarcar um modelo em uma revisão específica
Se você deseja marcar uma revisão específica, pode usar a opção --revision. Por padrão, a tag será criada no branch main:
>>> hf repos tag create Wauplin/my-cool-model v1.0 --revision refs/pr/104
You are about to create tag v1.0 on model Wauplin/my-cool-model
Tag v1.0 created on Wauplin/my-cool-modelMarcar um conjunto de dados ou um Space
Se você deseja marcar um dataset ou Space, é necessário especificar a opção --repo-type:
>>> hf repos tag create bigcode/the-stack v1.0 --repo-type dataset
You are about to create tag v1.0 on dataset bigcode/the-stack
Tag v1.0 created on bigcode/the-stackListar tags
Para listar todas as tags de um repositório, use o subcomando list (ou ls):
>>> hf repos tag list Wauplin/gradio-space-ci --repo-type space
Tags for space Wauplin/gradio-space-ci:
0.2.2
0.2.1
0.2.0
0.1.2
0.0.2
0.0.1Excluir uma tag
Para excluir uma tag, use o subcomando delete:
>>> hf repos tag delete Wauplin/my-cool-model v1.0
You are about to delete tag v1.0 on model Wauplin/my-cool-model
Proceed? [Y/n] y
Tag v1.0 deleted on Wauplin/my-cool-modelVocê também pode passar -y para pular a etapa de confirmação.
hf env
O comando hf env exibe detalhes sobre a configuração da sua máquina. Isso é útil ao abrir uma issue no GitHub para ajudar os mantenedores a investigar seu problema.
>>> hf env
Copy-and-paste the text below in your GitHub issue.
- huggingface_hub version: 1.0.0.rc6
- Platform: Linux-6.8.0-85-generic-x86_64-with-glibc2.35
- Python version: 3.11.14
- Running in iPython ?: No
- Running in notebook ?: No
- Running in Google Colab ?: No
- Running in Google Colab Enterprise ?: No
- Token path ?: /home/wauplin/.cache/huggingface/token
- Has saved token ?: True
- Who am I ?: Wauplin
- Configured git credential helpers: store
- Installation method: unknown
- Torch: N/A
- httpx2: 2.0.0
- hf_xet: 1.1.10
- gradio: 5.41.1
- tensorboard: N/A
- pydantic: 2.11.7
- ENDPOINT: https://huggingface.co
- HF_HUB_CACHE: /home/wauplin/.cache/huggingface/hub
- HF_ASSETS_CACHE: /home/wauplin/.cache/huggingface/assets
- HF_TOKEN_PATH: /home/wauplin/.cache/huggingface/token
- HF_STORED_TOKENS_PATH: /home/wauplin/.cache/huggingface/stored_tokens
- HF_HUB_OFFLINE: False
- HF_HUB_DISABLE_TELEMETRY: False
- HF_HUB_DISABLE_PROGRESS_BARS: None
- HF_HUB_DISABLE_SYMLINKS_WARNING: False
- HF_HUB_DISABLE_EXPERIMENTAL_WARNING: False
- HF_HUB_DISABLE_IMPLICIT_TOKEN: False
- HF_HUB_DISABLE_XET: False
- HF_HUB_DISABLE_SHARED_BLOBS: False
- HF_HUB_ETAG_TIMEOUT: 10
- HF_HUB_DOWNLOAD_TIMEOUT: 10hf jobs
Execute jobs de computação na infraestrutura do Hugging Face com uma interface semelhante ao Docker.
hf jobs é uma ferramenta de linha de comando que permite executar qualquer coisa na infraestrutura do Hugging Face (incluindo GPUs e TPUs!) com comandos simples. Pense em docker run, mas para executar código em A100s.
Para uma visão geral de Jobs e preços, consulte a documentação de Jobs do Hub. Para o uso da API em Python junto com a CLI, consulte o guia de execução e gerenciamento de Jobs.
# Directly run Python code
>>> hf jobs run --name hello-world python:3.12 python -c 'print("Hello from the cloud!")'
# Use GPUs without any setup
>>> hf jobs run --flavor a10g-small pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel \
... python -c "import torch; print(torch.cuda.get_device_name())"
# Run in an organization account
>>> hf jobs run --namespace my-org-name python:3.12 python -c 'print("Running in an org account")'
# Run from Hugging Face Spaces
>>> hf jobs run hf.co/spaces/lhoestq/duckdb duckdb -c 'select "hello world"'
# Run a Python script with `uv` (experimental)
>>> hf jobs uv run --name my-script my_script.pyOs Hugging Face Jobs estão disponíveis para qualquer usuário ou organização com créditos pré-pagos.
Início rápido
1. Execute seu primeiro job
# Run a simple Python script
>>> hf jobs run python:3.12 python -c 'print("Hello from HF compute!")'Este comando executa o job e exibe os logs. Você pode passar --detach para executar o Job em segundo plano e imprimir apenas o ID do Job. Adicione -q para imprimir apenas o ID do Job, o que é útil para capturá-lo em um script:
>>> JOB_ID=$(hf jobs run -dq python:3.12 python train.py)
>>> hf jobs wait "$JOB_ID"2. Verifique o status do trabalho
# List your running jobs
>>> hf jobs ls
# List all jobs
>>> hf jobs ls -a
# Inspect the status of a job
>>> hf jobs inspect <job_id>
# View logs from a job
>>> hf jobs logs <job_id>
# View resources usage stats and metrics of running jobs
>>> hf jobs stats
# View resources usage stats and metrics of some jobs
>>> hf jobs stats [job_ids]...
# Follow live stats until the jobs complete
>>> hf jobs stats -f [job_ids]...
# Cancel a job
>>> hf jobs cancel <job_id>
# Wait until one or more jobs finish (exit code 0 only if all jobs completed successfully)
>>> hf jobs wait <job_id> [<job_id>...]
# Wait for all currently running jobs
>>> hf jobs ls -q | xargs hf jobs waitNon-detached hf jobs run e hf jobs wait encerram com um código diferente de zero se um Job falhar, permitindo encadear comandos com &&:
>>> hf jobs run python:3.12 python train.py && echo "training succeeded"3. Executar na GPU
Você também pode executar jobs em GPUs ou TPUs com a opção --flavor. Por exemplo, para executar um job do PyTorch em uma GPU A10G:
# Use an A10G GPU to check PyTorch CUDA
>>> hf jobs run --flavor a10g-small pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel \
... 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
Use -- para separar as opções de Jobs dos argumentos passados ao seu comando ou script.
O Jobs não interpreta opções após --.
>>> hf jobs run --flavor cpu-basic python:3.12 -- python --helpÉ isso! Agora você está executando código na infraestrutura da Hugging Face.
Casos de uso comuns
- Treinamento de modelos: ajuste fino ou treine modelos em GPUs (T4, A10G, A100) sem gerenciar a infraestrutura
- Geração de dados sintéticos: Geração de conjuntos de dados em larga escala usando LLMs em hardware de alto desempenho
- Processamento de dados: Processe conjuntos de dados massivos com configurações de CPU de alto desempenho para cargas de trabalho paralelas
- Inferência em lote: Execute inferência offline em milhares de amostras usando configurações de GPU otimizadas
- Experimentos e Benchmarks: Execute experimentos de ML em hardware consistente para resultados reproduzíveis
- Desenvolvimento e depuração: Teste código de GPU sem configuração local de CUDA
Passar variáveis de ambiente e segredos
Você pode passar variáveis de ambiente para seu trabalho usando
# Pass environment variables
>>> hf jobs run -e FOO=foo -e BAR=bar python:3.12 python -c 'import os; print(os.environ["FOO"], os.environ["BAR"])'# Pass an environment from a local .env file
>>> hf jobs run --env-file .env python:3.12 python -c 'import os; print(os.environ["FOO"], os.environ["BAR"])'# Pass secrets by name - the value is read from your environment, never from the command line
>>> hf jobs run -s MY_SECRET python:3.12 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 run --secrets-file .env.secrets python:3.12 python -c 'import os; print(os.environ["MY_SECRET"])'# Or pipe them in, so the values touch neither the command line nor the disk
>>> printf 'MY_SECRET=psswrd\n' | hf jobs run --secrets-file - python:3.12 python -c 'import os; print(os.environ["MY_SECRET"])'Os segredos são criptografados no servidor em todos os três formatos. -s MY_SECRET=psswrd também funciona, mas o valor acaba ficando no histórico do seu shell e na listagem de processos (/proc/<pid>/cmdline no Linux), por isso a CLI imprime um aviso no stderr quando você usa esse formato; reserve esse formato para valores que não são realmente sensíveis. O mesmo se aplica a --token <value>: prefira hf auth login ou a variável de ambiente HF_TOKEN. Um arquivo de variáveis de ambiente ou de segredos deve ser legível apenas por você (chmod 600) — a CLI emite um aviso se não for.
Use
--secrets HF_TOKENpara passar seu token local do Hugging Face implicitamente. Com essa sintaxe, o segredo é recuperado da variável de ambiente. ParaHF_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.
Variáveis de Ambiente Integradas
Dentro do contêiner do job, as seguintes variáveis de ambiente estão automaticamente disponíveis:
| Variável | Descrição |
|---|---|
JOB_ID | O identificador único do trabalho atual. Use-o para referenciar o trabalho programaticamente. |
ACCELERATOR | O tipo de acelerador disponível (por exemplo, t4-medium, a10g-small, a100x4). Vazio se não houver acelerador. |
CPU_CORES | O número de núcleos de CPU disponíveis para o trabalho (por exemplo, 2, 4, 8). |
MEMORY | A quantidade de memória disponível para o trabalho (por exemplo, 16Gi, 32Gi). |
# 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\")}')"Tempo limite do trabalho
Os jobs possuem um tempo limite padrão de 30 minutos, após o qual são interrompidos automaticamente. Para tarefas de longa duração, como o treinamento de modelos, defina um tempo limite personalizado usando a opção --timeout:
# Set timeout in seconds (default unit)
>>> hf jobs run --timeout 7200 python:3.12 python train.py
# Use time units: s (seconds), m (minutes), h (hours), d (days)
>>> hf jobs run --timeout 2h pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel python train.py
>>> hf jobs run --timeout 90m python:3.12 python process_data.py
>>> hf jobs run --timeout 1.5h python:3.12 python train.py # floats are supportedA opção --timeout também funciona com scripts UV e agendamentos:
# UV script with timeout
>>> hf jobs uv run --timeout 2h training_script.py
# Scheduled job with timeout
>>> hf jobs scheduled run @daily --timeout 4h python:3.12 python daily_task.pySe a sua tarefa exceder o tempo limite, ela será encerrada automaticamente. Defina sempre um tempo limite adequado, com uma margem de segurança para tarefas de longa duração, a fim de evitar encerramentos inesperados da tarefa.
Tentar novamente e reexecutar um Job
--attempts define o número máximo de tentativas, incluindo a primeira execução. Funciona com Docker, UV e Jobs agendados. Reexecutar um Job inicia um novo Job com a mesma especificação salva:
>>> hf jobs run --attempts 3 --detach python:3.12 python train.py
>>> hf jobs rerun <job_id>Uma contagem de tentativas de 3 permite até duas novas tentativas quando um Job falha. hf jobs rerun também reutiliza a contagem de tentativas original. Assim como hf jobs run, ele transmite os logs do novo Job até que ele termine. Use --detach para retornar imediatamente.
Hardware
Opções de --flavor disponíveis:
- CPU:
cpu-basic,cpu-upgrade - GPU:
t4-small,t4-medium,l4x1,l4x4,a10g-small,a10g-large,a10g-largex2,a10g-largex4,a100-large - TPU:
v5e-1x1,v5e-2x2,v5e-2x4
(atualizado em 07/2025 a partir dos documentos suggested_hardware da Hugging Face)
Volumes
Monte um volume no disco do Job usando -v ou --volume.
Você pode montar qualquer Repositório do Hugging Face (modelo/conjunto de dados/espaço) ou Storage Bucket usando o esquema de URL hf://. Por exemplo:
- montar um repositório de modelo:
-v hf://openai/gpt-oss-120b:/model - montar um repositório de dataset:
-v hf://datasets/HuggingFaceFW/fineweb:/data - montar um bucket de armazenamento:
-v hf://buckets/username/my-bucket:/mnt - montar um espaço:
-v hf://spaces/username/my-space:/app - montar uma subpasta dentro de um repositório:
-v hf://datasets/org/ds/train:/data
Em seguida, você pode usar o volume montado como um diretório local:
# Docker Job with a mounted volume as input
>>> hf jobs run -v hf://datasets/HuggingFaceFW/fineweb:/dataset \
... duckdb/duckdb duckdb -c "SELECT * FROM '/dataset/**/*.parquet' LIMIT 5"
# UV Job with a mounted volume to save checkpoints when training a model
>>> hf jobs uv run -v hf://buckets/username/my-bucket:/training-outputs \
... sft.py --output-dir /training-outputs/training-v3-final ...Modelos, conjuntos de dados e espaços são sempre montados somente para leitura. Os buckets de armazenamento são, por padrão, de leitura e gravação — isso é especialmente útil para dados que mudam com frequência, pois os arquivos podem ser sobrescritos ou excluídos no local.
Use :ro para habilitar somente leitura:
- montar um bucket de armazenamento somente leitura:
-v hf://buckets/username/my-bucket:/mnt:ro
Montar dados locais
O lado de origem de -v também pode ser um diretório local. Ele é primeiro sincronizado com seu jobs-artifacts Storage Bucket e a pasta do bucket resultante é montada no Job:
>>> hf jobs uv run -v ./my-data:/data process.pyExecutar o comando novamente faz o upload apenas de novos arquivos ou arquivos modificados. Os diretórios locais são montados somente leitura por padrão. Use :rw para permitir que o Job escreva no volume, por exemplo, para recuperar as saídas após a conclusão do Job (um diretório local vazio também funciona):
>>> hf jobs uv run -v ./pdfs:/input -v ./md-out:/output:rw ocr.py
...
Hint: Volume '/output' is mounted read-write. Once the job is over, pull back its data with:
hf buckets sync hf://buckets/username/jobs-artifacts/md-out-a1b2c3d4 ./md-outRótulos
Adicione rótulos a um Job usando -l ou --label. Rótulos são pares chave=valor que aplicam metadados a um Job. Para rotular um Job com dois rótulos, repita a flag de rótulo (-l ou --label):
>>> hf jobs run -l my-label --label foo=bar ubuntu echo "This Job has multiple labels"A chave my-label não especifica um valor, portanto seu valor padrão é uma string vazia ("").
Use --name para adicionar o rótulo name ao criar um Job. Os nomes facilitam a localização e a identificação dos Jobs na interface; eles são opcionais e não precisam ser únicos. Se você não passar --name, um nome é derivado automaticamente da imagem Docker ou do script, além de um hash curto do comando e das configurações de runtime resolvidas (flavor, timeout, valores de ambiente, ...), de modo que a mesma configuração sempre produz o mesmo nome (por exemplo, python:3.12 foo --truc → python-3-12-1a2b3c4d). Alterar uma configuração altera o nome, mesmo quando o comando permanece o mesmo. Você também pode renomear um Job existente:
>>> hf jobs run --name training-v2 python:3.12 python train.py
>>> hf jobs labels <job_id> --name training-v2Use --status, --label e --name em hf jobs ls para filtrar Jobs. --status aceita um ou mais status, --label aceita pares key=value e --name é um atalho para --label name=NAME. Um Job deve corresponder a todos os filtros para ser listado. O nome do Job também é exibido em sua própria coluna NAME:
# Show completed Jobs
>>> hf jobs ls -a --status completed
# Show running or scheduling Jobs
>>> hf jobs ls --status running,scheduling
# Show Jobs named `training-v2`
>>> hf jobs ls -a --name training-v2
# Show Jobs with the `model=Qwen3-06B` label
>>> hf jobs ls -a --label model=Qwen3-06B
# Combine filters: running Jobs labelled both `env=prod` and `team=ml`
>>> hf jobs ls --status running --label env=prod --label team=mlPor padrão, hf jobs ps exibe no máximo 100 Jobs para evitar que o terminal fique sobrecarregado. Use --limit para alterar isso, ou --limit 0 para exibi-los todos:
# Show up to 500 Jobs
>>> hf jobs ps -a --limit 500
# Show all Jobs (no limit)
>>> hf jobs ps -a --limit 0Expor as portas do Job
Use --expose para uma porta protegida por token e --expose-public para uma porta que deve permitir acesso não autenticado. Ambas as flags podem ser repetidas e combinadas, e funcionam com Docker, UV e Jobs agendados.
# Start a Job with a public HTTP server
>>> hf jobs run --detach --expose-public 8000 python:3.12 python -m http.server 8000
# Replace the configuration on a running Job: port 8000 is private, 9000 is public
>>> hf jobs expose <job_id> 8000 --public 9000
# Close all exposed ports
>>> hf jobs expose <job_id> --clearhf jobs expose aceita portas protegidas por token como argumentos posicionais e portas públicas com --public. Ele aplica a alteração sem reexecutar o Job. Portas omitidas da lista de substituição são fechadas.
Conectar via SSH a um Job
Pass --ssh para hf jobs run (ou hf jobs uv run) para tornar o container do Job acessível via SSH e, em seguida, conecte-se com hf jobs ssh:
# Start a job with SSH enabled
>>> hf jobs run --ssh --detach python:3.12 sleep infinity
# Open an SSH session into it
>>> hf jobs ssh <job_id>
# Print the SSH command instead of running it
>>> hf jobs ssh <job_id> --dry-run
# Use a specific identity file
>>> hf jobs ssh <job_id> -i ~/.ssh/id_ed25519Apenas usuários com acesso de escrita ao namespace do Job (o criador do Job ou membros da organização proprietária) são permitidos, autenticados por uma chave pública SSH registrada em https://huggingface.co/settings/keys.
Grupos de rede
Passar --network-group <name> para hf jobs run (ou hf jobs uv run) permite que Jobs no mesmo namespace e grupo de recursos se comuniquem entre si em todas as portas. Dentro de cada membro, $HF_NETWORK_GROUP_HOSTNAME resolve para todos os Jobs do grupo, e ${HF_NETWORK_GROUP_PREFIX}<alias> para os membros que reivindicaram um alias com --network-alias <alias>:
# 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/"'Os membros são resolúveis antes de ficarem prontos, portanto, conecte-se com novas tentativas. Os nomes e os aliases de grupo são alfanuméricos em minúsculas e hífens, com no máximo 46 e 34 caracteres, respectivamente.
UV Scripts (Experimental)
Execute scripts UV (scripts Python com dependências inline) na infraestrutura do HF. Scripts UV são scripts Python que incluem suas dependências diretamente no arquivo usando uma sintaxe de comentário especial.
# Run a UV script (creates temporary repo)
>>> hf jobs uv run my_script.py
# Run with persistent repo
>>> hf jobs uv run --repo my-uv-scripts my_script.py
# Run with GPU
>>> hf jobs uv run --flavor t4-small ml_training.py
# Pass arguments to script
>>> hf jobs uv run process.py input.csv output.parquet
# Add dependencies
>>> hf jobs uv run --with transformers --with torch train.py
# Run a script directly from a URL
>>> hf jobs uv run https://huggingface.co/datasets/username/scripts/resolve/main/example.py
# Run a command
>>> hf jobs uv run --with lighteval python -c 'import lighteval'Os scripts UV são scripts Python que incluem suas dependências diretamente no arquivo usando uma sintaxe de comentário especial. Isso os torna perfeitos para tarefas autossuficientes que não exigem configurações complexas de projeto. Saiba mais sobre scripts UV na documentação do UV.
Use -- para passar opções conflitantes para o seu script. Aqui, --help chega ao train.py em vez de exibir a ajuda do Jobs:
>>> hf jobs uv run --flavor t4-small train.py -- --helpIsso também se aplica às flags de formatação: hf jobs run, hf jobs uv run e suas variantes scheduled consomem --format, --json e -q onde quer que apareçam, portanto, use -- quando seu script precisar delas.
Envie a configuração de lançamento com o script
Alguns scripts só são executados corretamente em um runtime específico: uma determinada imagem, um tipo de GPU, um interpretador de sistema, etc. Um script pode carregar essa configuração com ele em uma tabela opcional [tool.hf-jobs] em seu cabeçalho PEP 723:
# /// script
# requires-python = ">=3.11"
# dependencies = ["vllm", "datasets"]
#
# [tool.hf-jobs]
# name = "unlimited-ocr"
# image = "vllm/vllm-openai:unlimited-ocr"
# flavor = "l4x1"
# python = "/usr/bin/python3"
# timeout = "2h"
# env = { PYTHONPATH = "/usr/local/lib/python3.12/dist-packages", BATCH_SIZE = "64" }
# secrets = ["HF_TOKEN"]
# labels = { task = "ocr" }
# volumes = ["hf://datasets/org/pdfs:/input"]
# ///hf jobs uv run ocr.py in_ds out_ds em seguida inicia com o runtime correto, em vez de executar silenciosamente em uma imagem de CPU com o interpretador errado. A tabela é invisível para um uv run simples: 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 (name é armazenado como o rótulo name, volumes aceita as mesmas especificações hf://...:/MOUNT_PATH de -v, network_aliases é uma lista de valores de --network-alias). Uma chave desconhecida resulta em erro, em vez de uma intenção silenciosamente descartada — um erro de digitação como flavour é exatamente a falha que este recurso existe para prevenir.
Todos os valores devem ser strings, incluindo os valores de env e labels: -e BATCH_SIZE=64 se traduz em env = { BATCH_SIZE = "64" }, e não env = { BATCH_SIZE = 64 } (o TOML lê o segundo como um inteiro e a tabela é rejeitada). A única exceção é timeout, que também aceita um número inteiro de segundos (timeout = 7200 é o mesmo que timeout = "2h").
Os valores do script são padrões: uma flag explícita sempre tem prioridade, e env, secrets, labels e volumes são mesclados entrada por entrada, de modo que -e e -v podem adicionar ao que o script declara:
# Same script, on bigger hardware, with one extra env var
>>> hf jobs uv run --flavor a10g-large -e BATCH_SIZE=64 ocr.py in_ds out_dsnetwork_aliases é a exceção: os aliases que um Job reivindica formam um conjunto, portanto --network-alias substitui a lista do script em vez de adicioná-la a ela. Jobs agendados não possuem nenhum grupo de rede, portanto hf jobs scheduled uv run rejeita um script que declara network_group ou network_aliases.
secrets lista apenas os nomes dos segredos: os valores sempre vêm do ambiente de quem executa o script, nunca do próprio script (HF_TOKEN também é resolvido a partir de hf auth login). Um segredo solicitado, mas não definido localmente, resulta em um erro, em vez de o Job receber silenciosamente um valor vazio. Com --dry-run, ele é exibido como <not set>, de modo que a configuração de um script cujos segredos ainda não foram provisionados permaneça visível.
Cada execução ecoa a configuração que envia, marcando os valores que vêm do script. Use --dry-run para exibi-la sem iniciar nada:
>>> hf jobs uv run --dry-run --flavor a10g-large ocr.py in_ds out_ds
Warning: The script's [tool.hf-jobs] table requests HF_TOKEN: the value(s) from your local environment would be sent to the Job.
Job configuration:
script ocr.py
args in_ds out_ds
image vllm/vllm-openai:unlimited-ocr (from script)
flavor a10g-large
python /usr/bin/python3 (from script)
timeout 2h (from script)
env PYTHONPATH=/usr/local/lib/python3.12/dist-packages (from script)
BATCH_SIZE=64 (from script)
secrets HF_TOKEN=*** (from script)
volumes hf://datasets/org/pdfs:/input (from script)
labels task=ocr (from script)
name=unlimited-ocr (from script)
(dry run) Job not submitted.Isso também funciona para scripts que estão atrás de uma URL: o script é baixado uma vez quando o Job é enviado (para ler seu cabeçalho) e enviado para o Job como um script local, em vez de ser baixado novamente pelo container. A URL deve ser acessível a partir da sua máquina. Assim como os scripts locais, os scripts de URL usam o mount de artefatos reservado
/data; use outro caminho de mount para seus volumes de entrada.
Para hf jobs scheduled uv run, isso fixa o script ao seu conteúdo no momento da criação. Atualizar a URL de origem não altera mais as execuções futuras: recrie o Job agendado para incorporar uma nova versão.
--dry-run também está disponível em hf jobs run, hf jobs scheduled run e hf jobs scheduled uv run. Ele ignora o envio e os uploads de volumes locais. Os nomes gerados automaticamente para Jobs Docker e UV incluem a configuração de inicialização resolvida, portanto, alterar as configurações de tempo de execução ou os valores de ambiente altera o nome.
hf jobs scheduled
Agende e gerencie jobs que serão executados na infraestrutura da HF.
O agendamento deve ser um de @annually, @yearly, @monthly, @weekly, @daily, @hourly ou uma expressão de agendamento CRON (por exemplo, "0 9 * * 1" para 9h de toda segunda-feira).
# Schedule a job that runs every hour
>>> hf jobs scheduled run @hourly --name hourly-task python:3.12 python -c 'print("This runs every hour!")'
# Use the CRON syntax
>>> hf jobs scheduled run "*/5 * * * *" python:3.12 python -c 'print("This runs every 5 minutes!")'
# Schedule with GPU
>>> hf jobs scheduled run @hourly --flavor a10g-small pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel \
... python -c 'import torch; print(f"This code ran with the following GPU: {torch.cuda.get_device_name()}")'
# Schedule a UV script
>>> hf jobs scheduled uv run @hourly --name hourly-script my_script.pyUse os mesmos parâmetros de hf jobs run para passar variáveis de ambiente, segredos, timeout, etc.
Gerenciar trabalhos agendados usando
# List your active scheduled jobs
>>> hf jobs scheduled ls
# Same filters as `hf jobs ls`: --status, --label and --name
>>> hf jobs scheduled ls --all
>>> hf jobs scheduled ls --status suspended
>>> hf jobs scheduled ls --name hourly-task --label env=prod
# Inspect the status of a job
>>> hf jobs scheduled inspect <scheduled_job_id>
# Suspend (pause) a scheduled job
>>> hf jobs scheduled suspend <scheduled_job_id>
# Resume a scheduled job
>>> hf jobs scheduled resume <scheduled_job_id>
# Change future run times (Mondays at 9:00)
>>> hf jobs scheduled reschedule <scheduled_job_id> "0 9 * * 1"
# Trigger a scheduled job to run right now (does not change the schedule)
>>> hf jobs scheduled trigger <scheduled_job_id>
# Delete a scheduled job
>>> hf jobs scheduled delete <scheduled_job_id>hf sandbox
hf sandbox inicia máquinas de nuvem isoladas baseadas em Jobs: crie uma, execute comandos com saída transmitida ao vivo e copie arquivos para dentro e para fora. Qualquer imagem Docker com /bin/sh funciona. Consulte o guia de Sandboxes para a API em Python e o guia conceitual para entender como funciona por baixo dos panos.
Sandboxes são experimentais, e sua API e comportamento podem mudar sem aviso prévio. Sandboxes compartilhadas são destinadas a cargas de trabalho dentro do mesmo limite de confiança; use uma sandbox dedicada para cargas de trabalho que não confiam umas nas outras.
# Create a sandbox (waits until it is ready, prints its id)
>>> hf sandbox create
✓ Sandbox ready id=687f911eaea852de79c4a50a image=python:3.12 elapsed=6.0s
# Attach labels to the underlying Job
>>> hf sandbox create --label controller-run=run-42 --label team=data-infra
# Run commands inside it (output is streamed, exit code is propagated)
>>> hf sandbox exec 687f911eaea852de79c4a50a -- python -c "print('hi')"
hi
# Copy files in and out (docker-style)
>>> hf sandbox cp data.csv 687f911eaea852de79c4a50a:/data/data.csv
>>> hf sandbox cp 687f911eaea852de79c4a50a:/app/results.json results.json
# Terminate a sandbox
>>> hf sandbox kill 687f911eaea852de79c4a50aUse --flavor para escolher o hardware (por exemplo, a10g-small), --idle-timeout para limitar o tempo de vida do sandbox e -l / --label para anexar rótulos ao seu Job. Para distribuir muitos sandboxes de CPU de baixo custo, crie um pool com hf sandbox pool create e instancie nele com hf sandbox create --pool <id> (veja o guia de Sandboxes).
Passar variáveis de ambiente e segredos para um sandbox
Existem dois canais separados, com propriedades de armazenamento diferentes:
| canal | flags | sandbox dedicado | sandbox agrupado (--pool) |
|---|---|---|---|
| ambiente | -e / --env, --env-file | armazenado nos metadados do job | entregues ao host na criação, não armazenadas nos metadados do job |
| secrets | -s / --secrets, --secrets-file | criptografado no servidor | indisponível — use --env |
# Plain environment variables
>>> hf sandbox create -e LOG_LEVEL=debug --env-file .env
# Secrets, read from your environment by name (nothing sensitive on the command line)
>>> hf sandbox create -s OPENAI_API_KEY -s HF_TOKEN
# Secrets from a file, or piped in on stdin
>>> hf sandbox create --secrets-file .env.secrets
>>> printf 'OPENAI_API_KEY=sk-...\n' | hf sandbox create --secrets-file --s KEY=value também funciona, mas o valor fica no histórico do shell e na listagem de processos, por isso a CLI emite um aviso no stderr, inclusive no modo silencioso. Sandboxes em pool rejeitam --secrets de imediato: uma pool não possui um canal de segredos criptografados, e hf sandbox create --pool <id> -s KEY=value retorna um erro com uma referência para --env.
hf webhooks
hf webhooks permite gerenciar webhooks no Hugging Face Hub diretamente pelo terminal. Webhooks permitem que você escute eventos (pushes, discussões, etc.) em repositórios, usuários ou organizações e dispare ações — seja pingando uma URL remota ou executando um Job na infraestrutura do Hugging Face.
Listar webhooks
>>> hf webhooks ls
ID URL DISABLED DOMAINS WATCHED
wh-abc123 https://example.com/hook False repo model:bert-base-uncased
wh-def456 https://example.com/other-hook False repo org:HuggingFaceUse --format json para saída legível por máquina, ou -q para imprimir apenas os IDs:
>>> hf webhooks ls --format json
>>> hf webhooks ls -qObter informações do webhook
>>> hf webhooks info wh-abc123Imprime todos os detalhes do webhook como JSON.
Criar um webhook
Crie um webhook que envia payloads para uma URL:
>>> hf webhooks create --url https://example.com/hook --watch model:bert-base-uncased
>>> hf webhooks create --url https://example.com/hook --watch org:HuggingFace --watch model:gpt2 --domain repoOu crie um webhook que aciona um Job:
>>> hf webhooks create --job-id 687f911eaea852de79c4a50a --watch user:julien-cOs segredos do Job de origem não são copiados para o webhook. Use --secrets ou --secrets-file (mesma sintaxe de hf jobs run) para passá-los ao Job acionado. Por exemplo, --secrets HF_TOKEN passa seu token local do Hugging Face:
>>> hf webhooks create --job-id 687f911eaea852de79c4a50a --watch bucket:my-org/my-bucket --secrets HF_TOKENA opção --watch usa o formato type:name, em que type é um dos valores model, dataset, space, bucket, org ou user. Ela pode ser repetida para monitorar vários itens. Use --domain para filtrar eventos por repo ou discussion, e --secret para definir um segredo de assinatura.
Atualizar um webhook
>>> hf webhooks update wh-abc123 --url https://new-url.com/hook
>>> hf webhooks update wh-abc123 --watch model:gpt2 --domain repoSomente as opções fornecidas são alteradas. Observe que --watch substitui a lista inteira observada quando especificado.
Para atualizar os segredos de um webhook acionado por Job, passe --job-id junto com --secrets. Os segredos listados substituem os valores armazenados e todos os outros segredos são mantidos:
>>> hf webhooks update wh-abc123 --job-id 687f911eaea852de79c4a50a --secrets HF_TOKENAtivar / desativar um webhook
>>> hf webhooks enable wh-abc123
>>> hf webhooks disable wh-abc123Excluir um webhook
>>> hf webhooks delete wh-abc123
Are you sure you want to delete webhook 'wh-abc123'? [y/N]: y
Webhook deleted: wh-abc123Use --yes para pular o prompt de confirmação:
>>> hf webhooks delete wh-abc123 --yesTodos os comandos aceitam
--tokenpara substituir a autenticação. Use--helpem qualquer comando para ver todas as opções.
hf endpoints
Use hf endpoints para listar, implantar, descrever e gerenciar Inference Endpoints diretamente do terminal. O alias legado hf inference-endpoints continua disponível para compatibilidade.
# Lists endpoints in your namespace
>>> hf endpoints ls
# List the hardware you can deploy on
>>> hf endpoints hardware
# Deploy an endpoint from Model Catalog
>>> hf endpoints catalog deploy --repo openai/gpt-oss-120b --name my-endpoint
# Deploy an endpoint from the Hugging Face Hub
>>> hf endpoints deploy my-endpoint --repo gpt2 --framework pytorch --accelerator cpu --instance-size x2 --instance-type intel-icl
# List catalog entries
>>> hf endpoints catalog ls
# Show status and metadata
>>> hf endpoints describe my-endpoint
# Pause the endpoint
>>> hf endpoints pause my-endpoint
# Delete without confirmation prompt
>>> hf endpoints delete my-endpoint --yesAdicione
--namespacepara direcionar a uma organização e--tokenpara substituir a autenticação.
Encontre hardware para implantar
hf endpoints deploy requer cinco flags de hardware (--vendor, --region, --accelerator, --instance-type e --instance-size). hf endpoints hardware lista as combinações válidas, com o preço por réplica por hora em USD e a cota de aceleradores do seu namespace:
>>> hf endpoints hardware --vendor aws --region eu-west-1
VENDOR REGION ACCELERATOR INSTANCE_TYPE INSTANCE_SIZE MEMORY_GB GPU_MEMORY_GB PRICE_PER_HOUR QUOTA STATUS
------ --------- ----------- ------------- ------------- --------- ------------- -------------- ----- ---------
aws eu-west-1 cpu intel-spr x1 2.0 0.033 0/60 available
aws eu-west-1 cpu intel-spr x2 4.0 0.067 0/60 available
aws eu-west-1 cpu intel-spr x4 8.0 0.134 0/60 available
aws eu-west-1 cpu intel-spr x8 16.0 0.268 0/60 available
aws eu-west-1 cpu intel-spr x16 32.0 0.536 0/60 available
aws eu-west-1 gpu nvidia-a10g x1 30.0 24 1.0 0/16 available
aws eu-west-1 gpu nvidia-t4 x1 15.0 16 0.5 1/30 available
Hint: Deploy on one of these, e.g.: hf endpoints deploy my-endpoint --repo <repo> --framework <framework> --vendor aws --region eu-west-1 --accelerator cpu --instance-type intel-spr --instance-size x1As flags de filtro são as flags de deploy (--vendor, --region, --accelerator, --instance-type), portanto, o que você filtra é o que você passa para deploy. Apenas o hardware que você pode implantar agora é listado: um status utilizável e cota de acelerador suficiente no seu namespace para uma réplica. Adicione --all para também ver o que está descontinuado, temporariamente indisponível ou sem cota. --format json adiciona as especificações restantes por réplica (vCPUs, arquitetura, número de aceleradores) a cada entrada.
A cota é por namespace e determina quais linhas são listadas. Se você estiver implantando em uma organização, passe o mesmo
--namespaceque passará paradeploy— caso contrário, você estará vendo sua cota pessoal, o que pode tanto ocultar hardware no qual a organização pode implantar quanto exibir hardware no qual ela não pode.
Implantar um contêiner personalizado
Para implantar sua própria imagem Docker em vez de uma gerenciada pela Hugging Face, passe --framework custom junto com --custom-image. O repositório do modelo é montado em /repository dentro do contêiner. Use --container-args (e opcionalmente --container-command) para passar uma string de inicialização entre aspas, --env/--secrets para injetar variáveis de ambiente e --type para definir o tipo de acesso (public, authenticated ou private):
>>> hf endpoints deploy nex-n2-pro \
--repo nex-agi/Nex-N2-Pro \
--framework custom \
--accelerator gpu --vendor aws --region us-east-1 \
--instance-type nvidia-h200 --instance-size x8 \
--custom-image nexagi/sglang:v0.5.12 \
--health-route /health --port 30000 \
--container-args "--reasoning-parser qwen3 --tool-call-parser qwen3_coder --mamba-scheduler-strategy extra_buffer --tp 8" \
--env MODEL_ID=/repository \
--type authenticated--container-args e --container-command não se limitam a imagens personalizadas: eles mapeiam para model.args e model.command no payload da API, que se aplicam também a imagens gerenciadas. Em um endpoint existente, ambas as flags substituem o valor atual em vez de adicioná-lo, então passe a lista completa que você deseja e use uma string vazia para limpá-la. Endpoints implantados a partir do catálogo já vêm com flags de engine ajustadas, então verifique hf endpoints describe antes de sobrescrevê-las:
>>> hf endpoints update my-endpoint \
--container-args "--enable-auto-tool-choice --tool-call-parser lfm2"Implante uma imagem de mecanismo gerenciado
--custom-image sozinho implanta um container arbitrário. Adicione --engine para executá-lo como um dos engines gerenciados pela API (vllm, sglang, tgi, tei, llamacpp, hf-serve, …), o que libera as configurações desse engine, incluindo --tensor-parallel-size e --data-parallel-size. vLLM e SGLang usam um acelerador por padrão, enquanto o endpoint recebe todos os aceleradores da sua instância, portanto, deixar ambos sem configuração carregaria o modelo em um único acelerador e deixaria os demais ociosos, ainda assim reportando saúde, motivo pelo qual a API agora rejeita essa configuração:
>>> hf endpoints deploy gpt-oss-120b-vllm \
--repo openai/gpt-oss-120b \
--framework custom \
--accelerator gpu --vendor aws --region us-east-1 \
--instance-type nvidia-h200 --instance-size x8 \
--engine vllm --custom-image vllm/vllm-openai:v0.23.0 \
--tensor-parallel-size 8Isso não é o mesmo que --container-args "... --tp 8" acima: --tensor-parallel-size grava na configuração model.image do engine, que é o que a API valida em relação à quantidade de aceleradores da instância, enquanto --container-args apenas adiciona uma flag à linha de comando. Use --container-args para flags de engine sem campo de imagem e para contêineres personalizados simples, que não possuem campos de paralelismo.
Para retreinar um endpoint em execução, passe os tamanhos individualmente. model.image é enviado como um todo e requer url, portanto, a imagem atual do endpoint é obtida e atualizada no local:
>>> hf endpoints update gpt-oss-120b-vllm --tensor-parallel-size 4 --data-parallel-size 2hf endpoints update também aceita --custom-image e --engine, a única maneira de alterar a imagem de um endpoint pela CLI. Esse caminho substitui model.image em vez de fazer um patch, então execute hf endpoints describe primeiro e passe de volta o que você deseja manter.
catálogo de endpoints do hf
Use hf endpoints catalog para interagir com o Catálogo de Modelos do Inference Endpoints. Implante modelos diretamente do catálogo com configurações otimizadas.
Cada modelo do catálogo vem com uma ou mais receitas: uma combinação de hardware e motor que foi testada para ele. hf endpoints catalog ls imprime uma linha por receita, então um modelo com uma receita para GPU e uma para Neuron aparece duas vezes:
# List available catalog models
>>> hf endpoints catalog ls
REPO_ID TASK LICENSE ACCELERATOR ENGINE GGUF_FILE RECIPE_ID
----------------------------------- ------------------ ---------- ----------- -------- ----------------------------- -------------------------
meta-llama/Llama-3.1-8B-Instruct text-generation Llama 3.1 gpu vllm sizzling-biryani-g4xsi1ac
meta-llama/Llama-3.1-8B-Instruct text-generation Llama 3.1 neuron vllmNeuron artisanal-quinoa-yz9ynamx
bartowski/QwQ-32B-Preview-GGUF text-generation Apache 2.0 gpu llamacpp QwQ-32B-Preview-Q8_0.gguf baked-orange-m863gx7d
# Narrow it down
>>> hf endpoints catalog ls --engine vllm --task text-generation --search llama --limit 10--accelerator, --engine, --license, --task, --search e --limit filtram no servidor.
# Deploy the default recipe of a model
>>> hf endpoints catalog deploy --repo meta-llama/Llama-3.2-1B-Instruct
# Deploy an exact recipe listed above
>>> hf endpoints catalog deploy --recipe artisanal-quinoa-yz9ynamx
# Deploy with a custom name
>>> hf endpoints catalog deploy --repo meta-llama/Llama-3.2-1B-Instruct --name my-llama-endpointCom --repo, a receita padrão pode ser refinada com --accelerator (cpu, gpu, neuron) e --gguf-file (para modelos que possuem uma receita por quantização). Ambos são rejeitados em conjunto com --recipe, que já designa uma única receita.