Guia da Ultralytics sobre ajuste de hiperparâmetros para YOLO#

O ajuste de hiperparâmetros no Ultralytics YOLO é uma busca automatizada e iterativa que otimiza configurações — como taxa de aprendizado, pesos das perdas e intensidade das aumentações — para maximizar métricas de desempenho de um modelo de aprendizado de máquina, como acurácia, precisão e revocação. Em vez de testar esses valores manualmente, o Ultralytics YOLO explora o espaço de hiperparâmetros com um algoritmo genético que muta e avalia configurações candidatas em várias execuções curtas de treinamento.

O que são hiperparâmetros?#

Hiperparâmetros são configurações estruturais de alto nível do algoritmo. Eles são definidos antes da fase de treinamento e permanecem constantes durante ela. Veja alguns hiperparâmetros comumente ajustados no Ultralytics YOLO:

• Taxa de aprendizado lr0: determina o tamanho do passo em cada iteração ao avançar em direção a um mínimo na função de perda.
• Tamanho do lote batch: número de imagens processadas simultaneamente em uma passagem direta.
• Número de épocas epochs: uma época é uma passagem direta e retropropagação completas por todos os exemplos de treinamento.
• Detalhes da arquitetura: como o número de canais, o número de camadas, os tipos de funções de ativação etc. Esses elementos ficam na configuração YAML do modelo, e não nos argumentos de treinamento.

Desses quatro itens, apenas a taxa de aprendizado está no espaço de busca padrão: batch, epochs e a arquitetura permanecem fixos. O ajustador também altera o cronograma, os ganhos das perdas e as aumentações listadas abaixo.

Para ver uma lista completa dos hiperparâmetros de aumento de dados usados no YOLO26, consulte a página de configurações.

Evolução genética e mutação#

O Ultralytics YOLO usa algoritmos genéticos para otimizar hiperparâmetros. Os algoritmos genéticos se inspiram nos mecanismos da seleção natural e da genética.

• Seleção: cada iteração seleciona uma entre até nove configurações com maior aptidão, ponderadas pela aptidão. Após 30 resultados, os 20% melhores resultados (até 30) também são usados para estimar a covariância dos parâmetros, cuja influência aumenta à medida que se acumulam evidências das configurações de elite.
• Mutação: cada iteração altera aproximadamente metade dos parâmetros usando passos gaussianos normalizados pelos respectivos intervalos de busca. Quando a covariância está ativa, uma parcela ponderada pela confiança, de no máximo 40%, usa passos correlacionados; a reflexão mantém esses passos dentro dos limites sem acumular valores truncados. À medida que se acumulam tentativas sem melhora, os tamanhos dos passos diminuem linearmente em até 20% ao longo de 25 tentativas e são redefinidos quando um novo melhor resultado é encontrado. A iteração 1 não tem configuração-pai e usa os hiperparâmetros de treinamento padrão como linha de base.

Preparação para o ajuste de hiperparâmetros#

Antes de começar o processo de ajuste, é importante:

1. Identificar as métricas: o ajustador integrado (use_ray=False) classifica as tentativas pela pontuação fitness da tarefa, enquanto use_ray=True usa a métrica da tarefa. Decida quais métricas secundárias você vai analisar, como AP50 ou pontuação F1.
2. Definir o orçamento de ajuste: determine quantos recursos computacionais você pretende alocar. O ajuste de hiperparâmetros pode exigir muitos recursos computacionais.

Como funciona o ciclo de ajuste#

Em cada iteração, o ajustador integrado repete o seguinte ciclo:

1. Inicializar os hiperparâmetros — começar com uma linha de base razoável, usando os hiperparâmetros padrão definidos pelo Ultralytics YOLO ou valores baseados no seu conhecimento do domínio ou em experimentos anteriores.
2. Alterar os hiperparâmetros — a classe Tuner gera automaticamente um novo conjunto de hiperparâmetros a partir do conjunto existente com o método _mutate.
3. Treinar o modelo — treinar usando os hiperparâmetros alterados e, em seguida, avaliar o desempenho do treinamento com as métricas escolhidas.
4. Avaliar o modelo — o processo de avaliação gera a pontuação de aptidão da iteração, que é comparada às iterações anteriores para determinar se os hiperparâmetros atuais representam uma melhoria.
5. Registrar os resultados — registrar as métricas de desempenho e os hiperparâmetros correspondentes para consulta futura. O Ultralytics YOLO salva automaticamente esses resultados no formato NDJSON.
6. Repetir — continuar até atingir o número definido de iterações, cada uma aproveitando o conhecimento obtido nas execuções anteriores. O ajustador integrado executa todos os iterations; o Ray Tune informa as métricas após cada época de ajuste, permitindo que o ASHA interrompa tentativas com baixo desempenho após o período de tolerância.

Iterações e tamanho da população#

Com o ajustador integrado (use_ray=False), iterations controla o número total de tentativas sequenciais e tem o valor padrão 300. Cada tentativa treina um modelo com uma configuração de hiperparâmetros — por exemplo, iterations=40 com epochs=50 agenda 40 execuções de treinamento independentes de 50 épocas, e não uma execução de 50 épocas com uma população separada de 40 candidatos.

