Começar

Treinamento de modelos com o Ultralytics YOLO

Ultralytics YOLO ecosystem and integrations

Introdução#

Treinar um modelo de aprendizado profundo envolve fornecer dados ao modelo e ajustar seus parâmetros para que ele possa fazer previsões precisas. O modo Train do Ultralytics YOLO26 treina modelos de detecção de objetos e de outras tarefas de visão computacional com eficiência em hardware moderno. Este guia aborda os detalhes necessários para começar a treinar os teus próprios modelos com YOLO26. Se ainda não instalaste o Ultralytics, começa pelo guia de início rápido.

Confira a prévia inédita do YOLO27 para ver exemplos de treinamento planejados.



Assista: Como treinar um modelo YOLO com seu conjunto de dados personalizado no Google Colab.

Por que escolher o Ultralytics YOLO para treinamento?#

Motivos para usar o modo Train do YOLO26:

  • Eficiência: Aproveita ao máximo o teu hardware, seja em uma configuração com uma única GPU, seja escalando para várias GPUs.
  • Versatilidade: Treina com conjuntos de dados personalizados, além de conjuntos disponíveis, como COCO, VOC e ImageNet.
  • Facilidade de uso: Interfaces simples, mas poderosas, de CLI e Python para uma experiência de treinamento descomplicada.
  • Flexibilidade de hiperparâmetros: Uma ampla variedade de hiperparâmetros personalizáveis para ajustar o desempenho do modelo. Para ter mais controle, podes personalizar o trainer.
  • Treinamento na nuvem: Treine em GPUs na nuvem pela plataforma Ultralytics, com métricas em tempo real e salvamento automático de checkpoints.

Principais recursos do modo de treinamento#

Veja a seguir alguns recursos importantes do modo de treinamento do YOLO26:

  • Download automático de conjuntos de dados: As configurações de conjuntos de dados que incluem uma fonte de download são baixadas automaticamente no primeiro uso, por exemplo, yolo train data=coco8.yaml. Consulte a Visão geral dos conjuntos de dados para conhecer os formatos e conjuntos de dados compatíveis.
  • Suporte a várias GPUs: Escala o treinamento entre várias GPUs para reduzir o tempo de treinamento.
  • Configuração de hiperparâmetros: É possível modificar os hiperparâmetros por meio de arquivos de configuração YAML ou argumentos da CLI.
  • Visualização e monitoramento: Acompanhe as métricas de treinamento em tempo real e visualize o processo de aprendizado para obter melhores insights.

Exemplos de uso#

Treina YOLO26n no conjunto de dados COCO8 por 100 épocas, com tamanho de imagem 640. O dispositivo de treinamento pode ser especificado usando o argumento device. Se nenhum argumento for passado, a GPU device=0 será usada quando disponível; caso contrário, será usado device='cpu'.

Erro de multiprocessamento no Windows

No Windows, você pode receber um RuntimeError ao iniciar o treinamento como um script. Para resolver o problema, adicione um bloco if __name__ == "__main__": antes do código de treinamento.

Exemplo de treinamento com uma GPU ou CPU

O dispositivo é determinado automaticamente. Se houver uma GPU disponível, ela será usada (dispositivo CUDA 0 por padrão); caso contrário, o treinamento será iniciado na CPU.

from ultralytics import YOLO

# Carregar um modelo
model = YOLO("yolo26n.yaml")  # crie um novo modelo a partir de YAML
model = YOLO("yolo26n.pt")  # carregue um modelo pré-treinado (recomendado para treinamento)
model = YOLO("yolo26n.yaml").load("yolo26n.pt")  # crie a partir de YAML e transfira os pesos

# Treinar o modelo
results = model.train(data="coco8.yaml", epochs=100, imgsz=640)

Treinamento com várias GPUs#

O treinamento com várias GPUs aproveita melhor o hardware disponível ao distribuir a carga de treinamento entre várias GPUs. Esse recurso está disponível tanto pela API do Python quanto pela interface de linha de comando. Para ativar o treinamento com várias GPUs, especifica os IDs dos dispositivos GPU que queres usar.

Exemplo de treinamento com várias GPUs

Para treinar com 2 GPUs (dispositivos CUDA 0 e 1), usa os comandos a seguir. Adiciona mais GPUs conforme necessário.

from ultralytics import YOLO

# Carregar um modelo
model = YOLO("yolo26n.pt")  # carregue um modelo pré-treinado (recomendado para treinamento)

# Treine o modelo com duas GPUs
results = model.train(data="coco8.yaml", epochs=100, imgsz=640, device=[0, 1])

# Treine o modelo com as duas GPUs mais ociosas
results = model.train(data="coco8.yaml", epochs=100, imgsz=640, device=[-1, -1])
Suporte a várias GPUs no Windows

O treinamento com várias GPUs não funciona no Windows com os pacotes oficiais do PyTorch para torch>=2.4. O Ultralytics inicia o DDP por meio de torch.distributed.run, cuja etapa de rendezvous cria um TCPStore que usa o backend libuv por padrão desde o PyTorch 2.4; os pacotes oficiais do Windows são compilados sem libuv. O treinamento é encerrado imediatamente com:

RuntimeError: use_libuv was requested but PyTorch was built without libuv support

Definir USE_LIBUV=0 não resolve o problema, porque o rendezvous cria diretamente o TCPStore, e esse caminho de código nunca lê a variável. Treine no Linux ou no WSL2 para usar várias GPUs, ou treine com uma única GPU usando device=0 no Windows.

Treinamento com várias GPUs e código personalizado

Ao especificar vários dispositivos (por exemplo, device=[0, 1]), o Ultralytics inicia internamente uma nova instância do trainer e executa torch.distributed.run nos bastidores. Isso funciona com o uso padrão da CLI e com scripts Python sem modificações.

No entanto, se o seu script tiver componentes personalizados, como um treinador, validador, conjunto de dados ou pipeline de aumento de dados personalizados, esses objetos não poderão ser serializados e transferidos automaticamente para os subprocessos DDP. Nesse caso, você deve iniciar o script diretamente com torch.distributed.run:

python -m torch.distributed.run --nproc_per_node 2 your_training_script.py

O treinamento em GPU AMD usa uma versão do PyTorch com ROCm e a sintaxe padrão device=0 ou device=cuda:0. Consulte o guia de integração com AMD para obter informações sobre a instalação do ROCm, treinamento com várias GPUs, observações sobre AMP e inferência do MIGraphX com modelos exportados.

O treinamento em GPU Intel usa device=xpu:0 ou vários IDs XPU com uma versão do PyTorch que fornece XCCL.

Treinamento em NPU Huawei Ascend#

O Ultralytics oferece suporte ao treinamento e à validação em NPUs Huawei Ascend por meio de torch_npu. Instale versões compatíveis entre si do CANN, PyTorch e torch_npu seguindo o guia de instalação da extensão Ascend para PyTorch e, em seguida, carregue o ambiente CANN antes de iniciar o Ultralytics:

source /usr/local/Ascend/ascend-toolkit/set_env.sh
Exemplo de treinamento em NPU Ascend
from ultralytics import YOLO

model = YOLO("yolo26n.pt")

# Treine em uma NPU Ascend
results = model.train(data="coco8.yaml", epochs=100, imgsz=640, device="npu:0")

# Treine em duas NPUs Ascend com HCCL
results = model.train(data="coco8.yaml", epochs=100, imgsz=640, device="npu:0,1")

