Treine em um servidor com GPU, em um cluster SLURM ou em uma máquina atrás de NAT

Novo na v2.14.0

Este tutorial tira o treinamento de modelos do Potato do servidor de anotação e o leva a uma máquina com GPU. O tutorial é para um administrador de estudo cujo servidor de anotação é uma pequena VM na nuvem ou um laptop, e cujas GPUs ficam em um servidor do laboratório, em um cluster universitário ou em uma estação de trabalho à qual o servidor não consegue se conectar. Para cada um dos três backends remotos, a página cobre quando escolher o backend, o que a máquina remota precisa ter instalado, a configuração, o comando de verificação, o que acontece durante uma execução, como cancelar uma execução e as falhas mais prováveis. O tutorial supõe um projeto que já treina no servidor de anotação, como o projeto de avaliações em Treine o seu primeiro modelo.

Quatro lugares onde uma execução pode rodar

Um backend é o lugar onde uma execução de treinamento roda. O Potato sempre tem o backend local, um subprocesso no servidor de anotação. Você nomeia os outros backends em model_training.backends:

Escolha ssh quando o servidor de anotação consegue entrar na máquina com GPU com uma chave ssh. Escolha slurm quando as GPUs ficam atrás do escalonador SLURM e a máquina em que você consegue entrar é um nó de login. Escolha agent quando nenhuma conexão pode ser aberta do servidor para a máquina com GPU, porque o agente abre todas as conexões. Uma estação de trabalho atrás de um roteador doméstico ou de um firewall de campus é o caso usual de um agente. As predições e o resultado da execução chegam ao servidor a partir de todo backend, então a gravação de volta e a pontuação em itens reservados funcionam da mesma forma onde quer que o treinador tenha rodado. Todo treinador, exceto decision-calibrate, roda em qualquer backend.

A configuração do projeto

A configuração abaixo é o projeto de avaliações do primeiro tutorial com os três backends remotos adicionados. Um projeto real precisa apenas dos backends que usa, e cada backend tem a sua própria seção adiante. max_wall_seconds: 3600 interrompe qualquer execução que não terminou em uma hora. Em um backend ssh ou agent, o servidor verifica o limite a cada segundo, então uma execução que trava em uma máquina remota não ocupa a fila de execuções por mais tempo que o limite:

annotation_task_name: "Review Sentiment"
task_dir: "."
data_files:
  - "data/reviews.json"
item_properties:
  id_key: "id"
  text_key: "text"
output_annotation_dir: "annotation_output"
admin_api_key: "change-me"
 
annotation_schemes:
  - annotation_type: "radio"
    name: "sentiment"
    description: "Is this review positive or negative?"
    labels: ["positive", "negative"]
 
model_training:
  enabled: true
  backend: gpu-server        # the default for runs; leave out to keep runs local
  max_wall_seconds: 3600
  writeback:
    schemas: ["sentiment"]
    include_unlabeled: true
    min_confidence: 0.6
  backends:
    gpu-server:
      type: ssh
      host: gpu.example.org
      python: /opt/conda/bin/python3
      gpus: auto
      min_free_gpu_mb: 4000
    cluster:
      type: slurm
      host: login.cluster.example.org
      python: /opt/conda/bin/python3
      job_python: /shared/envs/train/bin/python
      remote_dir: /shared/projects/me/potato-training
      gres: gpu:1
      time: "04:00:00"
      prelude: ["module load cuda/12.4"]
    lab-workstation:
      type: agent
      queue_timeout_s: 3600

Valide a configuração antes de iniciar o servidor:

potato validate config.yaml --strict

O validador informa uma chave que o tipo de backend não aceita, um backend ssh ou slurm sem host, um remote_dir do SLURM em /tmp e um model_training.backend que não nomeia nenhum backend. O servidor não inicia diante dos mesmos erros, então um pyhton escrito errado interrompe o servidor na inicialização em vez de enviar as execuções ao python3 padrão.

O menu Runs on e a API

