Guia de Hyperparameter Tuning do Ultralytics YOLO#

A otimização de hiperparâmetros no Ultralytics YOLO é uma busca automatizada e iterativa que otimiza configurações — como taxa de aprendizado, pesos de perda e intensidade de aumento — para maximizar as métricas de desempenho de um modelo de machine learning, 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 ao longo de muitas execuções curtas de treinamento.

O que são Hiperparâmetros?#

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

• Learning Rate lr0: Determina o tamanho do passo em cada iteração ao se mover em direção a um mínimo na loss function.
• Batch Size batch: Número de imagens processadas simultaneamente em uma passagem para a frente (forward pass).
• Number of Epochs epochs: Uma época é uma passagem completa para a frente e para trás de todos os exemplos de treinamento.
• Especificidades da arquitetura: Como contagens de canais, número de camadas, tipos de funções de ativação, etc. Elas ficam na configuração YAML do modelo em vez de nos argumentos de treinamento.

Destes quatro, apenas a taxa de aprendizado está no espaço de busca padrão: batch, epochs e a arquitetura permanecem fixas. O otimizador também muta o agendamento, os ganhos de perda e as multiplicações de aumento listadas abaixo.

Para obter uma lista completa de hiperparâmetros de aumento usados no YOLO26, consulte a configurations page.

Evolução Genética e Mutação#

O Ultralytics YOLO usa genetic algorithms para otimizar hiperparâmetros. Os algoritmos genéticos são inspirados no mecanismo de seleção natural e genética.

• Cruzamento (Crossover): Cada iteração combina genes de até nove das configurações de maior aptidão vistas até agora, usando o cruzamento BLX-α com seleção de pais ponderada pela aptidão.
• Mutação: O candidato recombinado é então perturbado por um fator multiplicativo log-normal aplicado a cada hiperparâmetro (com probabilidade de 0,5 por parâmetro). A força da mutação sigma decai linearmente de 0,2 para 0,1 ao longo das primeiras 300 iterações, de modo que o algoritmo explore amplamente no início e refine conforme converge. A iteração 1 não tem pais para cruzamento e usa os hiperparâmetros de treinamento padrão como base.

Preparação para o Ajuste de Hiperparâmetros#

Antes de iniciar o processo de ajuste, é importante:

1. Identifique as métricas: O otimizador 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 inspecionar, como AP50 ou F1-score.
2. Definir o Orçamento de Ajuste: Defina quantos recursos computacionais você está disposto a alocar. O ajuste de hiperparâmetros pode ser computacionalmente intensivo.

Como funciona o loop de ajuste#

Para cada iteração, o ajustador (tuner) integrado repete o seguinte loop:

1. Inicializar hiperparâmetros — comece a partir de uma base razoável, seja os hiperparâmetros padrão definidos pelo Ultralytics YOLO ou valores baseados no seu conhecimento de domínio ou experimentos anteriores.
2. Mutate hyperparameters — a Tuner class produz automaticamente um novo conjunto de hiperparâmetros a partir do conjunto existente com seu método _mutate.
3. Treinar o modelo — treine usando os hiperparâmetros mutados e, em seguida, avalie o desempenho do treino com as métricas escolhidas.
4. Avalie o modelo — o processo de avaliação produz a pontuação de aptidão da iteração, que é comparada com as iterações anteriores para determinar se os hiperparâmetros atuais representam uma melhoria.
5. Registrar resultados — grave tanto as métricas de desempenho quanto os hiperparâmetros correspondentes para referência futura. O Ultralytics YOLO salva automaticamente esses resultados no formato NDJSON.
6. Repita — continue até que o número definido de iterações seja atingido, com cada iteração construindo sobre o conhecimento adquirido em execuções anteriores. O otimizador integrado executa todos os iterations; o Ray Tune relata as métricas após cada época de ajuste, permitindo que o ASHA interrompa tentativas fracas após seu período de carência.

Iterações e Tamanho da População#

Com o sintonizador embutido (use_ray=False), iterations controla o número total de tentativas sequenciais. 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 única execução de 50 épocas com uma população separada de 40 candidatos.

O algoritmo genético integrado não possui um parâmetro de tamanho de população explícito. Uma vez que existam tentativas anteriores, ele seleciona até nove das configurações de maior aptidão como pais, aplica o cruzamento BLX-α e mutação, e produz um candidato por iteração.

Para tentativas paralelas ou estratégias de busca mais avançadas, configure use_ray=True para usar o Ray Tune, que recebe iterations como num_samples. Consulte o Ray Tune integration guide para obter detalhes.

Espaço de pesquisa padrão#

A tabela a seguir lista os parâmetros padrão do espaço de busca para a otimização 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 na otimização de hiperparâmetros do YOLO26n no COCO8 por 30 épocas com um otimizador AdamW e pulando a geração de gráficos, salvamento de checkpoints e validação, exceto na época final, para uma sintonização mais rápida.