Os recursos padrão de treinamento, incluindo AMP, validação, salvamento de checkpoints e retomada, usam a NPU ativa. O AutoBatch está disponível para treinamento com uma única NPU, enquanto vários IDs de NPU iniciam o treinamento distribuído por meio do HCCL. Consulte o guia de integração com Huawei Ascend para saber como exportar e implantar modelos após o treinamento.

Treinamento em GPU ociosa#

O treinamento em GPUs ociosas seleciona automaticamente as GPUs menos utilizadas em sistemas com várias GPUs, para que não precises escolher os dispositivos manualmente. O sistema classifica as GPUs disponíveis pelo uso e pela VRAM livre.

Exemplo de treinamento em GPU ociosa

Para selecionar e usar automaticamente a(s) GPU(s) mais ociosa(s) no treinamento, use o parâmetro de dispositivo -1. Isso é especialmente útil em ambientes de computação compartilhados ou servidores com vários usuários.

from ultralytics import YOLO

# Carregar um modelo
model = YOLO("yolo26n.pt")  # carregue um modelo pré-treinado (recomendado para treinamento)

# Treine usando a GPU mais ociosa
results = model.train(data="coco8.yaml", epochs=100, imgsz=640, device=-1)

# Treine usando as duas GPUs mais ociosas
results = model.train(data="coco8.yaml", epochs=100, imgsz=640, device=[-1, -1])

O algoritmo de seleção automática prioriza GPUs com:

  1. Percentuais de utilização atuais mais baixos
  2. Mais memória disponível (VRAM livre)

Isso é especialmente útil em ambientes de computação compartilhados ou ao executar vários trabalhos de treinamento ao mesmo tempo, pois os dispositivos são escolhidos com base nas condições atuais sempre que uma execução é iniciada.

Treinamento com MPS no Apple Silicon#

Os modelos Ultralytics YOLO podem ser treinados em Apple silicon usando a estrutura Metal Performance Shaders (MPS), que executa tarefas de computação e processamento de imagens nas GPUs personalizadas da Apple.

Para treinar em Apple silicon, especifica mps como dispositivo ao iniciar o treinamento, em Python ou pela linha de comando:

Exemplo de treinamento com MPS
from ultralytics import YOLO

# Carregar um modelo
model = YOLO("yolo26n.pt")  # carregue um modelo pré-treinado (recomendado para treinamento)

# Treine o modelo com MPS
results = model.train(data="coco8.yaml", epochs=100, imgsz=640, device="mps")

Retomada de treinamentos interrompidos#

Retomar o treinamento a partir de um checkpoint salvo é útil quando uma execução é interrompida inesperadamente ou quando queres continuar treinando um modelo com novos dados ou por mais épocas.

Ao retomar o treinamento, o Ultralytics YOLO carrega os pesos do último modelo salvo e também restaura o estado do otimizador, o agendador da taxa de aprendizado, o número da época e o conjunto de dados. O treinamento continua então de onde parou. Passa um data= explícito junto com resume para continuar usando outro conjunto de dados, em vez do conjunto de dados do checkpoint.

Para retomar o treinamento no Ultralytics YOLO, define o argumento resume como True ao chamar o método train e especifica o caminho para o arquivo .pt que contém os pesos do modelo parcialmente treinado.

Para retomar uma execução de treinamento interrompida em Python ou pela linha de comando:

Exemplo de retomada do treinamento
from ultralytics import YOLO

# Carregar um modelo
model = YOLO("path/to/last.pt")  # carregar um modelo parcialmente treinado

# Retomar o treinamento
results = model.train(resume=True)

Ao definir resume=True, a função train continuará o treinamento de onde parou, usando o estado armazenado no arquivo path/to/last.pt. Se o argumento resume for omitido ou definido como False, a função train iniciará uma nova sessão de treinamento. Uma execução que envia dados para a Ultralytics Platform continua usando o mesmo modelo da Platform quando é retomada.

Lembre-se de que, por padrão, os checkpoints são salvos ao final de cada época, ou em intervalos fixos usando o argumento save_period; portanto, você precisa concluir pelo menos 1 época para retomar uma execução de treinamento.

Configurações de treino#

As configurações de treinamento dos modelos YOLO incluem vários hiperparâmetros e configurações usados durante o processo de treinamento. Essas configurações influenciam o desempenho, a velocidade e a precisão do modelo. Entre as principais configurações de treinamento estão o tamanho do lote, a taxa de aprendizado, o momentum e o decaimento dos pesos. Além disso, a escolha do otimizador, da função de perda e da composição do conjunto de dados de treinamento pode afetar o processo. Ajustar cuidadosamente essas configurações e fazer experimentos com elas é essencial para otimizar o desempenho.

Otimizador MuSGD#

No YOLO26, MuSGD é um otimizador híbrido que combina atualizações padrão de SGD com atualizações ortogonalizadas no estilo Muon.

Ele é recomendado para execuções de treinamento mais longas do YOLO26 e conjuntos de dados maiores, nos quais as atualizações ortogonalizadas do Muon podem ajudar a estabilizar a otimização.

Somente os pesos lineares 2D e os filtros convolucionais 4D (redimensionados para 2D) recebem a atualização no estilo Muon junto com SGD; todos os outros parâmetros, como os pesos da normalização em lote e os termos de viés, continuam usando SGD padrão.

Quando optimizer=auto é usado, o Ultralytics seleciona automaticamente MuSGD para execuções de treinamento mais longas (normalmente quando as iterações > 10000). Para execuções mais curtas, o treinador usa AdamW. No modo auto, o treinador também seleciona a taxa de aprendizado, portanto um lr0 fornecido pelo usuário é ignorado. Para controlar essas configurações manualmente, selecione um otimizador explicitamente, por exemplo, optimizer=AdamW lr0=0.001.

Exemplo de uso:

yolo train model=yolo26n.pt data=coco8.yaml optimizer=MuSGD

Confira a implementação em ultralytics/optim/muon.py e a lógica de seleção automática do otimizador em BaseTrainer.build_optimizer.