A página Training em /admin/training tem um menu Runs on que lista todos os backends com o tipo e o host, por exemplo gpu-server (ssh to gpu.example.org). model_training.backend define a entrada que o menu seleciona primeiro, e a tabela Runs registra onde cada execução rodou na coluna Ran on. Uma execução iniciada pela API nomeia o backend no campo backend do corpo da requisição:

curl -X POST -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  http://localhost:8000/admin/training/api/runs \
  -d '{"trainer": "hf-text-classification", "schemas": ["sentiment"], "backend": "cluster"}'

Um nome de backend que não está na configuração é recusado com 409. O retreinamento automático usa model_training.backend, a menos que auto_retrain.backend nomeie outro backend, e Modelo no ciclo cobre auto_retrain por inteiro. Uma execução roda por vez, qualquer que seja o backend, e uma execução iniciada enquanto outra está em andamento espera na fila.

Treinando nesta máquina

Verifique qual dispositivo uma execução local recebe antes de levar as execuções para outro lugar. Com o device: auto padrão, uma execução local usa primeiro CUDA, depois o Metal da Apple (mps) e depois a CPU, e device: cuda:1 nomeia uma GPU. O comando de verificação mostra o dispositivo que uma execução local usaria:

potato training check local config.yaml

Em um Mac com Apple silicon, o comando mostra local: this machine, Apple Metal (mps). Um dispositivo que você pede e que não existe recorre à CPU ou a outro acelerador, com um aviso no log da execução. Quando a resposta é CPU e o treinador ajusta um transformer, leve a execução para um backend remoto, descrito adiante. A configuração lista device, num_threads e max_ram_mb para execuções locais.

Um servidor com GPU por ssh

Um backend ssh executa o treinador em uma máquina que o servidor de anotação alcança por ssh, tipicamente um servidor de GPU do laboratório. O Potato inicia tudo do lado remoto por conta própria, então nada é instalado ou iniciado ali à mão além do Python e dos pacotes do treinador. O host com GPU não precisa ter o Potato instalado, porque o Potato copia o próprio código-fonte Python para o host na primeira execução e reaproveita a cópia até que o código-fonte mude.

Requisitos de um backend ssh

A conta com que o servidor de anotação roda precisa de uma chave ssh que entre no host com GPU sem pedir nada. O Potato executa ssh com BatchMode=yes, então um pedido de senha faz a execução falhar de imediato em vez de travar. Executar ssh gpu.example.org true com essa conta precisa dar certo, e uma chave com frase secreta funciona quando o ssh-agent guarda a chave. O valor de host é qualquer nome que o ssh aceite, e um alias de ~/.ssh/config funciona. As chaves user, port e identity_file são passadas ao ssh como -l, -p e -i.

O host com GPU precisa de Python 3.8 ou mais recente e dos pacotes do treinador que você executa. Para hf-text-classification, esses pacotes são torch, transformers e peft, o conteúdo do extra potato-annotation[train-text]. A página Treinadores nomeia a instalação de cada treinador. Quando o interpretador do host não tem um pacote, aponte python para um interpretador que o tenha ou liste o pacote em packages. Com packages definido, o Potato cria um ambiente virtual em remote_dir com --system-site-packages e instala os pacotes listados no ambiente uma única vez. A versão do torch com CUDA do próprio host continua visível dentro do ambiente:

model_training:
  enabled: true
  backends:
    gpu-server:
      type: ssh
      host: gpu.example.org
      python: /opt/conda/bin/python3
      packages: ["transformers>=4.46.0", "peft>=0.13.0"]
      gpus: auto
      min_free_gpu_mb: 4000
      num_threads: 8

Com gpus: auto, cada execução usa a GPU com mais memória livre e se recusa a iniciar quando nenhuma GPU tem min_free_gpu_mb livre (padrão 2000). O Potato compara a memória livre, e não a utilização, porque uma placa com pouca utilização em um servidor compartilhado ainda pode ter pouca memória livre. Defina min_free_gpu_mb perto da memória de que o seu treinador precisa. gpus: "1" fixa a GPU 1, "0,1" fixa duas GPUs e gpus: none treina na CPU. Um host sem nenhuma GPU também treina na CPU com auto. num_threads define OMP_NUM_THREADS, MKL_NUM_THREADS e OPENBLAS_NUM_THREADS para a execução. Alguns servidores compartilhados definem OMP_NUM_THREADS=1 nos shells de login, e num_threads sobrepõe o valor do shell de login.