O algoritmo genético integrado não tem um parâmetro explícito de tamanho da população. Quando já existem tentativas anteriores, ele seleciona entre até nove das configurações com maior aptidão e altera um candidato por iteração.

Para executar tentativas em paralelo ou usar estratégias de busca mais avançadas, defina use_ray=True para usar o Ray Tune, que também tem 300 tentativas como padrão e recebe iterations como num_samples. Consulte o guia de integração do Ray Tune para obter detalhes.

Espaço de busca padrão#

A tabela a seguir lista os parâmetros padrão do espaço de busca para o ajuste de hiperparâmetros no YOLO26. Cada parâmetro tem um intervalo de valores específico definido por uma tupla (min, max).

Exemplo de espaço de busca personalizado#

Veja como definir um espaço de busca e usar o método model.tune() para utilizar a classe Tuner no ajuste de hiperparâmetros do YOLO26n no COCO8 por 30 épocas com um otimizador AdamW, ignorando a geração de gráficos, o salvamento de checkpoints e a validação — exceto na época final — para acelerar o ajuste.

from ultralytics import YOLO

# Inicializa o modelo YOLO
model = YOLO("yolo26n.pt")

# Define o espaço de busca
search_space = {
    "lr0": (1e-5, 1e-2),
    "degrees": (0.0, 45.0),
}

# Ajusta os hiperparâmetros no COCO8 por 30 épocas
model.tune(
    data="coco8.yaml",
    epochs=30,
    iterations=300,
    optimizer="AdamW",
    space=search_space,
    plots=False,
    save=False,
    val=False,
)

Retomar uma sessão interrompida de ajuste de hiperparâmetros#

Você pode retomar uma sessão interrompida de ajuste de hiperparâmetros passando resume=True. Opcionalmente, você pode passar o diretório name usado em runs/{task} para retomar a sessão. Sem um name, o processo retoma o diretório chamado literalmente tune, que é o nome padrão, e não a sessão executada mais recentemente; por isso, passe name para qualquer execução iniciada com um nome personalizado. Você também precisa fornecer todos os argumentos de treinamento anteriores, incluindo data, epochs, iterations e space.

from ultralytics import YOLO

# Define um modelo YOLO
model = YOLO("yolo26n.pt")

# Define o espaço de busca
search_space = {
    "lr0": (1e-5, 1e-2),
    "degrees": (0.0, 45.0),
}

# Retoma a execução anterior
results = model.tune(data="coco8.yaml", epochs=50, iterations=300, space=search_space, resume=True)

# Retoma a execução de ajuste com o nome 'tune_exp'
results = model.tune(data="coco8.yaml", epochs=50, iterations=300, space=search_space, name="tune_exp", resume=True)

Resultados#

Depois de concluir o processo de ajuste de hiperparâmetros, você terá vários arquivos e diretórios com os resultados do ajuste. Veja a seguir a descrição de cada um:

Estrutura de arquivos#

Veja como será a estrutura de diretórios dos resultados. Diretórios de varredura, como multitrain/ e multitrain-2/, contêm iterações individuais de ajuste: um modelo treinado por conjunto de dados com um conjunto de hiperparâmetros, em um subdiretório nomeado de acordo com cada conjunto de dados. Para economizar espaço de armazenamento, o ajustador exclui os diretórios de execução por conjunto de dados das iterações que não são as melhores atuais. O diretório tune/ contém os resultados do ajuste de todos os treinamentos individuais de modelos:

runs/
└── detect/
    ├── multitrain/
    │   └── coco8/
    ├── multitrain-2/
    ├── ...
    └── tune/
        ├── best_hyperparameters.yaml
        ├── tune_fitness.png
        ├── tune_results.ndjson
        ├── tune_scatter_plots.png
        └── weights/
            ├── last.pt
            └── best.pt

Descrições dos arquivos#

best_hyperparameters.yaml#

Este arquivo YAML contém os hiperparâmetros de melhor desempenho encontrados durante o processo de ajuste. Você pode usar este arquivo para inicializar treinamentos futuros com essas configurações otimizadas.

• Formato: YAML

• Uso: resultados dos hiperparâmetros

• Exemplo:

  # 558/900 iterations complete ✅ (45536.81s)
  # Results saved to /usr/src/ultralytics/runs/detect/tune
  # Best fitness=0.64297 observed at iteration 498
  # Best fitness metrics are {'metrics/precision(B)': 0.87247, 'metrics/recall(B)': 0.71387, 'metrics/mAP50(B)': 0.79106, 'metrics/mAP50-95(B)': 0.62651, 'val/box_loss': 2.79884, 'val/cls_loss': 2.72386, 'val/l1_loss': 0.68503, 'fitness': 0.64297}
  # Best fitness model is /usr/src/ultralytics/runs/detect/tune/weights
  # Best fitness hyperparameters are printed below.
  
  lr0: 0.00269
  lrf: 0.00288
  momentum: 0.73375
  weight_decay: 0.00015
  warmup_epochs: 1.22935
  warmup_momentum: 0.1525
  box: 18.27875
  cls: 1.32899
  dfl: 0.56016
  hsv_h: 0.01148
  hsv_s: 0.53554
  hsv_v: 0.13636
  degrees: 0.0
  translate: 0.12431
  scale: 0.07643
  shear: 0.0
  perspective: 0.0
  flipud: 0.0
  fliplr: 0.08631
  mosaic: 0.42551
  mixup: 0.0
  copy_paste: 0.0