ArgumentoTipoPadrãoDescrição
modelstrNoneEspecifica o ficheiro do modelo usado no treino. Aceita o caminho para um modelo pré-treinado .pt ou para um ficheiro de configuração .yaml. É essencial para definir a estrutura do modelo ou inicializar os pesos.
datastrNoneCaminho para o YAML do conjunto de dados (por exemplo, coco8.yaml), que contém os caminhos para os dados de validação e de treino, os nomes das classes e o número de classes. A classificação requer um diretório do conjunto de dados ou o nome de um conjunto de dados integrado (por exemplo, imagenet10).
epochsint100Número total de épocas de treino. Cada época corresponde a uma passagem completa pelo conjunto de dados. Ajustar este valor pode afetar a duração do treino e o desempenho do modelo.
timefloatNoneDuração máxima do treino, em horas. Se definido, substitui o argumento epochs, permitindo que o treino pare automaticamente após o período especificado. Útil em cenários com limitações de tempo.
patienceint100Número de épocas a aguardar sem melhoria nas métricas de validação antes de interromper o treino antecipadamente. Ajuda a evitar o sobreajuste, parando o treino quando o desempenho estabiliza.
batchint ou float16Tamanho do lote, com três modos: definir como um número inteiro (por exemplo, batch=16), modo automático para 60% da memória GPU disponível (batch=-1) ou modo automático com uma fração especificada da memória GPU disponível (batch=0.70).
imgszint640Tamanho de imagem pretendido para o treino. As imagens são redimensionadas para quadrados cujos lados correspondem ao valor especificado (se rect=False), preservando a proporção nos modelos YOLO, mas não no RT-DETR. Afeta a precisão do modelo e a complexidade computacional.
saveboolTruePermite guardar pontos de controlo do treino e os pesos finais do modelo. Útil para retomar o treino ou para a implementação do modelo.
save_periodint-1Frequência de gravação dos pontos de controlo do modelo, especificada em épocas. O valor -1 desativa esta funcionalidade. Útil para guardar modelos intermédios durante sessões de treino longas.
cachebool ou strFalsePermite guardar em cache as imagens do conjunto de dados na memória (True/ram), no disco (disk) ou desativa a cache (False). Acelera o treino ao reduzir as operações de E/S do disco, à custa de um maior consumo de memória.
tilebool ou intFalseExpande cada imagem de origem em blocos fixos para treinamento, com rótulos recortados e janelas negativas mantidas. True usa imgsz; um inteiro positivo define o tamanho do bloco. Consulta Recorte em blocos de alta resolução.
deviceint ou str ou listNoneEspecifica o(s) dispositivo(s) de computação para o treino: uma única GPU (device=0), várias GPUs (device=[0,1]), CPU (device=cpu), MPS para Apple silicon (device=mps), NPU Huawei Ascend (device=npu:0 ou device=npu:0,1), Intel XPU (device=xpu:0), ou seleção automática de uma GPU inativa (device=-1) ou de várias GPUs inativas (device=[-1,-1]).
workersint8Número de threads de trabalho para carregar dados (por RANK no treino com várias GPUs). Afeta a velocidade do pré-processamento e do envio dos dados para o modelo, sendo especialmente útil em configurações com várias GPUs.
projectstrNoneNome do diretório do projeto onde as saídas do treinamento são salvas. Um caminho relativo é colocado em runs_dir/<task>, enquanto um caminho absoluto é usado sem alterações.
namestrNoneNome da execução de treino. Usado para criar um subdiretório na pasta do projeto, onde são armazenados os registos e os resultados do treino.
exist_okboolFalseSe True, permite substituir um diretório de projeto/nome existente. Útil para experiências iterativas sem ter de limpar manualmente os resultados anteriores.
save_dirstrNoneEspecifica o diretório exato onde os resultados da execução são guardados, substituindo a combinação project/name. O caminho é usado tal como está, sem incrementação automática, pelo que execuções consecutivas reutilizam o mesmo diretório.
pretrainedbool ou strTrueDetermina se o treino começa com pesos pré-treinados. Pode ser um valor booleano ou um caminho em formato de string para os pesos a carregar. pretrained=False treina com pesos inicializados aleatoriamente, mantendo a arquitetura do modelo.
cls_remapboolTrueAo ajustar o modelo em vários conjuntos de dados, copia as linhas da camada de classificação pré-treinada para o novo modelo sempre que os nomes das classes coincidem. Assim, as classes correspondentes mantêm o viés aprendido e também os pesos, se a largura da camada não mudar. Aplica-se quer o número de classes seja diferente, quer seja igual mas com uma ordem diferente.
optimizerstr'auto'Escolha do otimizador para o treino. As opções incluem SGD, MuSGD, Adam, Adamax, AdamW, NAdam, RAdam, RMSProp ou auto para escolher AdamW ou MuSGD com base no número de iterações de treino. Afeta a velocidade e a estabilidade da convergência.
seedint0Define a semente aleatória do treino, garantindo a reprodutibilidade dos resultados entre execuções com as mesmas configurações.
deterministicboolTrueForça a utilização de algoritmos determinísticos, garantindo a reprodutibilidade, mas podendo afetar o desempenho e a velocidade devido à restrição de algoritmos não determinísticos.
verboseboolTrueAtiva a saída detalhada durante o treino, mostrando barras de progresso, métricas por época e informações adicionais sobre o treino na consola.
single_clsboolFalseTrata todas as classes dos conjuntos de dados multiclasse como uma única classe durante o treino. Útil para tarefas de classificação binária ou quando o objetivo é detetar a presença de objetos em vez de os classificar.
classeslist[int]NoneEspecifica uma lista de IDs de classes a usar no treino. Útil para filtrar e focar apenas em determinadas classes durante o treino.
rectboolFalseAtiva a estratégia de preenchimento mínimo — as imagens de um lote recebem o mínimo de preenchimento necessário para atingir um tamanho comum, com o lado mais longo igual a imgsz. Isso pode melhorar a eficiência e a velocidade, mas afetar a precisão do modelo. O treinador padrão do YOLO usa rect=True para a validação de detecção, segmentação, pose e OBB, independentemente desta configuração.
multi_scalefloat0.0Varia aleatoriamente imgsz em cada lote em +/- multi_scale (por exemplo, 0.25 -> 0.75x a 1.25x), arredondando para múltiplos do stride do modelo; 0.0 desativa o treino multiescala.
cos_lrboolFalseUtiliza um programador de taxa de aprendizagem cosseno, ajustando a taxa de aprendizagem segundo uma curva cosseno ao longo das épocas. Ajuda a gerir a taxa de aprendizagem para obter uma melhor convergência.
close_mosaicint10Desativa a ampliação de dados mosaico nas últimas N épocas para estabilizar o treino antes de este terminar. Definir como 0 desativa esta funcionalidade.
resumeboolFalseRetoma o treinamento a partir do último checkpoint salvo. Carrega automaticamente os pesos do modelo, o estado do otimizador e a contagem de épocas, continuando o treinamento de onde parou.
ampbool ou strTrueDefine a precisão do treino: True ou "fp16" usa FP16, "bf16" usa BF16 em dispositivos CUDA compatíveis e False ou "fp32" usa FP32.
quantizeint ou strNoneDefine como 8 (ou "int8") para o treino com reconhecimento de quantização INT8 (QAT), que ajusta o modelo com quantização simulada no ciclo para que os pesos tolerem a exportação INT8. Consulta Treino com reconhecimento de quantização.
fractionfloat, int ou list1.0Subconjunto do conjunto de dados, definido como proporção/contagem ou lista [train, val, test]. 1 indica a divisão completa, os números inteiros superiores a 1 são contagens de imagens e apenas a entrada de teste opcional aceita 0/0.0 para indicar nenhum. As listas de dois elementos mantêm o conjunto de teste completo.
profileboolFalseAtiva a criação de perfis de velocidade do ONNX e do TensorRT durante o treino, o que é útil para otimizar a implementação do modelo.
freezeint ou listNoneCongela as primeiras N camadas do modelo ou camadas específicas pelo índice ou pelo nome do módulo (23.cv2, sem o model. inicial), reduzindo o número de parâmetros treináveis. Útil para o ajuste fino ou a aprendizagem por transferência.
lr0float0.01Taxa de aprendizado inicial (por exemplo, SGD=1E-2, Adam=1E-3). Ignorada com o valor padrão optimizer='auto'; especifique um otimizador explicitamente para usá-la.
lrffloat0.01Taxa de aprendizagem final como fração da taxa inicial = (lr0 * lrf), usada em conjunto com os programadores para ajustar a taxa de aprendizagem ao longo do tempo.
momentumfloat0.937Momentum do SGD/MuSGD ou beta1 para otimizadores Adam. Com optimizer=auto, o AdamW usa 0.9; o MuSGD começa em 0.9, depois o aquecimento interpola de warmup_momentum a momentum. Sem aquecimento, o MuSGD automático permanece em 0.9.
weight_decayfloat0.0005Termo de regularização L2, que penaliza pesos elevados para evitar o sobreajuste.
warmup_epochsfloat3.0Épocas de aquecimento (são permitidas frações), limitadas para deixar a última época sem aquecimento. A taxa de aprendizagem aumenta linearmente de 0 (viés de warmup_bias_lr) até o valor programado, o momentum de warmup_momentum até momentum e o acúmulo de gradientes de 1 lote até o valor nominal (consulte nbs), todos alcançando seus valores-alvo ao fim do aquecimento.
warmup_momentumfloat0.8Momentum inicial para otimizadores com termo de momentum (SGD, MuSGD, RMSprop), aumentado linearmente até momentum ao fim do aquecimento. O beta1 da família Adam não passa por aquecimento.
warmup_bias_lrfloat0.1Taxa de aprendizagem dos parâmetros de viés durante a fase de aquecimento, que ajuda a estabilizar o treino do modelo nas primeiras épocas. É definida automaticamente como 0.0 com o valor predefinido optimizer='auto'; especifica um otimizador explicitamente para a usar.
distill_modelstrNoneCaminho para um ponto de controlo do modelo professor (por exemplo, yolo26x.pt) para destilação de conhecimento. Quando definido, o modelo aluno é treinado com uma perda de destilação adicional, orientada pelo modelo professor congelado.
disfloat6.0Peso da perda de destilação adicionada às perdas de deteção padrão. Valores mais altos aumentam a influência da orientação das características do modelo professor.
boxfloat7.5Peso da componente de perda da caixa na função de perda, que determina a importância dada à previsão precisa das coordenadas da caixa delimitadora.
clsfloat0.5Peso da perda de classificação na função de perda total, que afeta a importância da previsão correta da classe em relação às outras componentes.
cls_pwfloat0.0Expoente para ponderar classes e lidar com o desequilíbrio entre classes usando o inverso da frequência de cada classe. 0.0 desativa a ponderação de classes; 1.0 aplica a ponderação inversa da frequência na totalidade. Os valores entre 0 e 1 aplicam uma ponderação parcial.
dflfloat1.5Peso do termo de regressão da distância da caixa: perda focal de distribuição (DFL) quando a cabeça de deteção usa reg_max > 1; perda L1 nas distâncias normalizadas das caixas para o YOLO26 sem DFL (reg_max: 1).
posefloat12.0Peso da perda de pose nos modelos treinados para estimativa de pose, que determina a importância dada à previsão precisa dos pontos-chave da pose.
kobjfloat1.0Peso da perda de objetividade dos pontos-chave nos modelos de estimativa de pose, que equilibra a confiança da deteção com a precisão da pose.
rlefloat1.0Peso da perda de estimativa da verosimilhança logarítmica residual nos modelos de estimativa de pose, que afeta a precisão da localização dos pontos-chave.
anglefloat1.0Peso da perda angular nos modelos obb, que afeta a precisão das previsões dos ângulos das caixas delimitadoras orientadas.
dlogfloat1.0Peso da perda logarítmica invariante à escala (SILog) nos modelos de estimativa de profundidade, o principal termo que determina a precisão da profundidade.
dgradfloat0.5Peso da perda de gradiente nos modelos de estimativa de profundidade, que penaliza erros nas arestas de profundidade e incentiva limites de superfície mais nítidos.
dlamfloat1.0Fator de foco da variância da perda SILog nos modelos de estimativa de profundidade. 1.0 torna a perda totalmente invariante à escala, enquanto 0.0 a reduz a um RMSE logarítmico simples.
nbsint64Tamanho nominal do lote. Os gradientes são acumulados ao longo de round(nbs / batch) lotes por etapa do otimizador (no mínimo 1 e, fora do modo time, no máximo o número total de lotes da execução), e weight_decay é escalado por batch * accumulate / nbs para corresponder.
overlap_maskboolTrueDetermina se as máscaras dos objetos devem ser combinadas numa única máscara para o treino ou mantidas separadas para cada objeto. Em caso de sobreposição, ao combinar, a máscara mais pequena é sobreposta à maior.
mask_ratioint4Fator de redução da resolução das máscaras de segmentação, que afeta a resolução das máscaras usadas durante o treino. Não altera a resolução das máscaras previstas.
dropoutfloat0.0Taxa de dropout para regularização em tarefas de classificação, que evita o sobreajuste ao omitir unidades aleatoriamente durante o treino.
valboolTrueAtiva a validação durante o treino, permitindo avaliar periodicamente o desempenho do modelo num conjunto de dados separado.
splitstr'val'Divisão do conjunto de dados usada para validação durante o treinamento: val, test ou train. As métricas selecionam best.pt e acionam a parada antecipada.
nmsbool, opcionalNoneSeleciona a cabeça de inferência usada para a validação de cada época, a seleção de pontos de controlo e a paragem antecipada. None ou True usa a abordagem um-para-muitos com NMS; False usa a cabeça sem NMS, quando disponível. Ambas as cabeças mantêm as respetivas perdas de treino.
plotsboolTrueGera e guarda gráficos das métricas de treino e validação, bem como exemplos de previsões, proporcionando uma visão visual do desempenho do modelo e da evolução da aprendizagem.
compilebool ou strFalseAtiva a compilação de grafos torch.compile do PyTorch 2.x com backend='inductor'. Aceita True → "default", False → desativa, ou um modo em formato de string, como "default", "reduce-overhead", "max-autotune-no-cudagraphs". Se não for suportado, recorre à execução ansiosa e apresenta um aviso.
channels_lastboolNoneUsa o formato de memória channels_last (NHWC) para convoluções durante o treino. None ativa-o automaticamente em CUDA com PyTorch 1.11 ou superior, exceto no Windows e no AMD ROCm, onde apresentou desempenho inferior. False desativa-o, e True solicita-o explicitamente. O treino em CPU ou MPS mantém-se sempre em NCHW (True é ignorado com um aviso).
max_detint300Número máximo de detecções por imagem durante a validação do treinamento. Para detect, segment, pose e OBB, o valor padrão 300 aumenta até a maior contagem de objetos rotulados no treinamento/validação somente quando essa contagem ultrapassa 300. Os demais valores permanecem fixos; ultrapassar o limite gera um aviso.
Nota sobre as configurações do tamanho do lote