O comando de verificação de um backend ssh

Execute a verificação a partir do servidor de anotação, com a conta com que o servidor roda:

potato training check gpu-server config.yaml

O comando se conecta e informa a versão do Python remoto, cada GPU com a memória livre e a utilização, a GPU que uma execução receberia e os pacotes de treinamento que faltam ao interpretador remoto. Uma GPU para a qual o torch instalado não tem kernels é marcada com (torch there has no kernels for it), e gpus: auto ignora essa GPU. --json imprime o mesmo relatório em JSON. O comando termina com 0 quando uma execução poderia iniciar e com 1 caso contrário. O botão Check, ao lado do menu Runs on, executa a mesma verificação a partir da página Training.

Etapas de uma execução ssh

Para cada execução, o Potato realiza estas etapas:

1. Conecta com ssh e abre um encaminhamento reverso de um socket unix no /tmp remoto de volta ao servidor de anotação.
2. Verifica o interpretador, lê nvidia-smi e escolhe a GPU.
3. Copia o código-fonte do Potato para remote_dir/code/<hash> quando o host não tem essa versão e cria o ambiente virtual quando packages está definido e o ambiente não existe. remote_dir tem como padrão ~/.cache/potato-training.
4. Inicia python -m potato.training.agent para a execução. O token da execução chega ao agente pela entrada padrão e nunca aparece em uma linha de comando, porque as linhas de comando são visíveis a todas as contas de um servidor compartilhado.
5. O agente baixa o pacote da execução com itens, rótulos e mídia. O agente executa o mesmo worker de treinamento que o backend local executa e devolve o progresso, as predições e o resultado pelo socket.
6. Quando a execução tem sucesso, o Potato copia o diretório de artefatos de volta para o artifacts/ da execução, apaga o diretório remoto do job e fecha a conexão.

A linha de etapa na página Training acompanha essas fases, por exemplo copying Potato's code to gpu.example.org e waiting for the agent on gpu.example.org. O log da execução nomeia o Python do host e a GPU que a execução recebeu.

Um ajuste fino completo copia o modelo inteiro de volta, e em um link lento um modelo de 330 MB leva minutos. A linha de etapa mostra quanto do modelo já chegou. Arquivos maiores que max_artifact_mb (padrão 2048) ficam no host com GPU e são nomeados no log da execução. fetch_artifacts: false deixa todos os arquivos do modelo no host com GPU, e keep_remote: true mantém o diretório remoto do job para inspeção. O envio ao Hugging Face Hub pela página da execução precisa dos arquivos do modelo no servidor de anotação, então um modelo deixado no host com GPU não é enviado pela página da execução.

O socket unix é criado com o modo 0600, então apenas a conta com que o Potato entrou consegue se conectar pelo socket. As requisições pelo socket chegam ao servidor de anotação como requisições de loopback. Um servidor iniciado com debug: true concede acesso de administrador a requisições de loopback. Qualquer pessoa que possa usar essa conta no host com GPU tem então acesso de administrador a um servidor em modo debug enquanto uma execução está em andamento. Mantenha debug desligado em um servidor que treina por ssh.

Cancelamento e tempo limite do heartbeat

Cancel run, na página Training, chega ao agente pelo socket, na resposta ao próximo relatório de progresso do agente. O agente envia SIGTERM ao worker e SIGKILL se o worker ainda estiver rodando após model_training.grace_seconds (padrão 20), que o servidor envia junto com o job. Um job de um servidor Potato mais antigo não traz grace_seconds, e o agente espera então 20 segundos. No servidor, a execução termina como cancelada depois que grace_seconds passam, e o servidor fecha a sessão ssh do agente. Uma execução cujo agente não envia nada por heartbeat_timeout_s (padrão 120) falha, e agent.log, no diretório da execução, guarda a última saída do agente.