from ultralytics import YOLO

# Initialize the YOLO model
model = YOLO("yolo26n.pt")

# Define search space
search_space = {
    "lr0": (1e-5, 1e-2),
    "degrees": (0.0, 45.0),
}

# Tune hyperparameters on COCO8 for 30 epochs
model.tune(
    data="coco8.yaml",
    epochs=30,
    iterations=300,
    optimizer="AdamW",
    space=search_space,
    plots=False,
    save=False,
    val=False,
)

Retomando uma Sessão de Ajuste de Hiperparâmetros Interrompida#

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

from ultralytics import YOLO

# Define a YOLO model
model = YOLO("yolo26n.pt")

# Define search space
search_space = {
    "lr0": (1e-5, 1e-2),
    "degrees": (0.0, 45.0),
}

# Resume previous run
results = model.tune(data="coco8.yaml", epochs=50, iterations=300, space=search_space, resume=True)

# Resume tuning run with name 'tune_exp'
results = model.tune(data="coco8.yaml", epochs=50, iterations=300, space=search_space, name="tune_exp", resume=True)

Resultados#

Após concluir com sucesso o processo de ajuste de hiperparâmetros, você obterá vários arquivos e diretórios que encapsulam os resultados do ajuste. O seguinte descreve cada um:

Estrutura de Arquivos#

Aqui está a aparência da estrutura de diretórios dos resultados. Diretórios de treinamento como train/ e train-2/ contêm iterações de ajuste individuais, ou seja, um modelo treinado com um conjunto de hiperparâmetros. O diretório tune/ contém os resultados de ajuste de todos os treinamentos individuais de modelos:

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

Descrições de 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 futuros treinamentos com essas configurações otimizadas.

• Formato: YAML

• Uso: Resultados de 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 é um gráfico que exibe a aptidão em relação ao número de iterações. Ele ajuda você a visualizar como o algoritmo genético funcionou ao longo do tempo.

• Formato: PNG
• Uso: Visualização de desempenho

O gráfico contém:

• Um marcador por iteração por conjunto de dados, então uma execução de conjunto de dados único mostra um ponto por iteração, e uma execução de múltiplos conjuntos de dados mostra um ponto por conjunto de dados por iteração.
• Uma linha tracejada de "média suavizada" calculada como uma suavização gaussiana (sigma=3) sobre os valores de aptidão de nível superior por iteração.

tune_results.ndjson#

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

• Formato: NDJSON
• Uso: Rastreamento de resultados por iteração.
• Exemplo:

Um exemplo formatado (pretty-printed) é apresentado a seguir 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/coco8",
        "coco8-grayscale": "runs/detect/coco8-grayscale"
    }
}

O fitness de nível superior é a média aritmética dos valores de fitness por conjunto de dados. Para a sintonização em um único conjunto de dados, o dicionário datasets possui uma entrada cuja chave fitness é igual ao fitness de nível superior. Um objeto JSON é gravado por iteração concluída. Os caminhos save_dirs reais 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, ajudando você a visualizar as relações entre diferentes hiperparâmetros e métricas de desempenho. Hiperparâmetros cujo valor padrão é 0 (por exemplo, degrees e shear abaixo) podem evoluir apenas lentamente a partir de sua semente inicial, porque o fator de mutação multiplicativo tem muito pouco espaço para expandir a partir de um valor próximo de zero.

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

weights/#

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

• last.pt: O arquivo last.pt contém os pesos da última época de treinamento.
• best.pt: Os pesos best.pt para a iteração que obteve a melhor pontuação de aptidão.

Usando esses resultados, você pode tomar decisões mais informadas para futuros treinos e análises de modelos.

Conclusão#

A otimização de hiperparâmetros no Ultralytics YOLO é simples de iniciar e poderosa por trás dos panos, combinando o cruzamento BLX-α com mutação log-normal em um algoritmo genético. Seguir o ciclo descrito neste guia permite sintonizar sistematicamente o seu modelo para obter um desempenho melhor, e então reutilizar o best_hyperparameters.yaml resultante para inicializar futuras execuções de treinamento. Para dimensionar a sintonização em tentativas paralelas e algoritmos de busca mais avançados, continue com o Ray Tune integration guide, ou execute trabalhos gerenciados com hiperparâmetros configuráveis e rastreamento de métricas em tempo real na Ultralytics Platform via cloud training.

Para configurações que nenhum argumento expõe, como taxas de aprendizado por camada ou uma métrica de aptidão personalizada, subclasses do treinador devem ser usadas em vez disso. Para insights mais profundos, explore o código-fonte da classe Tuner. Se você tiver dúvidas ou solicitações de recursos, entre em contato no GitHub ou Discord.

FAQ#