O argumento batch aceita três tipos de valores, e o trainer adiciona duas proteções:

  • Tamanho do lote fixo: Define um valor inteiro (por exemplo, batch=16), especificando diretamente o número de imagens por lote. O treinamento com várias GPUs divide esse lote global igualmente entre as GPUs, por isso o valor deve ser pelo menos igual ao número de GPUs; o restante é descartado (por exemplo, batch=15 em 2 GPUs treina 7 imagens por GPU).
  • Modo automático (60% da memória GPU): use batch=-1 para ajustar automaticamente o tamanho do lote para usar aproximadamente 60% da memória CUDA disponível para o treinamento.
  • Modo automático com fração de utilização: defina um valor de fração (por exemplo, batch=0.70) para ajustar o tamanho do lote com base na fração especificada da memória GPU disponível.
  • Nova tentativa automática em caso de OOM: se ocorrer um erro de falta de memória CUDA durante a primeira época, o treinador reduzirá automaticamente o tamanho do lote pela metade e tentará novamente (até 3 vezes). Isso se aplica somente ao treinamento com uma única GPU; o treinamento com várias GPUs (DDP) gerará o erro imediatamente.
  • Nenhum tamanho adequado encontrado: Se nenhum tamanho de lote candidato gerar um perfil utilizável, o AutoBatch apresenta um RuntimeError claro em vez de recorrer silenciosamente a um valor predefinido não relacionado.

Configurações de aumento de dados e hiperparâmetros#