Um cluster SLURM

Um backend slurm serve a um cluster cujas GPUs ficam atrás do escalonador SLURM. Em um cluster assim, a máquina que o Potato alcança por ssh é um nó de login sem GPUs, e os nós de computação não alcançam o Potato de forma alguma. O Potato então inicia o agente no nó de login, como faz um backend ssh, e o agente envia apenas o worker de treinamento a um nó de computação com sbatch. O progresso volta por um arquivo em armazenamento que o nó de login e os nós de computação compartilham.

Requisitos de um backend SLURM

O nó de login precisa de uma chave ssh sem pedido de senha e de Python 3.8 ou mais recente para o agente, como o host de um backend ssh. O nó de login também precisa de sbatch, squeue e scancel no PATH. O agente também chama scontrol onde o cluster tem o comando. O Potato nunca chama srun nem sacct, então um cluster com srun desativado e sem banco de dados de contabilização funciona. remote_dir é obrigatório e precisa estar em armazenamento que os nós de computação compartilham, porque o job lê o pacote e grava o modelo ali. O validador informa um erro para um remote_dir em /tmp ou /var/tmp, porque esses diretórios são locais a cada nó.

Os nós de computação precisam de um interpretador com os pacotes do treinador, nomeado por job_python. packages não é aceito em um backend SLURM, porque um ambiente virtual criado no nó de login pode não rodar nos nós de computação. Aponte job_python para um ambiente que os nós de computação têm e ponha carregamentos de módulos ou uma ativação de ambiente em prelude:

model_training:
  enabled: true
  backends:
    cluster:
      type: slurm
      host: login.cluster.example.org
      python: /opt/conda/bin/python3                    # on the login node, for the agent
      job_python: /shared/envs/train/bin/python         # on the compute nodes, for the worker
      remote_dir: /shared/projects/me/potato-training   # storage the compute nodes share
      partition: gpu
      gres: gpu:1
      time: "04:00:00"
      prelude: ["module load cuda/12.4"]

Toda chave ssh vale para um backend SLURM, exceto gpus e packages. As GPUs vêm de gres, e o escalonador define CUDA_VISIBLE_DEVICES para as GPUs que ele concede. Um job sem gres não recebe GPU. As configurações do SLURM correspondem aos flags do sbatch:

Um time acima de 6 horas faz potato validate e a inicialização do servidor informarem model_training.backends.cluster.time is 12:00:00. A job that holds a GPU for more than 6 hours is long on a shared cluster; check its policy, e potato validate --strict falha com o aviso. Quando a política do cluster permitir o job mais longo, reconheça o aviso para esse backend em um bloco validation de nível superior, que apenas potato validate lê:

validation:
  acknowledge:
    - "model_training.backends.cluster.time is"

Cada entrada é comparada com o texto do aviso como uma substring que diferencia maiúsculas de minúsculas, de pelo menos 12 caracteres, e um aviso correspondente passa para a lista de reconhecidos e deixa de falhar --strict. Uma entrada que nomeia o backend reconhece o aviso apenas desse backend. Uma entrada curta demais, ou que não corresponde a nenhum aviso, vira um aviso por si mesma.

O comando de verificação de um backend SLURM

potato training check cluster config.yaml

A verificação entra no nó de login e confirma que sbatch, squeue e scancel estão no PATH e que remote_dir não está em /tmp. O relatório nomeia a versão do Python no nó de login e o job_python que o job vai executar. A verificação não vê quais pacotes os nós de computação têm, então um pacote ausente em um nó de computação aparece como uma execução que falhou, com o erro de importação no log da execução. Execute um primeiro job curto com um time pequeno para encontrar esses problemas cedo.

Etapas de uma execução SLURM

O Potato se conecta ao nó de login e copia o código para lá, como em um backend ssh. O agente realiza então estas etapas:

1. Baixa o pacote para remote_dir/jobs/<run>/.
2. Escreve job.sh e envia o script com sbatch --parsable. O log da execução registra Submitted SLURM job com o ID do job e os flags.
3. No diretório do job, o worker no nó de computação grava os eventos em events.jsonl, os erros em stderr.log e o código de saída em exit_code. A saída do próprio SLURM vai para slurm.out.
4. O agente lê events.jsonl conforme o arquivo cresce e repassa o progresso ao servidor. O agente executa squeue uma vez por poll_interval_s, e o log da execução registra cada mudança no estado do job na fila, por exemplo SLURM job 4242: PENDING (Priority) e depois RUNNING on node07.
5. Quando o job termina, o agente envia as predições e informa o resultado. Os artefatos voltam ao servidor e o diretório do job é removido, como em um backend ssh.

Cancel run envia scancel --full --signal=TERM ao job e depois um scancel simples se o worker não parou. Quando a sessão ssh com o nó de login cai, o agente cancela o seu job, e a alocação de GPU é liberada. Quando o próprio escalonador encerra um job, a execução falha com o motivo do escalonador, lido de scontrol show job ou de slurm.out. Os motivos que o Potato informa incluem o limite de tempo, uma falha de nó, preempção, falta de memória e um scancel vindo de fora do Potato.

A suíte de testes do Potato executa a sequência do SLURM contra um substituto de sbatch, squeue e scancel, e cobre o envio do job, o status na fila, o repasse do progresso e o cancelamento. Os limites de partição e a política de preempção variam de cluster para cluster, então acompanhe o log da execução do seu primeiro job em um cluster novo.

Um agente iniciado à mão em um nó de login que alcança o servidor também pode enviar jobs ao SLURM, com potato training agent --server ... --backend <name> --workdir <shared dir> --slurm-config slurm.json. O arquivo slurm.json guarda as configurações da tabela acima como um objeto JSON, e --workdir precisa estar em armazenamento que os nós de computação compartilham.

Uma máquina que o Potato não alcança

Um backend agent serve a uma máquina à qual o servidor de anotação não consegue se conectar, como uma estação de trabalho atrás de NAT. Alguém inicia potato training agent nessa máquina, e o agente consulta o servidor em busca de jobs. O agente não precisa de nenhuma porta de entrada, porque o agente abre todas as conexões. Um cancelamento chega ao agente na resposta do servidor ao próximo relatório de progresso do agente. Os arquivos do modelo ficam na máquina de treinamento, e apenas as predições e o resultado voltam.

Requisitos de um backend agent

A máquina de treinamento precisa do Potato instalado, dos pacotes do treinador que você executa e de uma rota de rede até a URL do servidor de anotação. Para hf-text-classification, uma única instalação cobre o Potato e os pacotes do treinador:

pip install "potato-annotation[train-text]"

O servidor precisa apenas da entrada do backend. Um backend agent aceita type, description, heartbeat_timeout_s (padrão 120) e queue_timeout_s, e nenhuma outra chave:

model_training:
  enabled: true
  backends:
    lab-workstation:
      type: agent
      queue_timeout_s: 3600

Registrando e iniciando o agente

Emita um token para o backend no servidor de anotação:

potato training register lab-workstation config.yaml

O comando imprime o token uma única vez, com os comandos a executar na máquina de treinamento:

Token for backend 'lab-workstation' (shown once; registering again replaces it):
 
  <token>
 
On the training machine:
 
  export POTATO_TRAINING_TOKEN=<token>
  potato training agent --server http://<this-server>:8000 --backend lab-workstation

Inicie o agente na máquina de treinamento com a URL real do servidor:

export POTATO_TRAINING_TOKEN=<the token>
potato training agent --server https://annotate.example.org --backend lab-workstation

O agente executa os jobs do seu backend até que você o pare. --token-file lê o token de um arquivo em vez de POTATO_TRAINING_TOKEN, e --python nomeia o interpretador em que o worker de treinamento roda, sendo o padrão o interpretador do próprio agente. --once sai após um job, --workdir move os arquivos do agente de ~/.cache/potato-training, e --keep mantém o pacote de cada job. Registrar o nome de novo emite um novo token e invalida o token antigo.

potato training check lab-workstation config.yaml imprime o registro do token do backend, com last_seen preenchido depois que um agente se conecta. Antes do registro, o comando imprime no token issued yet e o comando de registro a executar.

