Como implantar Ray Train no EKS com EFA sem criar uma imagem própria

O exemplo da AWS executa um job distribuído com Ray Train no Amazon EKS usando o contêiner publicado, sem criar uma imagem própria. A configuração distribui o Qwen2.5-1.5B com PyTorch FSDP e bfloat16 por oito GPUs NVIDIA L4 em duas instâncias g6.12xlarge. Para usar EFA na comunicação entre os workers, coloque as instâncias na mesma zona de disponibilidade e VPC.

O que o exemplo executa

A AWS publicou o tutorial em 28 de outubro de 2026. Ele combina Amazon EKS, KubeRay, Ray Train e o Elastic Fabric Adapter (EFA), uma interface de rede voltada à comunicação entre instâncias. O exemplo usa um nó de sistema para coordenar o cluster e dois nós com GPU para o treinamento.

O container publicado é usado sem alterações tanto no Ray head quanto nos workers: public.ecr.aws/deep-learning-containers/ray:train-ml-cuda-v1.1. A pilha listada nessa imagem inclui Ray 2.58.0, PyTorch 2.13.0, torchvision 0.28.0, CUDA 13.0.2 e NCCL 2.29.7.

Pré-requisitos: capacidade e posicionamento do EFA

Para as duas instâncias g6.12xlarge, a AWS indica 96 vCPUs de capacidade sob demanda da família G ou uma reserva de capacidade sob demanda existente. A documentação da AWS lista g6.12xlarge entre os tipos compatíveis com EFA, mas a disponibilidade de instâncias habilitadas para EFA varia por região. Confira a região escolhida antes de provisionar o cluster.

O tráfego EFA não atravessa zonas de disponibilidade nem limites de VPC. Portanto, os dois workers precisam compartilhar a mesma zona e VPC para a comunicação EFA do exemplo. O tráfego IP comum da interface ENA é uma rota separada e pode ser roteado normalmente.

Configure os workers e a rede

Cada pod worker solicita quatro GPUs e um dispositivo EFA. A configuração também define FI_PROVIDER=efa, NCCL_NET_PLUGIN=ofi, NCCL_SOCKET_IFNAME=eth0 e NCCL_DEBUG=INFO. O caminho de comunicação coletiva é NCCL, plugin AWS OFI NCCL, libfabric e EFA.

Mantenha alinhadas a quantidade de GPUs solicitada pelo Kubernetes e a propriedade num-gpus do Ray. O exemplo também define requests iguais a limits por pod worker: quatro GPUs, um EFA, 40 CPUs e 160Gi de memória. Essa correspondência evita que o Kubernetes reserve uma quantidade diferente da que o Ray anuncia aos workers.

A configuração usa sub-redes privadas em uma VPC e um NAT Gateway para baixar o contêiner e os pesos do modelo. O job é enviado de dentro do Ray head por kubectl exec; a porta 8265, usada pelo servidor de jobs, não fica exposta fora do cluster. A porta 6379 é usada pelo armazenamento de controle do Ray.

Implante o cluster e envie o job

Siga a ordem das dependências para que os workers encontrem os recursos de GPU e EFA quando o RayCluster iniciar.

1. Configure scripts/env.sh. Defina os parâmetros do cluster, da região, dos nós, da imagem e do treinamento usados pelo exemplo.
2. Execute deploy_all.sh. O script verifica a capacidade e cria o cluster e o grupo de nós. A opção --plan permite visualizar as ações de infraestrutura antes de executá-las.
3. Instale ou confira os plugins de dispositivos. Verifique os plugins de GPU e EFA para que o Kubernetes possa disponibilizar esses recursos nos nós.
4. Instale o KubeRay. O operador gerencia o recurso RayCluster no Kubernetes.
5. Execute deploy_ray_train_job.sh. O script gera e aplica o manifesto do job, verifica os recursos alocáveis e inicia o RayCluster. A opção --train encadeia o treinamento após a configuração da infraestrutura.
6. Envie o job de dentro do Ray head. O exemplo usa kubectl exec para iniciar o trabalho no pod head, sem expor a porta 8265 à rede externa do cluster.

Confira os recursos e o transporte do NCCL

Antes de aguardar os pods, verifique se cada nó de GPU anuncia GPUs e EFA como recursos alocáveis. A configuração do nó também usa o rótulo nvidia.com/gpu.present=true. Se o pod não solicitar um dispositivo EFA ou não puder acessá-lo, o NCCL pode recorrer a sockets TCP, e o job pode continuar sem usar o caminho EFA.

Com NCCL_DEBUG=INFO, inspecione o transporte escolhido nos registros do NCCL e confirme que EFA está no caminho. O script do exemplo encerra com erro se não encontrar EFA na rota. Uma solicitação de recurso presente no manifesto, por si só, não substitui essa checagem do transporte ativo.

O que a execução demonstra

O código gera IDs de tokens aleatórios, em vez de treinar com um corpus real. Para um fine-tuning com dados, a AWS indica substituir essa entrada por um pipeline com Ray Data ou DataLoader. Assim, o exemplo configura uma execução distribuída e sua comunicação entre GPUs, mas não uma demonstração de ajuste fino com dados reais.

A AWS relata throughput duas vezes maior com EFA do que com TCP usando o mesmo código nesse exemplo. O relato não vem acompanhado de valores numéricos nem de condições de benchmark, portanto o resultado permanece ligado à configuração descrita.