As técnicas de aumento de dados são essenciais para melhorar a robustez e o desempenho dos modelos YOLO, pois introduzem variabilidade nos dados de treinamento e ajudam o modelo a generalizar melhor para dados que ainda não viu. A tabela a seguir descreve o objetivo e o efeito de cada argumento de aumento:

ArgumentoTipoPadrãoTarefas suportadasIntervaloDescrição
hsv_hfloat0.015detect, segment, semantic, depth, classify, pose, obb0.0 - 1.0Ajusta o matiz da imagem numa fração da roda das cores, introduzindo variabilidade cromática. Ajuda o modelo a generalizar em diferentes condições de iluminação. Para classify, isto aplica-se apenas quando auto_augment=None.
hsv_sfloat0.7detect, segment, semantic, depth, classify, pose, obb0.0 - 1.0Altera a saturação da imagem numa determinada fração, afetando a intensidade das cores. É útil para simular diferentes condições ambientais. Para classify, isto aplica-se apenas quando auto_augment=None.
hsv_vfloat0.4detect, segment, semantic, depth, classify, pose, obb0.0 - 1.0Modifica o valor (brilho) da imagem numa determinada fração, ajudando o modelo a ter um bom desempenho em várias condições de iluminação. Para classify, isto aplica-se apenas quando auto_augment=None.
degreesfloat0detect, segment, semantic, depth, pose, obb0.0 - 180Roda a imagem aleatoriamente dentro do intervalo de graus especificado, melhorando a capacidade do modelo de reconhecer objetos em várias orientações.
translatefloat0.1detect, segment, semantic, depth, pose, obb0.0 - 1.0Desloca a imagem na horizontal e na vertical numa fração do tamanho da imagem, ajudando o modelo a aprender a detetar objetos parcialmente visíveis.
scalefloat | tuple0.5detect, segment, semantic, depth, classify, pose, obb0 - 1 ou uma tupla (min, max) explícita (não para classify)Redimensiona a imagem por um fator de escala, simulando objetos a diferentes distâncias da câmara.
shearfloat0detect, segment, semantic, depth, pose, obb-180 - +180Aplica uma deformação de cisalhamento à imagem segundo um grau especificado, imitando o efeito de observar objetos de diferentes ângulos.
perspectivefloat0detect, segment, semantic, depth, pose, obb0.0 - 0.001Aplica uma transformação de perspetiva aleatória à imagem, melhorando a capacidade do modelo de compreender objetos no espaço 3D.
flipudfloat0detect, segment, semantic, depth, classify, pose, obb0.0 - 1.0Inverte a imagem de cabeça para baixo com a probabilidade especificada, aumentando a variabilidade dos dados sem afetar as características do objeto.
fliplrfloat0.5detect, segment, semantic, depth, classify, pose, obb0.0 - 1.0Inverte a imagem da esquerda para a direita com a probabilidade especificada, o que é útil para aprender objetos simétricos e aumentar a diversidade do conjunto de dados.
bgrfloat0detect, segment, semantic, depth, pose, obb0.0 - 1.0Inverte os canais da imagem de RGB para BGR com a probabilidade especificada, o que é útil para aumentar a robustez a uma ordem incorreta dos canais.
mosaicfloat1detect, segment, semantic, pose, obb0.0 - 1.0Combina quatro imagens de treinamento em uma, simulando diferentes composições de cena e interações entre objetos. Eficaz para compreender cenas complexas.
mixupfloat0detect, segment, semantic, pose, obb0.0 - 1.0Combina duas imagens e as respetivas etiquetas, criando uma imagem composta. Melhora a capacidade de generalização do modelo ao introduzir ruído nas etiquetas e variabilidade visual.
cutmixfloat0detect, segment, semantic, pose, obb0.0 - 1.0Combina partes de duas imagens, criando uma mistura parcial e mantendo regiões distintas. Melhora a robustez do modelo ao criar cenários de oclusão.
copy_pastefloat0segment, semantic, obb0.0 - 1.0Fração de objetos elegíveis colados; flip espelha-os dentro da imagem, enquanto mixup também usa o valor como probabilidade de aplicação entre imagens.
copy_paste_modestrflipsegment, semantic, obb-Especifica a estratégia copy-paste a utilizar. As opções incluem 'flip' e 'mixup'.
auto_augmentstrrandaugmentclassify-Aplica uma política de aumento de dados predefinida ('randaugment', 'autoaugment' ou 'augmix') para melhorar o desempenho do modelo através da diversidade visual.
erasingfloat0.4classify0.0 - 1.0Apaga aleatoriamente regiões da imagem durante o treino para incentivar o modelo a focar-se em características menos óbvias.
augmentationslistNonedetect, segment, semantic, depth, pose, obb-Transformações Albumentations personalizadas para aumento de dados avançado (apenas API Python). Aceita uma lista de objetos de transformação para necessidades especializadas de aumento de dados.

Essas configurações podem ser ajustadas para atender aos requisitos específicos do conjunto de dados e da tarefa em questão. Fazer experimentos com diferentes valores pode ajudar a encontrar a melhor estratégia de aumento.

Informações

Para saber mais sobre as operações de aumento de dados no treinamento, consulte a seção de referência.

Registro de dados#

As métricas de treinamento, os gráficos e os checkpoints são sempre gravados no diretório da execução, e o Ultralytics também os envia para qualquer rastreador de experimentos que tenhas instalado e ativado: Comet, ClearML, TensorBoard, MLflow, Weights & Biases e DVCLive. Cada logger é ativado ou desativado nas configurações do Ultralytics, por exemplo, yolo settings tensorboard=True. As três configurações mais comuns são mostradas abaixo.

Comet#

Comet é uma plataforma que permite a cientistas de dados e desenvolvedores acompanhar, comparar, explicar e otimizar experimentos e modelos. Ela fornece métricas em tempo real, diferenças de código e acompanhamento de hiperparâmetros.

Para usar o Comet:

Exemplo
# pip install comet_ml
import comet_ml

comet_ml.login()

Lembre-se de entrar na sua conta do Comet pelo site e obter sua chave de API. Você precisará adicioná-la às variáveis de ambiente ou ao script para registrar seus experimentos.

ClearML#

ClearML é uma plataforma de código aberto que automatiza o acompanhamento de experimentos e ajuda a compartilhar recursos com eficiência. Ela foi projetada para ajudar as equipes a gerenciar, executar e reproduzir seu trabalho de ML com mais eficiência.

Para usar o ClearML:

Exemplo
# pip install clearml
import clearml

clearml.browser_login()

Depois de executar este script, você precisará entrar na sua conta do ClearML pelo navegador e autenticar sua sessão.

TensorBoard#

TensorBoard é um conjunto de ferramentas de visualização para TensorFlow. Ele permite visualizar o grafo do TensorFlow, gerar gráficos de métricas quantitativas sobre a execução do grafo e exibir dados adicionais, como as imagens que passam por ele.

Para usar o TensorBoard no Google Colab:

Exemplo
%load_ext tensorboard
tensorboard --logdir ultralytics/runs # replace with 'runs' directory

Para usar o TensorBoard localmente, executa o comando abaixo e consulta os resultados em localhost:6006.

Exemplo
tensorboard --logdir ultralytics/runs # replace with 'runs' directory

Isso carregará o TensorBoard e o direcionará ao diretório onde os registros do treinamento estão salvos.

Depois de configurar o logger, inicia o treinamento como de costume. As métricas de treinamento são registradas automaticamente na plataforma escolhida, onde podes monitorar o desempenho ao longo do tempo, comparar modelos e identificar pontos a melhorar.