Etapas de uma execução agent

Uma execução para um backend agent espera no estado queued até que um agente peça trabalho. Com queue_timeout_s: 3600, a execução falha após uma hora sem agente, e sem queue_timeout_s a execução espera até que você a cancele. O agente baixa o pacote como um arquivo tar.gz e retoma de onde parou um download interrompido, com até cinco tentativas. O agente então executa o worker, envia o progresso, envia predictions.jsonl e informa o código de saída. O servidor responde 413 a um arquivo de predições maior que max_predictions_mb (padrão 512).

Os arquivos do modelo ficam na máquina de treinamento em --workdir, e o artifact_uri do registro da execução nomeia o host e o diretório. Se o agente não alcança o servidor por 300 segundos durante uma execução, o agente cancela a execução por conta própria. Uma execução cujo agente não envia nada por heartbeat_timeout_s falha no servidor com No word from the agent on lab-workstation for 120 seconds.

Falhas comuns

Cada entrada dá a mensagem no log da execução ou no relatório de verificação e depois a correção. A lista completa para todos os backends e treinadores está na seção de solução de problemas do repositório original.

• ssh to gpu.example.org failed: Permission denied. O Potato precisa de uma chave que funcione sem pedido de senha. ssh gpu.example.org true, com a conta do servidor, precisa dar certo.
• /opt/conda/bin/python3 was not found on gpu.example.org. Defina python no backend como um interpretador que exista no host.
• No GPU has 4000 MB free. Toda GPU do host está mais ocupada do que min_free_gpu_mb permite. potato training check gpu-server config.yaml lista as GPUs. Espere, reduza o limite ou fixe uma GPU com gpus: "1".
• Trainer 'hf-text-classification' could not be imported. O interpretador remoto não tem um pacote de que o treinador precisa. Aponte python para um interpretador que tenha o pacote ou liste o pacote em packages. Em um backend SLURM, corrija o ambiente que job_python nomeia.
• This host's torch has no kernels for any of its GPUs. O torch remoto foi compilado para GPUs mais novas que as do host. Instale uma versão do torch para essas GPUs ou use outro host.
• No word from the agent on gpu-server for 120 seconds. A máquina remota ou a rede sumiu. Em um backend ssh, agent.log, no diretório da execução, tem a última saída do agente.
• The copy from gpu.example.org sent nothing for 180 s. A rede até o host parou enquanto o modelo era copiado de volta. As predições da execução já estão armazenadas, e apenas os arquivos do modelo faltam em artifacts/.
• login.cluster.example.org has no sbatch on PATH, so it cannot submit jobs. O host não é o nó de login do cluster, ou os comandos estão em um PATH que apenas um shell de login define. Defina PATH em env, no backend.
• SLURM job 4242 ended before the worker finished: it reached its time limit. Aumente time no backend ou treine com menos itens. Defina keep_remote: true para manter slurm.out e poder lê-lo após outras falhas do escalonador.
• Uma execução em um backend agent permanece em fila. Nenhum agente com esse nome de backend está consultando o servidor. Inicie um agente com potato training agent --backend lab-workstation e verifique o token com Check na página Training.
• nvrtc: error: failed to open libnvrtc-builtins.so.13.0. O torch do host e o pacote nvidia-cuda-nvrtc são de versões diferentes do CUDA. Instale o nvidia-cuda-nvrtc que corresponde à versão do torch ou aponte python para outro interpretador.

Leitura complementar

• A visão geral do treinamento de modelos cobre a página Training, o ciclo de treinamento e a publicação de um modelo no Hugging Face Hub.
• A configuração lista todas as chaves de model_training, as pontuações em itens reservados e onde as execuções são armazenadas.
• Ajuste fino de LLMs cobre os treinadores que mais precisam de uma GPU remota, com LoRA e pesos-base de 4 bits.
• A referência original sobre onde as execuções rodam traz a tabela completa de chaves de cada backend, e a seção do protocolo do agente documenta as rotas para quem escreve o próprio agente.