Executando Cargas de Trabalho em Hugging Face Jobs

Guia Detalhado

Leia o guia detalhado antes de executar esta habilidade. Ele contém o procedimento completo e o material de referência. Trate seus requisitos de segurança, pré-requisitos e validação como obrigatórios. Para trabalho focado, carregue as seções relevantes; para trabalho de ponta a ponta, leia o guia completamente.

Quando Usar Esta Habilidade

Use esta habilidade quando os usuários quiserem:

• Executar cargas de trabalho Python em infraestrutura de nuvem
• Executar jobs sem configuração local de GPU/TPU
• Processar dados em escala
• Executar inferência em lote ou experimentos
• Agendar tarefas recorrentes
• Usar GPUs/TPUs para qualquer carga de trabalho
• Persistir resultados no Hugging Face Hub

Lista de Verificação de Pré-requisitos

Antes de iniciar qualquer job, verifique:

✅ Conta e Autenticação

• Conta Hugging Face com plano Pro, Team ou Enterprise (Jobs exigem plano pago)
• Login autenticado: Verifique com hf_whoami()
• HF_TOKEN para Acesso ao Hub ⚠️ CRÍTICO - Necessário para quaisquer operações do Hub (enviar modelos/datasets, baixar repositórios privados, etc.)
• O token deve ter as permissões apropriadas (leitura para downloads, escrita para uploads)

✅ Uso de Token (Veja a seção Uso de Token para detalhes)

Quando tokens são necessários:

• Enviar modelos/datasets para o Hub
• Acessar repositórios privados
• Usar APIs do Hub em scripts
• Quaisquer operações autenticadas do Hub

Como fornecer tokens:

# hf_jobs MCP tool — $HF_TOKEN is auto-replaced with real token:
{"secrets": {"HF_TOKEN": "$HF_TOKEN"}}

# HfApi().run_uv_job() — MUST pass actual token:
from huggingface_hub import get_token
secrets={"HF_TOKEN": get_token()}

⚠️ CRÍTICO: O placeholder $HF_TOKEN é SUBSTITUÍDO AUTOMATICAMENTE APENAS pela ferramenta MCP hf_jobs. Ao usar HfApi().run_uv_job(), VOCÊ DEVE passar o token real via get_token(). Passar a string literal "$HF_TOKEN" resulta em um token inválido de 9 caracteres e erros 401.

Guia de Uso de Token

Entendendo Tokens

O que são Tokens HF?

• Credenciais de autenticação para o Hugging Face Hub
• Necessários para operações autenticadas (envio, repositórios privados, acesso à API)
• Armazenados com segurança em sua máquina após hf auth login

Tipos de Token:

• Token de Leitura - Pode baixar modelos/datasets, ler repositórios privados
• Token de Escrita - Pode enviar modelos/datasets, criar repositórios, modificar conteúdo
• Token de Organização - Pode agir em nome de uma organização

Quando Tokens São Necessários

Sempre Necessários:

• Enviar modelos/datasets para o Hub
• Acessar repositórios privados
• Criar novos repositórios
• Modificar repositórios existentes
• Usar APIs do Hub programaticamente

Não Necessários:

• Baixar modelos/datasets públicos
• Executar jobs que não interagem com o Hub
• Ler informações de repositórios públicos

Como Fornecer Tokens para Jobs

Método 1: Token Automático (Recomendado)

hf_jobs("uv", {
    "script": "your_script.py",
    "secrets": {"HF_TOKEN": "$HF_TOKEN"}  # ✅ Automatic replacement
})

Como funciona:

• $HF_TOKEN é um placeholder que é substituído pelo seu token real
• Usa o token da sua sessão logada (hf auth login)
• Método mais seguro e conveniente
• O token é criptografado no lado do servidor quando passado como um segredo

Benefícios:

• Nenhuma exposição de token no código
• Usa sua sessão de login atual
• Atualizado automaticamente se você fizer login novamente
• Funciona perfeitamente com ferramentas MCP

Método 2: Token Explícito (Não Recomendado)

hf_jobs("uv", {
    "script": "your_script.py",
    "secrets": {"HF_TOKEN": "hf_abc123..."}  # ⚠️ Hardcoded token
})

Quando usar:

• Somente se o token automático não funcionar
• Testando com um token específico
• Tokens de organização (use com cautela)

Preocupações de segurança:

• Token visível no código/logs
• Deve ser atualizado manualmente se o token for rotacionado
• Risco de exposição do token

Método 3: Variável de Ambiente (Menos Seguro)

hf_jobs("uv", {
    "script": "your_script.py",
    "env": {"HF_TOKEN": "hf_abc123..."}  # ⚠️ Less secure than secrets
})

Diferença de segredos:

• Variáveis env são visíveis nos logs do job
• secrets são criptografados no lado do servidor
• Sempre prefira secrets para tokens

Usando Tokens em Scripts

Em seu script Python, os tokens estão disponíveis como variáveis de ambiente:

# /// script
# dependencies = ["huggingface-hub"]
# ///

import os
from huggingface_hub import HfApi

# O token está automaticamente disponível se passado via segredos
token = os.environ.get("HF_TOKEN")


…