O que fazer a seguir#

Valide seu modelo treinado com dados separados para verificar sua precisão no mundo real e, em seguida, exporte o modelo para ONNX, TensorRT ou outro formato de implantação. Vai treinar com seus próprios dados em vez do COCO8? Formate-os primeiro usando o guia de conjuntos de dados.

Perguntas frequentes#

  • Sim. O treinamento na nuvem da Ultralytics Platform inclui créditos gratuitos para você começar. Envie seu conjunto de dados, selecione um modelo e uma GPU e treine diretamente no navegador.

  • Para treinar um modelo de detecção de objetos usando o Ultralytics YOLO26, você pode usar a API Python ou a CLI. Veja abaixo um exemplo de cada opção:

    Exemplo de treinamento com uma GPU ou CPU
    from ultralytics import YOLO
    
    # Carregar um modelo
    model = YOLO("yolo26n.pt")  # carregue um modelo pré-treinado (recomendado para treinamento)
    
    # Treinar o modelo
    results = model.train(data="coco8.yaml", epochs=100, imgsz=640)

    Para mais detalhes, consulte a seção Configurações de treinamento.

  • Os principais recursos do modo Train do Ultralytics YOLO26 incluem:

    • Download automático de conjuntos de dados: baixa automaticamente conjuntos de dados padrão, como COCO, VOC e ImageNet.
    • Suporte a várias GPUs: dimensione o treinamento para várias GPUs e acelere o processamento.
    • Configuração de hiperparâmetros: personalize os hiperparâmetros por meio de arquivos YAML ou argumentos da CLI.
    • Visualização e monitoramento: acompanhamento das métricas de treinamento em tempo real para obter melhores insights.

    Esses recursos tornam o treinamento eficiente e personalizável de acordo com suas necessidades. Para mais detalhes, consulte a seção Principais recursos do modo Train.

  • Para retomar o treinamento de uma sessão interrompida, defina o argumento resume como True e especifique o caminho para o último checkpoint salvo.

    Exemplo de retomada do treinamento
    from ultralytics import YOLO
    
    # Carregar o modelo parcialmente treinado
    model = YOLO("path/to/last.pt")
    
    # Retomar o treinamento
    results = model.train(resume=True)

    Consulte a seção sobre retomada de treinamentos interrompidos para mais informações.

  • O desequilíbrio entre classes ocorre quando algumas classes têm significativamente menos exemplos do que outras nos dados de treino. Isso pode fazer com que o modelo tenha um desempenho ruim nas classes raras. O Ultralytics YOLO oferece suporte à ponderação de classes por meio do argumento cls_pw para resolver esse problema. A ponderação da perda funciona melhor como última etapa, após coletar e superamostrar as classes raras, conforme descrito em Como lidar com o desequilíbrio entre classes.

    O argumento cls_pw controla a intensidade da ponderação das classes com base na frequência inversa das classes:

    • cls_pw=0.0 (padrão): desativa a ponderação de classes
    • cls_pw=1.0: aplica a ponderação total pela frequência inversa
    • Valores entre 0.0 e 1.0: aplicam ponderação parcial para desbalanceamentos moderados

    Os pesos das classes são calculados como (1.0 / class_counts) ^ cls_pw e normalizados para que a média seja igual a 1.0. class_counts é o número de objetos rotulados por classe ou, para classificação, o número de imagens de treinamento por classe; classes sem rótulos de treinamento, como as excluídas por classes=, recebem um peso de 1.0. Em segmentação semântica, os pesos são calculados com base na frequência de pixels, como (1.0 / ln(1.02 + p)) ^ cls_pw, em que p é a proporção de pixels de treinamento rotulados em cada classe; assim, uma classe sem pixels rotulados recebe o maior peso.

    Treinamento com conjunto de dados desbalanceado
    from ultralytics import YOLO
    
    # Carregar um modelo pré-treinado
    model = YOLO("yolo26n.pt")
    
    # Treinar com ponderação total de classes para dados muito desbalanceados
    results = model.train(data="custom.yaml", epochs=100, imgsz=640, cls_pw=1.0)
    
    # Ou usar ponderação parcial (0.25) para desbalanceamento moderado
    results = model.train(data="custom.yaml", epochs=100, imgsz=640, cls_pw=0.25)
    Dica

    Comece com cls_pw=0.25 para conjuntos de dados moderadamente desbalanceados e aumente para 1.0 se as classes raras ainda tiverem baixo desempenho. Você pode conferir os pesos das classes calculados nos registros do treinamento para verificar a distribuição dos pesos.

  • Sim, o Ultralytics YOLO26 é compatível com o treinamento em chips Apple silicon usando a estrutura Metal Performance Shaders (MPS). Especifica mps como dispositivo de treinamento.

    Exemplo de treinamento com MPS
    from ultralytics import YOLO
    
    # Carregar um modelo pré-treinado
    model = YOLO("yolo26n.pt")
    
    # Treinar o modelo em um chip Apple silicon (M1/M2/M3/M4)
    results = model.train(data="coco8.yaml", epochs=100, imgsz=640, device="mps")

    Para mais detalhes, consulte a seção Treinamento com Apple Silicon MPS.

  • O Ultralytics YOLO26 permite configurar várias opções de treinamento por meio de argumentos, como tamanho do lote, taxa de aprendizado, épocas e muito mais. Veja um breve resumo:

    ArgumentoPadrãoDescrição
    modelNoneCaminho para o arquivo do modelo usado no treinamento.
    dataNoneCaminho para o YAML do conjunto de dados (por exemplo, coco8.yaml), ou um diretório ou nome de conjunto de dados (por exemplo, imagenet10) para classificação.
    epochs100Número total de épocas de treinamento.
    batch16Tamanho do lote, configurável como inteiro ou no modo automático.
    imgsz640Tamanho de imagem desejado para o treinamento.
    deviceNoneDispositivo(s) computacional(is) para o treinamento, como cpu, 0, 0,1 ou mps.
    saveTrueAtiva o salvamento dos checkpoints do treinamento e dos pesos finais do modelo.

    Para um guia detalhado sobre as configurações de treinamento, consulte a seção Configurações de treinamento.

Comentários1.074