tune_fitness.png#

Este gráfico mostra a aptidão em função do número de iterações. Ele ajuda você a visualizar o desempenho do algoritmo genético ao longo do tempo.

• Formato: PNG
• Uso: visualização do desempenho

O gráfico contém:

• Um marcador por iteração e por conjunto de dados, ou seja, uma execução com um único conjunto de dados mostra um ponto por iteração, e uma execução com vários conjuntos de dados mostra um ponto por conjunto de dados em cada iteração.
• Uma linha pontilhada de "média suavizada" calculada por suavização gaussiana (sigma=3) dos valores de aptidão de nível superior por iteração.

tune_results.ndjson#

Um arquivo NDJSON com resultados detalhados de cada iteração de ajuste. Cada linha é um objeto JSON com a aptidão agregada, os hiperparâmetros ajustados e as métricas por conjunto de dados. O ajuste com um único conjunto de dados e com vários conjuntos de dados usa o mesmo formato de arquivo.

• Formato: NDJSON
• Uso: acompanhamento dos resultados por iteração.
• Exemplo:

A seguir, um exemplo formatado para facilitar a leitura; no arquivo .ndjson real, cada objeto é armazenado em uma única linha.

{
    "iteration": 1,
    "fitness": 0.48628,
    "hyperparameters": {
        "lr0": 0.01,
        "lrf": 0.01,
        "momentum": 0.937,
        "weight_decay": 0.0005
    },
    "datasets": {
        "coco8": {
            "metrics/precision(B)": 0.65666,
            "metrics/recall(B)": 0.85,
            "metrics/mAP50(B)": 0.85086,
            "metrics/mAP50-95(B)": 0.64104,
            "val/box_loss": 1.57958,
            "val/cls_loss": 1.04986,
            "val/l1_loss": 1.32641,
            "fitness": 0.64104
        },
        "coco8-grayscale": {
            "metrics/precision(B)": 0.6582,
            "metrics/recall(B)": 0.51667,
            "metrics/mAP50(B)": 0.59106,
            "metrics/mAP50-95(B)": 0.33152,
            "val/box_loss": 1.95424,
            "val/cls_loss": 1.64059,
            "val/l1_loss": 1.70226,
            "fitness": 0.33152
        }
    },
    "save_dirs": {
        "coco8": "runs/detect/multitrain/coco8",
        "coco8-grayscale": "runs/detect/multitrain/coco8-grayscale"
    }
}

O valor de nível superior fitness é a média aritmética dos valores fitness por conjunto de dados. No ajuste com um único conjunto de dados, o dicionário datasets tem uma entrada cujo fitness é igual ao fitness de nível superior. É registrado um objeto JSON por iteração concluída. Os caminhos reais save_dirs são absolutos; eles foram abreviados acima para facilitar a leitura.

tune_scatter_plots.png#

Este arquivo contém gráficos de dispersão gerados a partir de tune_results.ndjson, que ajudam você a visualizar as relações entre diferentes hiperparâmetros e métricas de desempenho. A mutação usa o intervalo configurado para cada hiperparâmetro, portanto, os valores podem evoluir a partir de padrões iguais a zero, como degrees e shear.

• Formato: PNG
• Uso: análise exploratória de dados

weights/#

Este diretório contém os modelos PyTorch salvos da iteração com melhor aptidão na execução de ajuste. Os dois arquivos vêm dessa mesma iteração:

• last.pt: last.pt contém os pesos da última época de treinamento.
• best.pt: os pesos best.pt correspondem à iteração que alcançou a melhor pontuação de aptidão.

Com esses resultados, você pode tomar decisões mais informadas em treinamentos e análises futuros de modelos.

Conclusão#

O ajuste de hiperparâmetros no Ultralytics YOLO é simples de iniciar e poderoso nos bastidores, usando seleção ponderada pela aptidão e mutação normalizada por intervalo em um algoritmo genético. Seguir o ciclo descrito neste guia permite ajustar sistematicamente o teu modelo para obter melhor desempenho e, em seguida, reutilizar o best_hyperparameters.yaml resultante para inicializar futuras execuções de treino. Para expandir o ajuste a testes paralelos e algoritmos de pesquisa mais avançados, continua com o guia de integração do Ray Tune ou executa tarefas geridas com hiperparâmetros configuráveis e monitorização de métricas em tempo real na Ultralytics Platform através do treino na nuvem.

Para definições que nenhum argumento expõe, como taxas de aprendizagem por camada ou uma métrica de aptidão personalizada, cria uma subclasse do treinador. Para conhecer melhor a implementação, explora o código-fonte da classe Tuner. Se tiveres perguntas ou pedidos de funcionalidades, contacta-nos no GitHub ou no Discord.

Perguntas frequentes#