Faz uma pergunta, partilha os teus resultados ou ajuda alguém.

  1. drcosimoGitHub

    Hi there, I' m new to this field and I'm trying to train a YOLO model for detection and tracking of video streams for security.

    Until now I have managed to create my pipeline for training and I want to understand if it's a correct/possible approach:

    1. Load a pretrained model from yolo

    2. transfer learning with my custom dataset that possibly can focus on just some classes(person,car,truck,bus,bycicle)

    3. Validate model to see how it performs

    4. Operate a tuning with the custom best model and using my custom dataset

    5. Retrain the initial pretrained model with my custom dataset and the best hyperparameters found in the tuning process.

    6. Validate final model

    The questions are several:

    • The above approach is logically correct or it has flaws?
    • Is it correct to narrow the detected classes? Or it isn't crucial to the precision of the model?
    • When tuning(if its a correct approach) should i use my dataset or try the coco dataset to keep generalization?
    • When tuning should i specify the classes to detect?
    • When retraining should I use the first pretrained model or it is better to use my custom trained model?
    • In the final training am I using the correct parameters?

    Here the code of the pipeline:

    from ultralytics import YOLO import yaml

    load pretrained model from coco dataset

    model:YOLO = YOLO('yolov8n.yaml').load('yolov8n.pt')

    train_classes = []

    NOTE if you're using COCO format, the new dataset should also be in COCO format.

    operate transfer learning with my custom dataset, narrowing the classes to the ones I want to detect

    model.train(data='custom_data.yaml',classes=train_classes,epochs=200,imgsz=640,optimizer='AdamW',device=[0,1],augment=True,name='custom_model')

    load custom model

    custom_model = YOLO('path/to/best.pt')

    validate custom model

    custom_model.val()

    try tuning to find the best hyperparameters for my custom model

    custom_model.tune(data='custom_data.yaml', epochs=50, iterations=100,optimizer="AdamW", plots=True,save=True,val=True)

    load best hyperparameters

    cfg = yaml.load(open('path/to/best_hyperparameters.yaml'))

    retrain custom model from pretrained on coco with best hyperparameters

    model.train(data='custom_data.yaml',classes=train_classes,epochs=200,imgsz=640,device=[0,1],name='custom_model',exist_ok=True,optimizer='AdamW',**cfg)

    load and validate

    tuned_custom_model = YOLO('path/to/best.pt')

    tuned_custom_model.val()


    Thank you for your effort and time in this project!

    3
    1. Paula DerrengerUltralytics(editado)

      Hello,

      Your approach to training a YOLO model for detection and tracking is well-thought-out and mostly aligns with best practices. Here are some insights and answers to your questions:

      1. Approach Validity: Your steps are logically sound. Starting with a pretrained model and applying transfer learning to your specific classes is a recommended strategy. Validating and tuning based on the performance helps refine the model further.

      2. Narrowing Detected Classes: It's perfectly fine to focus on specific classes if those are the only ones relevant to your use case. This can help improve the model's performance by reducing the complexity of the problem it needs to solve.

      3. Dataset for Tuning: Use your custom dataset for tuning. This ensures that the hyperparameters are optimized for the specific characteristics of your data rather than the general characteristics of the COCO dataset.

      4. Specifying Classes During Tuning: When tuning, you should specify the classes if your dataset is a subset of the original classes used in the pretrained model. This helps in focusing the model’s learning and evaluation on relevant classes.

      5. Model for Retraining: Tuning only finds hyperparameters, so the usual practice is to train again from the original pretrained model with the best hyperparameters, as in your step 5. Continuing from the already fine-tuned model is also possible, but then it effectively trains for longer, which makes the result harder to compare with the tuning runs.

      6. Parameters for Final Training: The parameters should be chosen based on the results of your tuning. Ensure that they are the ones that gave the best validation performance during the tuning phase.

      Keep up the great work, and don't hesitate to reach out if you have more questions!

    2. drcosimoGitHub

      Thank you very much for you response. I adjusted my script to follow your insights. I have another question regarding transfer learning. The normal approach in transfer learning is to freeze the first n layers to preserve the more generic feature extraction properties of an already trained model and then it is retrained letting only the remaining layers update. I found the callback function to achieve this. My question is, applying the fine-tuning as specified by ultralytics documentation has the same effect? What I mean is: executing the train method again on a pretrained model changing the dataset causes the underlying library to execute the freeze automatically? If it isn't the case it is not clear to me why the fine-tuning is said to have the same effect as applying transfer learning.

      Another question is: it is useful to take a pretrained model from ultralytics and train it with the coco dataset? Because from what I know the pretrained model is already trained using coco dataset. Doing such a thing following the logic you provide for fine-tuning would be essentially the same as resuming a training / do the same train with more epochs?

      Thank you again for your time.

    3. Paula DerrengerUltralytics

      Hello,

      Thank you for your follow-up questions. Let's address each of them:

      1. Freezing Layers in Transfer Learning: The Ultralytics YOLO framework does not automatically freeze any layers when you initiate training, even if you're using a pretrained model. If you want to freeze the first N layers (common in transfer learning to preserve learned features), you must explicitly specify this in your training script. This is different from some other frameworks that might automate this aspect of transfer learning.

      2. Training on COCO Dataset with a Pretrained Model: If the pretrained model you are using was already trained on the COCO dataset, retraining it on the same dataset without significant changes or additional data might not yield substantial improvements. It could be beneficial for fine-tuning if you've made modifications to the model architecture or if you're using a significantly altered version of the dataset. However, generally, this approach would indeed be akin to simply extending the training duration.

      For fine-tuning and transfer learning, it's crucial to tailor the approach based on what changes you've made to the dataset or model and your specific goals (e.g., improving accuracy, adapting to new classes, etc.).

      I hope this clarifies your queries! If you have more questions or need further assistance, feel free to ask.

    1. Paula DerrengerUltralytics

      哈哈,确实,“train”翻译成“火车”听起来很有趣 😄。这里的“train”应该翻译为“训练”,指的是在机器学习中对模型进行训练,以提高其准确性和效率。感谢您指出这个问题,我们会尽快修正翻译错误。如果您有任何其他建议或问题,欢迎随时告诉我们!🚀

      2
  2. Syedshajib55GitHub

    Hi, does platform.ultralytics currently support using custom PyTorch modules directly via a YAML configuration without modifying tasks.py or the core source code? We are attempting to train a custom architecture (e.g., YOLO26) and want to know if there is an existing feature for dynamic module registration.

    1
    1. Muh-7GitHub

      Hi, As far as I know, not at the moment. Ultralytics doesn't seem to have a built-in dynamic registration system where you can define a custom PyTorch module outside the repo and then use it directly in the YAML.

      Usually, the custom module still needs to be imported/registered in tasks.py so that parse_model() can resolve it from the YAML.

      It would be really useful if Ultralytics added something like a register_module() API for this, though.

    2. Murat Raimbekov

      @Syedshajib55 @Muh-7 Platform can train any model that the ultralytics Python package can build, including custom architectures from a modified package or fork. The custom code runs on your own hardware; Platform receives real-time metrics, console and system logs, plots, and the final weights.

      There is no dynamic registration API. parse_model() resolves layer names from the ultralytics.nn.tasks namespace, so a name in your YAML must exist there. You don't need to edit tasks.py for that — expose the class from your own package before building the model:

      import ultralytics.nn.tasks as tasks
      from my_custom_package import MyBlock
      
      tasks.MyBlock = MyBlock  # now `[-1, 1, MyBlock, [...]]` resolves in the YAML

      Full local training with metric streaming to Platform:

      pip install "ultralytics>=8.4.120"
      export ULTRALYTICS_API_KEY="YOUR_API_KEY"
      import ultralytics.nn.tasks as tasks
      from my_custom_package import MyBlock
      from ultralytics import YOLO
      
      tasks.MyBlock = MyBlock
      
      model = YOLO("custom-model.yaml")  # YAML referencing MyBlock
      model.train(
          data="ul://username/datasets/my-dataset",
          epochs=100,
          project="username/my-project",
          name="custom-architecture",
      )

      project and name enable the Platform integration automatically; nothing else is required. Verified on 8.4.157 with a custom nn.Module inserted into a YOLO26n YAML: the model builds, trains, and appears on Platform as a completed run with weights and train args.

      One caveat: the saved .pt pickles the class by import path (my_custom_package.MyBlock), so any environment that loads it needs that package importable — otherwise loading fails with ModuleNotFoundError. That includes Platform-side features that load the uploaded weights with the stock package (Predict, Export, Deploy); local training and streaming are unaffected. Setup details: https://docs.ultralytics.com/platform/train/cloud-training/#remote-training

  3. RussellLee12345GitHub

    Hello all,

    I want my training images to rotate 360 degrees randomly. How do I set the hyper-parameter: degrees?

    Thanks a lot.

    1
    1. Glenn JocherUltralytics

      @RussellLee12345 to rotate your training images randomly up to 360 degrees, set the degrees parameter to 180 in your training configuration. This allows for rotations within the range of -180 to +180 degrees. For more details, see the augmentation settings in the Train Settings documentation.

  4. GKYofficeGitHub

    Please tell me how to set imgsz when I use the yolo11 model for training. Can it only be an integer (this means that the final input is a square)? After I modify this parameter, will the input interface of the network change the input of data? There are corresponding transformations, such as imgsz=1280, does it mean that my input data will be resized to 1280*1280 and input into the network for training?

    Thanks!

    1
    1. Glenn JocherUltralytics

      @GKYoffice when using the YOLO11 model, imgsz can be set as an integer, which resizes the input data to a square of that size (e.g., 1280x1280). This parameter adjusts the input dimensions for training. For more details, please visit the training documentation.

  5. IruhDegSetGitHub

    hi, I'm just wondering if yolov8 accepts class weights, in the data.yaml file:

    names: ['class 1', 'class 2', 'class 3']
    classes_weights: [c1_weight, c2_weight, c3_weight]

    if no how to incorpoorate wighted loss in yolov8 THX

    1
    1. Glenn JocherUltralytics

      @IruhDegSet yOLOv8 does not directly support class weights in the data.yaml file. To incorporate weighted loss, you can modify the loss function in the training script to apply different weights to each class. For more details, you might explore custom loss implementations in PyTorch.

    2. Glenn JocherUltralytics(editado)

      Yes, YOLO11 supports similar features, including training and hyperparameter customization. For specific details on YOLO11, please refer to the documentation or the relevant sections in the repository.

  6. User

    Dear author, how are the weights of these three losses set: box: 7.5, cls: 0.5, dfl: 1.5? Are they adjusted on the COCO validation, manually adjusted, or obtained through hyperparameter search? For the model I trained, the output confidence scores are very low. I directly increased the weight of cls by 10 times, but the effect did not improve. What other methods can I take?

    1
    1. Glenn JocherUltralytics

      @Stephen-Hao the weights for the box, cls, and dfl losses in YOLOv8 are typically set based on empirical results and fine-tuning on standard datasets like COCO. These values are chosen to balance the contributions of each loss component to the overall training process. If increasing the cls weight did not improve your model's performance, consider the following approaches:

      1. Hyperparameter Tuning: Experiment with other hyperparameters such as learning rate, batch size, and augmentation settings.
      2. Data Quality: Ensure your dataset is well-labeled and balanced. Poor quality data can significantly affect model performance.
      3. Training Duration: Increase the number of epochs to allow the model more time to learn.
      4. Validation: Regularly validate your model to monitor overfitting and adjust training strategies accordingly.

      For more detailed guidance, you can refer to the Ultralytics YOLO training documentation.

    2. Glenn JocherUltralytics

      @Stephen-Hao thank you for your question! The weights for box, cls, and dfl losses are typically set based on empirical results and fine-tuning on standard datasets like COCO. If increasing the cls weight didn't improve your model's performance, consider experimenting with other hyperparameters such as learning rate, batch size, and augmentation settings. Additionally, ensure your dataset is well-labeled and balanced. For more detailed guidance, you can refer to the Ultralytics YOLO training documentation.

    1. Glenn JocherUltralytics(editado)

      Hey there! 🙌 It's awesome that you're looking to further improve your model with new data. To re-train a pre-trained model on a new dataset, you can simply follow these steps:

      1. Make sure your new dataset is prepared in the same YOLO format as your initial training (a dataset YAML plus one .txt label file per image).

      2. Load your pre-trained model using the YOLO loading method, then specify your new dataset in the train method. Here's a quick code snippet for clarity:

        from ultralytics import YOLO
        
        # Load your pre-trained model
        model = YOLO('path/to/your/pretrained/model.pt') 
        
        # Start training on the new dataset
        results = model.train(data='path/to/your/new/dataset.yaml', epochs=50, imgsz=640)

      Just replace 'path/to/your/pretrained/model.pt' and 'path/to/your/new/dataset.yaml' with the actual paths to your model and new dataset config file, respectively. Adjust the epochs and imgsz (image size) to suit your needs. 🛠️

      That's it! Your model will now continue training on the new dataset. If you have any further questions or run into issues, feel free to ask. Happy training! 🚀

  7. songziang182GitHub

    谢谢你们开发了这么完善的 yolov8🙏, 我想问一下,这两种训练方式的区别 model = YOLO('yolov8n.pt') model = YOLO('yolov8n.yaml').load('yolov8n.pt') model.train(.........)

    1
    1. Paula DerrengerUltralytics

      Hello there! 😊

      The main difference between the two training methods you've mentioned:

      1. model = YOLO('yolov8n.pt'): This directly loads a pretrained YOLOv8n model. It's the simplest way to load a model that has already been trained, making it ready for further training, evaluation, or inference right away.

      2. model = YOLO('yolov8n.yaml').load('yolov8n.pt'): This approach builds a new model from the YAML configuration file and then transfers the weights from the pretrained .pt model. It's a two-step process, where the model is first constructed based on the architecture defined in the YAML file, and then the weights from a pretrained model are loaded. This method is useful when you want to customize the model architecture before loading the weights.

      Both methods ultimately get you to a similar starting point for continuing training or making predictions. The choice depends on whether you need to customize the model architecture as defined in the YAML file before applying the pretrained weights.

      Let me know if this helps or if you have more questions!

    2. songziang182GitHub

      Thank you for answering me. I find it very useful. I have another question, which is the configuration file yolov8n.yaml. I didn’t find where it is. Can I adjust the scale of the model, for example, n, s, m, l, etc., is this the case?

    3. Paula DerrengerUltralytics(editado)

      Hey! 😊 Thank you for your kind words, and I'm glad the information was helpful to you!

      Regarding the yolov8n.yaml configuration file, it defines the architecture for YOLOv8 models. All scales share one model file (yolov8.yaml) that contains a scales section mapping each letter to [depth, width, max_channels]; the letter in the name you load (yolov8n.yaml, yolov8s.yaml, ...) selects the scale:

      scales:
        n: [0.33, 0.25, 1024]
        s: [0.33, 0.50, 1024]

      To create or modify a model, copy the YAML from the Ultralytics GitHub repository, edit the layers or scales, then load it together with the pretrained weights as you mentioned:

      model = YOLO('path/to/custom_yolov8.yaml').load('yolov8n.pt')
      model.train(.........)

      Model changes can require a solid understanding of the network architecture to be effective.

      I hope this clarifies your question! Feel free to reach out if you have further queries or need more examples. 😊

  8. vonzoGitHub

    So, imgsz works different when training than when predicting?

    For train: if it's an int the ratio will be kept and the train function will take care of that (can't be a tuple). For predict: if it's an int the image will be resized as a square of size imgsz x imgsz, if it's a tuple the image will be resized using HxW and the user has to take care of the ratio and stride.

    Is this right? I would add a comment in the doc to avoid confusions

    1
    1. Paula DerrengerUltralytics(editado)

      You've got it mostly right! 👍 For training (train), imgsz is an int, the aspect ratio is maintained and resizing is handled internally. It can't be a tuple. For prediction (predict), an int imgsz resizes the longest side to imgsz while keeping the aspect ratio, with padding only up to a multiple of the model stride (so the image is not forced into a square), and a [h, w] list sets the size explicitly.

      Great suggestion on the documentation comment – clarity is key! If you have any more questions or need further examples, feel free to ask. 😊