Configuração
As configurações e os hiperparâmetros do YOLO desempenham um papel fundamental no desempenho, na velocidade e na precisão do modelo. Essas configurações podem afetar o comportamento do modelo em várias etapas, incluindo treinamento, validação e previsão.
Assista: Domine o Ultralytics YOLO: configuração
Os comandos do Ultralytics usam a seguinte sintaxe:
yolo TASK MODE ARGSOnde:
TASK(opcional) é um dos seguintes: (detectar, segmentar, semântico, profundidade, classificar, pose, obb)MODE(obrigatório) é um dos seguintes: (treinar, val, prever, exportar, rastrear, benchmark)ARGS(opcional) são paresarg=value, comoimgsz=640, que substituem os valores padrão.
Os valores padrão de ARG estão definidos nesta página e vêm do arquivo cfg/default.yaml.
Tarefas#
Os modelos Ultralytics YOLO podem realizar diversas tarefas de visão computacional, incluindo:
- Detecção: A detecção de objetos identifica e localiza objetos em uma imagem ou vídeo.
- Segmentação: A segmentação de instâncias divide uma imagem ou vídeo em regiões correspondentes a diferentes objetos ou classes.
- Segmentação semântica (
semantic): A segmentação semântica atribui um rótulo de classe a cada pixel de uma imagem para permitir a compreensão densa da cena. - Profundidade (
depth): A estimativa monocular de profundidade prevê um mapa de profundidade por pixel, em metros, a partir de uma única imagem RGB. - Classificação: A classificação de imagens prevê o rótulo de classe de uma imagem de entrada.
- Pose: A estimativa de pose identifica objetos e estima seus pontos-chave em uma imagem ou vídeo.
- OBB: caixas delimitadoras orientadas usa caixas delimitadoras rotacionadas, adequadas para imagens aéreas ou de satélite.
| Argumento | Padrão | Descrição |
|---|---|---|
task | 'detect' | Especifica a tarefa do YOLO: detect para deteção de objetos, segment para segmentação de instâncias, semantic para segmentação semântica, depth para estimativa monocular de profundidade, classify para classificação, pose para estimativa de pose e obb para caixas delimitadoras orientadas. Cada tarefa é adaptada a resultados e problemas específicos da análise de imagens e vídeos. |
Modos#
Os modelos Ultralytics YOLO funcionam em diferentes modos, cada um concebido para uma etapa específica do ciclo de vida do modelo:
- Train: Treina um modelo YOLO com um conjunto de dados personalizado.
- Val: Valida um modelo YOLO treinado.
- Predict: Usa um modelo YOLO treinado para fazer previsões em novas imagens ou vídeos.
- Export: Exporta um modelo YOLO para implementação.
- Track: rastreie objetos em tempo real usando um modelo YOLO.
- Benchmark: Avalia a velocidade e a precisão das exportações YOLO (ONNX, TensorRT, etc.).
| Argumento | Padrão | Descrição |
|---|---|---|
mode | 'train' | Especifica o modo de funcionamento do modelo YOLO: train para treinar o modelo, val para validação, predict para inferência, export para converter para formatos de implementação, track para rastreamento de objetos e benchmark para avaliação de desempenho. Cada modo abrange diferentes etapas, do desenvolvimento à implementação. |
Configurações de treino#
As configurações de treino dos modelos YOLO incluem hiperparâmetros e configurações que afetam o desempenho, a velocidade e a precisão do modelo. As principais configurações incluem tamanho do lote, taxa de aprendizagem, momentum e decaimento de pesos. A escolha do otimizador, da função de perda e da composição do conjunto de dados também afeta o treino. O ajuste e a experimentação são fundamentais para alcançar um desempenho ideal.
| Argumento | Tipo | Padrão | Descrição |
|---|---|---|---|
model | str | None | Especifica 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. |
data | str | None | Caminho 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). |
epochs | int | 100 | Nú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. |
time | float | None | Duraçã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. |
patience | int | 100 | Nú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. |
batch | int ou float | 16 | Tamanho 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). |
imgsz | int | 640 | Tamanho 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. |
save | bool | True | Permite 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_period | int | -1 | Frequê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. |
cache | bool ou str | False | Permite 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. |
tile | bool ou int | False | Expande 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. |
device | int ou str ou list | None | Especifica 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]). |
workers | int | 8 | Nú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. |
project | str | None | Nome 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. |
name | str | None | Nome 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_ok | bool | False | Se True, permite substituir um diretório de projeto/nome existente. Útil para experiências iterativas sem ter de limpar manualmente os resultados anteriores. |
save_dir | str | None | Especifica 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. |
pretrained | bool ou str | True | Determina 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_remap | bool | True | Ao 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. |
optimizer | str | '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. |
seed | int | 0 | Define a semente aleatória do treino, garantindo a reprodutibilidade dos resultados entre execuções com as mesmas configurações. |
deterministic | bool | True | Forç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. |
verbose | bool | True | Ativa 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_cls | bool | False | Trata 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. |
classes | list[int] | None | Especifica uma lista de IDs de classes a usar no treino. Útil para filtrar e focar apenas em determinadas classes durante o treino. |
rect | bool | False | Ativa 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_scale | float | 0.0 | Varia 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_lr | bool | False | Utiliza 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_mosaic | int | 10 | Desativa a ampliação de dados mosaico nas últimas N épocas para estabilizar o treino antes de este terminar. Definir como 0 desativa esta funcionalidade. |
resume | bool | False | Retoma 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. |
amp | bool ou str | True | Define a precisão do treino: True ou "fp16" usa FP16, "bf16" usa BF16 em dispositivos CUDA compatíveis e False ou "fp32" usa FP32. |
quantize | int ou str | None | Define 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. |
fraction | float, int ou list | 1.0 | Subconjunto 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. |
profile | bool | False | Ativa 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. |
freeze | int ou list | None | Congela 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. |
lr0 | float | 0.01 | Taxa 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. |
lrf | float | 0.01 | Taxa 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. |
momentum | float | 0.937 | Momentum 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_decay | float | 0.0005 | Termo de regularização L2, que penaliza pesos elevados para evitar o sobreajuste. |
warmup_epochs | float | 3.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_momentum | float | 0.8 | Momentum 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_lr | float | 0.1 | Taxa 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_model | str | None | Caminho 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. |
dis | float | 6.0 | Peso 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. |
box | float | 7.5 | Peso 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. |
cls | float | 0.5 | Peso 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_pw | float | 0.0 | Expoente 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. |
dfl | float | 1.5 | Peso 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). |
pose | float | 12.0 | Peso 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. |
kobj | float | 1.0 | Peso 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. |
rle | float | 1.0 | Peso 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. |
angle | float | 1.0 | Peso da perda angular nos modelos obb, que afeta a precisão das previsões dos ângulos das caixas delimitadoras orientadas. |
dlog | float | 1.0 | Peso da perda logarítmica invariante à escala (SILog) nos modelos de estimativa de profundidade, o principal termo que determina a precisão da profundidade. |
dgrad | float | 0.5 | Peso 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. |
dlam | float | 1.0 | Fator 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. |
nbs | int | 64 | Tamanho 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_mask | bool | True | Determina 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_ratio | int | 4 | Fator 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. |
dropout | float | 0.0 | Taxa de dropout para regularização em tarefas de classificação, que evita o sobreajuste ao omitir unidades aleatoriamente durante o treino. |
val | bool | True | Ativa a validação durante o treino, permitindo avaliar periodicamente o desempenho do modelo num conjunto de dados separado. |
split | str | '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. |
nms | bool, opcional | None | Seleciona 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. |
plots | bool | True | Gera 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. |
compile | bool ou str | False | Ativa 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_last | bool | None | Usa 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 posterior, exceto no Windows, onde foi medido um desempenho mais lento. False desativa-o e True solicita-o explicitamente. O treino em CPU ou MPS mantém sempre o formato NCHW (True é ignorado com um aviso). |
max_det | int | 300 | Nú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. |
O argumento batch oferece três opções de configuração:
- Tamanho fixo do lote: Especifica o número de imagens por lote com um número inteiro (por exemplo,
batch=16). - Modo automático (60% da memória GPU): use
batch=-1para ajustar automaticamente o uso para aproximadamente 60% da memória CUDA disponível para o treinamento. - Modo automático com fração de utilização: defina uma fração (por exemplo,
batch=0.70) para ajustar com base em uma fração especificada da memória GPU disponível.
Se nenhum tamanho de lote candidato gerar um perfil utilizável, o AutoBatch gera um RuntimeError claro em vez de recorrer silenciosamente a um valor predefinido sem relação.
Configurações de previsão#
As configurações de previsão dos modelos YOLO incluem hiperparâmetros e configurações que influenciam o desempenho, a velocidade e a precisão durante a inferência. Entre as principais configurações estão o limiar de confiança, o limiar de supressão não máxima (NMS) e a filtragem de classes. O tamanho e o formato dos dados de entrada, bem como recursos adicionais, como máscaras, também afetam as previsões. Ajustar essas configurações é essencial para obter o melhor desempenho.
Argumentos de inferência:
| Argumento | Tipo | Padrão | Descrição |
|---|---|---|---|
source | str ou int ou None | None | Especifica a origem dos dados para a inferência. Pode ser o caminho de uma imagem, um ficheiro de vídeo, um diretório, um URL ou o ID de um dispositivo para transmissões em direto. Se não for especificada, é registado um aviso e o modelo recorre aos recursos de demonstração integrados (ultralytics/assets ou um URL de demonstração para OBB). Suporta uma grande variedade de formatos e origens, permitindo uma aplicação flexível em diferentes tipos de entrada. |
conf | float | 0.25 | Define o limiar mínimo de confiança para as deteções. Os objetos detetados com confiança abaixo deste limiar são descartados. Ajustar este valor pode ajudar a reduzir os falsos positivos. |
iou | float | 0.5 | Limiar de interseção sobre união (IoU) para a supressão não máxima (NMS). Valores mais baixos resultam em menos deteções, eliminando caixas sobrepostas, o que é útil para reduzir duplicados. |
imgsz | int ou tuple | 640 | Alvo do letterbox. Um número inteiro define um N×N quadrado; uma tupla define (height, width). Com rect=True, o tensor real pode ser menor do que este alvo devido ao preenchimento em retângulo mínimo. Usa rect=False para um tamanho fixo. Consulta Formato fixo vs. retângulo mínimo. |
rect | bool | True | Se True, usa o preenchimento com retângulo mínimo quando possível (lote com formas iguais e backend compatível). Se False, usa sempre o imgsz completo. Consulta Forma fixa vs. retângulo mínimo. Ignorado para depth e modelos RT-DETR, que redimensionam as imagens para preencher o imgsz completo sem preenchimento. |
quantize | int ou str | None | Precisão de inferência: 16/"fp16" e 32/"fp32"/unset selecionam o cálculo em FP16 ou FP32 para modelos PyTorch e TorchScript (FP32 na CPU); os outros formatos usam a precisão selecionada pelo artefato e pelo ambiente de execução. Em 16, o OpenVINO ainda arredonda a entrada para FP16 no cliente e a converte de volta para FP32, sem alterar a precisão do ambiente de execução. A quantização INT8/PTQ é configurada durante a exportação e, em seguida, usada ao carregar o modelo exportado. Substitui a flag obsoleta half. |
device | str | None | Especifica o dispositivo para inferência (por exemplo, cpu, cuda:0, 0, npu ou npu:0). Permite que os usuários escolham entre CPU, uma GPU específica, NPU Huawei Ascend ou outros dispositivos de computação para executar modelos. Os modelos OpenVINO e LiteRT são executados em xpu e npu na GPU e na NPU Intel; consulte dispositivos de inferência para ver todos os formatos. |
dnn | bool | False | Se True, usa o módulo DNN do OpenCV em vez do ONNX Runtime para inferência com modelos ONNX. |
data | str | None | Caminho para um YAML de conjunto de dados (por exemplo, coco8.yaml), lido apenas para obter names e somente quando o modelo carregado não tem nomes de classe próprios: uma exportação de terceiros ou uma exportação da Ultralytics separada dos metadados que a acompanham. Caso contrário, esse modelo informa class0, class1 e assim por diante. |
batch | int | 1 | Especifica o tamanho do lote para inferência (funciona apenas quando a origem é um diretório, um arquivo de vídeo ou um arquivo .txt). Um tamanho de lote maior pode aumentar a taxa de processamento e reduzir o tempo total necessário para a inferência. |
tile | bool ou int | False | Executa inferência em blocos fixos e retorna os resultados nas coordenadas da imagem original. True usa imgsz; um inteiro positivo define o tamanho do bloco. Consulta Recorte em blocos de alta resolução. |
max_det | int | 300 | Número máximo de detecções permitido por imagem. Limita o número total de objetos que o modelo pode detectar em uma única inferência, evitando saídas excessivas em cenas densas. |
vid_stride | int | 1 | Intervalo entre quadros para entradas de vídeo. Permite ignorar quadros em vídeos para acelerar o processamento, à custa da resolução temporal. O valor 1 processa todos os quadros; valores maiores ignoram quadros. |
stream_buffer | bool | False | Determina se os quadros recebidos em fluxos de vídeo devem ser enfileirados. Se False, os quadros antigos são descartados para dar lugar aos novos (otimizado para aplicações em tempo real). Se True, os quadros novos são enfileirados em um buffer, garantindo que nenhum quadro seja ignorado, mas causando latência se o FPS da inferência for inferior ao FPS do fluxo. |
visualize | bool | False | Salva um mapa de calor de ativação de classe junto a cada predição, mostrando quais pixels elevaram as pontuações da classe prevista. Respeita conf e classes, portanto classes=[0] mapeia apenas essa classe. Disponível somente para modelos PyTorch da Ultralytics. |
augment | bool | False | Ativa o aumento em tempo de teste (TTA) para as predições, podendo melhorar a robustez da detecção à custa da velocidade de inferência. Disponível somente para modelos PyTorch da Ultralytics. |
agnostic_nms | bool | False | Ativa a Supressão Não Máxima (NMS) independente de classe, suprimindo caixas sobrepostas com pontuações menores entre classes diferentes, em vez de apenas dentro da mesma classe. Útil em cenários de detecção multiclasse nos quais a sobreposição entre classes é comum. Com a inferência sem NMS (nms=False no YOLO26 ou YOLOv10), isso apenas impede que a mesma detecção apareça com vários rótulos de classe (duplicatas com IoU=1.0) e não aplica supressão baseada em limiar de IoU entre caixas distintas. |
classes | list[int] | None | Filtra as predições para um conjunto de IDs de classe. Somente as detecções pertencentes às classes especificadas serão retornadas. Útil para priorizar objetos relevantes em tarefas de detecção multiclasse. |
retina_masks | bool | False | Retorna máscaras de segmentação em alta resolução. Quando ativado, as máscaras retornadas (masks.data) correspondem ao tamanho original da imagem. Quando desativado, elas têm o tamanho da imagem usado durante a inferência. |
embed | list[int] | None | Especifica as camadas das quais extrair vetores de características ou incorporações. Usa model.embed(source) para incorporações da penúltima camada ou model.predict(source, embed=[layer]) para selecionar camadas específicas. Útil para tarefas posteriores, como agrupamento ou busca por similaridade. Disponível somente para modelos PyTorch da Ultralytics. |
project | str | None | Nome do diretório do projeto onde as saídas da predição são salvas se save estiver ativado. Um caminho relativo é colocado em runs_dir/<task>, enquanto um caminho absoluto é usado sem alterações. |
name | str | None | Nome da execução de predição. Usado para criar um subdiretório dentro da pasta do projeto, onde as saídas das predições são armazenadas quando save está ativado. |
stream | bool | False | Ativa o processamento com uso eficiente de memória para vídeos longos ou muitas imagens, retornando um gerador de objetos Results em vez de carregar todos os quadros na memória de uma só vez. |
verbose | bool | True | Controla se os registros detalhados da inferência são exibidos no terminal, fornecendo informações em tempo real sobre o processo de predição. |
compile | bool ou str | False | Ativa 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_last | bool | None | Usa o formato de memória channels_last (NHWC) para inferência nativa com PyTorch. None ativa-o automaticamente em CPUs x86 com Linux e Windows compatíveis com oneDNN e PyTorch 1.13 ou mais recente; False desativa-o; e True solicita-o em dispositivos CPU x86 ou CUDA compatíveis. ARM64, MPS, versões mais antigas do PyTorch, CPUs sem oneDNN e formatos exportados, como TensorRT e ONNX, permanecem inalterados. |
nms | bool, opcional | None | Executa inferência de um para muitos com NMS por padrão (None ou True). Define False para usar a cabeça de um para um sem NMS quando disponível. Consulte o guia de detecção de ponta a ponta para obter detalhes. |
Argumentos de visualização:
| Argumento | Tipo | Padrão | Descrição |
|---|---|---|---|
show | bool | False | Se True, exibe as imagens ou os vídeos anotados em uma janela. Útil para obter feedback visual imediato durante o desenvolvimento ou os testes. |
save | bool | False or True | Ativa o salvamento das imagens ou dos vídeos anotados em arquivos. Útil para documentação, análises adicionais ou compartilhamento de resultados. O padrão é True ao usar a CLI e False ao usar Python. |
save_frames | bool | False | Ao processar vídeos, salva os quadros individuais como imagens. Útil para extrair quadros específicos ou fazer uma análise detalhada quadro a quadro. |
save_txt | bool | False | Salva os resultados da detecção em um arquivo de texto, seguindo o formato [class] [x_center] [y_center] [width] [height] [confidence]. Útil para integração com outras ferramentas de análise. |
save_conf | bool | False | Inclui pontuações de confiança nos arquivos de texto salvos. Aumenta o nível de detalhe disponível para pós-processamento e análise. |
save_crop | bool | False | Salva imagens recortadas das detecções. Útil para aumento de dados, análise ou criação de conjuntos de dados específicos para determinados objetos. |
show_labels | bool | True | Exibe os rótulos de cada detecção na saída visual. Permite identificar imediatamente os objetos detectados. |
show_conf | bool | True | Exibe a pontuação de confiança de cada detecção junto ao rótulo. Mostra o grau de certeza do modelo em cada detecção. |
show_boxes | bool | True | Desenha caixas delimitadoras ao redor dos objetos detectados. Essencial para identificar visualmente e localizar objetos em imagens ou quadros de vídeo. |
line_width | int or None | None | Especifica a espessura das linhas das caixas delimitadoras. Se None, a espessura da linha é ajustada automaticamente com base no tamanho da imagem. Permite personalizar a visualização para melhorar a clareza. |
Configurações de validação#
As configurações de validação dos modelos YOLO incluem hiperparâmetros e configurações para avaliar o desempenho em um conjunto de dados de validação. Essas configurações influenciam o desempenho, a velocidade e a precisão. As configurações comuns incluem tamanho do lote, tamanho da imagem, limiares de confiança e IoU, além da divisão do conjunto de dados a ser avaliada. O tamanho e a composição do conjunto de dados de validação, bem como a tarefa específica, também afetam o processo.
| Argumento | Tipo | Padrão | Descrição |
|---|---|---|---|
data | str | None | Especifica o caminho para o YAML do conjunto de dados (por exemplo, coco8.yaml), que deve incluir o caminho para os dados de validação. Para classificação, use um diretório de conjunto de dados ou o nome de um conjunto de dados integrado (por exemplo, imagenet10). |
imgsz | int | 640 | Define o tamanho das imagens de entrada. Todas as imagens são redimensionadas para essa dimensão antes do processamento. Tamanhos maiores podem melhorar a precisão para objetos pequenos, mas aumentam o tempo de computação. |
batch | int | 16 | Define o número de imagens por lote. Valores maiores aproveitam a memória da GPU com mais eficiência, mas exigem mais VRAM. Ajuste o valor de acordo com os recursos de hardware disponíveis. |
tile | bool ou int | False | Executa inferência em blocos fixos e avalia os resultados combinados em relação às anotações da imagem original completa. True usa imgsz; um inteiro positivo define o tamanho do bloco. Consulta Recorte em blocos de alta resolução. |
save_json | bool | False | Se True, salva os resultados em um arquivo JSON para análise posterior, integração com outras ferramentas ou envio a servidores de avaliação, como o COCO. Em conjuntos de dados de detecção, também avalia as previsões com faster-coco-eval e informa o mAP de objetos pequenos, médios e grandes, registrado durante o treinamento como metrics/mAP_small(B), metrics/mAP_medium(B) e metrics/mAP_large(B) em results.csv. Para segmentação semântica, em vez disso, salva máscaras de classe PNG em results/, mantendo os subdiretórios das imagens. |
conf | float | 0.001 | Define o limiar mínimo de confiança para as detecções. Valores menores aumentam a revocação, mas podem gerar mais falsos positivos. As curvas precisão-revocação, o mAP e as matrizes de confusão da detecção usam esse valor; um conf mais alto, como 0.25, produz uma matriz mais próxima da saída da predição, mas pode reduzir o mAP. A precisão e a revocação resumidas usam a confiança de F1 máximo e, por isso, podem diferir dos valores derivados de confusion_matrix.png. O padrão é 0.01 para validação OBB, a fim de reduzir o uso de memória. |
iou | float | 0.7 | Define o limiar de Interseção sobre União para a Supressão Não Máxima. Controla a eliminação de detecções duplicadas. |
max_det | int | 300 | Limita o número máximo de detecções por imagem. Para detect, segment, pose e OBB, se o valor permanecer em 300, ele é aumentado até a maior contagem de objetos rotulados na divisão validada quando uma imagem ultrapassa esse limite, com um aviso; qualquer outro valor é mantido, com um aviso de que a revocação pode ser limitada quando uma imagem exceder esse valor. |
quantize | int ou str | None | Precisão de validação: 16/"fp16" e 32/"fp32"/unset selecionam o cálculo em FP16 ou FP32 para modelos PyTorch e TorchScript (FP32 na CPU); os outros formatos usam a precisão selecionada pelo artefato e pelo ambiente de execução. Em 16, o OpenVINO ainda arredonda a entrada para FP16 no cliente e a converte de volta para FP32, sem alterar a precisão do ambiente de execução. A quantização INT8/PTQ é configurada durante a exportação e, em seguida, usada ao validar o modelo exportado. Substitui a flag obsoleta half. |
device | str | None | Especifica o dispositivo para validação (cpu, cuda:0, npu, npu:0 etc.). Quando None, seleciona automaticamente o melhor dispositivo disponível. É possível especificar vários dispositivos CUDA separando-os por vírgulas. Os modelos OpenVINO e LiteRT são executados em xpu e npu na GPU e na NPU Intel; consulte dispositivos de inferência para ver todos os formatos. |
dnn | bool | False | Se True, usa o módulo DNN do OpenCV para inferência com modelos ONNX, como alternativa aos métodos de inferência do PyTorch. |
plots | bool | True | Quando definido como True, gera e salva gráficos de predições em comparação com a verdade fundamental, matrizes de confusão e curvas PR para a avaliação visual do desempenho do modelo. |
classes | list[int] | None | Especifica uma lista de IDs de classe a avaliar. Útil para filtrar e focar apenas em determinadas classes durante a avaliação. |
rect | bool | True | Se True, agrupa proporções de imagem semelhantes em formas retangulares. Adiciona metade de um stride antes de arredondar cada dimensão para cima até um múltiplo do stride (sem metade extra do stride para semantic). Com stride 32, uma imagem de 640×640 em imgsz=640 passa a ter 672×672 com um deslocamento de 16 px, enquanto predict usa 640×640, então as métricas podem diferir. rect=False corresponde a predict para imagens quadradas. Ignorado para depth e RT-DETR, que redimensionam as imagens para um quadrado imgsz. |
split | str | 'val' | Determina a divisão do conjunto de dados a usar na validação (val, test ou train). Permite escolher com flexibilidade o segmento de dados para avaliar o desempenho. |
fraction | float, int ou list | 1.0 | Subconjunto da divisão validada. Com uma lista [train, val, test], aplica-se a entrada correspondente a split (1 = divisão completa; números inteiros acima de 1 = quantidade de imagens; entradas omitidas = divisão completa). Um valor escalar aplica-se somente a split=train; val e test usam então a divisão completa. |
project | str | None | Nome do diretório do projeto onde as saídas da validação são salvas. Um caminho relativo é colocado em runs_dir/<task>, enquanto um caminho absoluto é usado sem alterações. |
name | str | None | Nome da execução de validação. Usado para criar um subdiretório dentro da pasta do projeto, onde os registros e as saídas da validação são armazenados. |
verbose | bool | True | Se True, exibe informações detalhadas durante o processo de validação, incluindo métricas por classe, progresso dos lotes e informações adicionais de depuração. |
save_txt | bool | False | Se True, salva os resultados da detecção em arquivos de texto, um arquivo por imagem, para análise adicional, pós-processamento personalizado ou integração com outros sistemas. |
save_conf | bool | False | Se True, inclui valores de confiança nos arquivos de texto salvos quando save_txt está ativado, fornecendo uma saída mais detalhada para análise e filtragem. |
workers | int | 8 | Número de threads de trabalho para carregar dados. Valores maiores podem acelerar o pré-processamento dos dados, mas podem aumentar o uso da CPU. Definir como 0 usa a thread principal, o que pode ser mais estável em alguns ambientes. |
augment | bool | False | Ativa o aumento em tempo de teste (TTA) durante a validação, podendo melhorar a precisão da detecção à custa da velocidade de inferência, executando a inferência em versões transformadas da entrada. Disponível somente para modelos PyTorch da Ultralytics. |
agnostic_nms | bool | False | Ativa a supressão não máxima independente de classe, suprimindo caixas sobrepostas com pontuações mais baixas, independentemente da classe prevista. Útil para aplicações focadas em instâncias. Com inferência sem NMS (nms=False em YOLO26 ou YOLOv10), isso apenas impede que a mesma detecção apareça com vários rótulos de classe (duplicatas com IoU=1.0) e não realiza supressão baseada em limiar de IoU entre caixas distintas. |
single_cls | bool | False | Trata todas as classes como uma única classe durante a validação. Útil para avaliar o desempenho do modelo em tarefas de detecção binária ou quando as distinções entre classes não são importantes. |
visualize | bool | False | Visualiza as verdades fundamentais, os verdadeiros positivos, os falsos positivos e os falsos negativos de cada imagem. Útil para depuração e interpretação do modelo. |
show_labels | bool | True | Exibe os rótulos de classe nas visualizações de validação quando visualize=True. Define como False para facilitar a visualização das correspondências e dos erros. |
show_conf | bool | True | Exibe as pontuações de confiança nas visualizações de validação quando visualize=True. Define como False para facilitar a visualização das correspondências e dos erros. |
compile | bool ou str | False | Ativa 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_last | bool | None | Usa o formato de memória channels_last (NHWC) para validação nativa com PyTorch. None ativa-o automaticamente em CPUs x86 com Linux e Windows compatíveis com oneDNN e PyTorch 1.13 ou mais recente; False desativa-o; e True solicita-o em dispositivos CPU x86 ou CUDA compatíveis. ARM64, MPS, versões mais antigas do PyTorch, CPUs sem oneDNN e formatos exportados permanecem inalterados; durante o treinamento, a validação mantém o layout do modelo de treinamento. |
nms | bool, opcional | None | Executa inferência de um para muitos com NMS por padrão (None ou True). Define False para usar a cabeça de um para um sem NMS quando disponível. Consulte o guia de detecção de ponta a ponta para obter detalhes. |
O ajuste cuidadoso e a experimentação são essenciais para garantir o desempenho ideal e detectar e evitar o sobreajuste.
Configurações de exportação#
As configurações de exportação dos modelos YOLO incluem opções para salvar ou exportar o modelo para uso em diferentes ambientes. Essas configurações afetam o desempenho, o tamanho e a compatibilidade. Entre as principais configurações estão o formato do arquivo exportado (por exemplo, ONNX, TensorFlow SavedModel), o dispositivo de destino (por exemplo, CPU, GPU) e a precisão numérica por meio da quantização (quantize). A tarefa do modelo e as limitações do ambiente de destino também afetam o processo de exportação.
| Argumento | Tipo | Padrão | Descrição |
|---|---|---|---|
format | str | 'torchscript' | Formato de destino do modelo exportado, como 'onnx', 'torchscript', 'engine' (TensorRT) ou outros. Cada formato permite a compatibilidade com diferentes ambientes de implantação. |
name | str | None | Nome do hardware de destino para os formatos que exigem um: arquitetura Hailo ('hailo8', 'hailo8l', 'hailo10h', 'hailo15h', 'hailo15l'; o padrão é 'hailo8l'), chip Rockchip RKNN (o padrão é 'rk3588'), SoC Huawei Ascend (um --soc_version do CANN; o padrão é 'Ascend310B4'), destino Qualcomm QNN HTP (o padrão é '73') ou dispositivo AMD Xilinx Versal AI Edge Series Gen 2 (o padrão é 've2-xc2ve3858', o kit de avaliação VEK385). Diferente do par de nomes de execução project/name usado por outros modos. |
imgsz | int ou tuple | 640 | Tamanho de imagem desejado para a entrada do modelo. Pode ser um inteiro para imagens quadradas (por exemplo, 640 para 640×640) ou uma tupla (height, width) para dimensões específicas. Se não for informado, a exportação reutiliza o tamanho de treinamento registrado no checkpoint carregado: os checkpoints oficiais do YOLO26 registram 1024 para modelos semânticos pré-treinados no Cityscapes (yolo26n-sem.pt), 768 para profundidade, 224 para classificação, 1024 para OBB e 640 para as outras tarefas, inclusive modelos semânticos pré-treinados no ADE20K (yolo26n-sem-ade20k.pt), enquanto um ajuste fino registra o tamanho imgsz usado no treinamento. Um modelo criado a partir de um YAML não tem tamanho de treinamento registrado e usa 640. |
optimize | bool | False | Ativa uma otimização mais avançada do compilador para DEEPX, reduzindo a latência da inferência e aumentando o tempo de compilação. |
quantize | int ou str | None | Precisão da quantização: 16 (FP16, reduz o tamanho do modelo e pode acelerar a inferência em hardware compatível) ou 8 (INT8/PTQ, comprime ainda mais o modelo com perda mínima de precisão, principalmente para dispositivos de borda; requer calibração data/fraction); 32 seleciona FP32 quando compatível; se não for definido, usa FP32, a menos que o destino exija quantização, como INT8 para NXP. Um checkpoint treinado com quantize=8 sempre é exportado em INT8: onnx e engine são exportados a partir dos intervalos que carregam, sem calibração, e outros formatos ou precisões são rejeitados. 'w8a8' e 'w16a16' são aliases de 8 e 16; as precisões mistas 'w8a16' (pesos INT8 com ativações de 16 bits: CoreML, LiteRT, QNN) e 'w8a32' (INT8 dinâmico: LiteRT) são aceitas somente por esses formatos. Substitui as flags obsoletas half/int8 (half=True → 16, int8=True → 8, ainda aceitas com um aviso de descontinuação). Somente as precisões compatíveis com o formato de destino são permitidas (veja abaixo). |
dynamic | bool | False | Permite tamanhos de entrada dinâmicos nas exportações TorchScript, ONNX, OpenVINO, TensorRT, CoreML e MNN, aumentando a flexibilidade para lidar com dimensões de imagem variáveis. |
simplify | bool | True | Simplifica o grafo ONNX intermediário com onnxslim nas exportações que o geram (consulte Formatos de exportação), podendo melhorar o desempenho e a compatibilidade com mecanismos de inferência. |
opset | int | None | Especifica a versão do opset do ONNX para as exportações que criam um grafo ONNX (consulte Formatos de exportação), para garantir compatibilidade com diferentes analisadores e ambientes de execução ONNX. Se não for definido, usa o opset 18 (uma versão inferior no PyTorch < 2.4), limitado à versão instalada onnx. As exportações para RKNN, Ascend, AMD Xilinx, Hailo e RT-DETR TensorFlow definem seu próprio opset. |
workspace | float ou None | None | Define o tamanho máximo do espaço de trabalho, em GiB, para otimizações TensorRT, equilibrando o uso de memória e o desempenho. Use None para que o TensorRT aloque automaticamente até o máximo do dispositivo. |
nms | bool, opcional | None | None exporta previsões brutas de um para muitos para NMS externo (YOLO26 mantém sua cabeça sem NMS na Axelera); True incorpora NMS quando há suporte; False seleciona a cabeça sem NMS quando disponível. O NMS incorporado do CoreML é compatível com detecção, segmentação e pose com dimensões estáticas. Consulta o guia de deteção end-to-end. |
conf | float | None | Limiar de confiança usado sempre que a NMS é gerada durante a exportação: exportações nms=True; exportações detect da Hailo que não são de ponta a ponta; e exportações detect, pose e segment do IMX, que definem internamente nms=True. O padrão, se não for definido, é 0.25. |
iou | float | 0.5 | Limiar de IoU usado sempre que a NMS é gerada durante a exportação: exportações nms=True; exportações detect da Hailo que não são de ponta a ponta; e exportações detect, pose e segment do IMX, que definem internamente nms=True. |
max_det | int | 300 | Número máximo de detecções mantidas na saída do modelo exportado. Aplica-se às exportações nms=True em todos os formatos, exceto à detecção CoreML, cujo pipeline nativo de NMS não tem limite de detecções, além das exportações de detecção de ponta a ponta sem NMS (YOLO26, YOLOv10, limitadas ao número de âncoras disponíveis) e das exportações detect, pose e segment do IMX. |
agnostic_nms | bool | False | Ativa a NMS independente de classe sempre que ela é gerada durante a exportação pelo pipeline padrão nms=True, incluindo a própria etapa de NMS do CoreML, suprimindo caixas sobrepostas com pontuações menores entre classes diferentes, em vez de apenas dentro da mesma classe. Não é aplicada às configurações de NMS geradas pela própria Hailo ou pelo IMX, que não têm uma opção independente de classe e permanecem cientes das classes, independentemente dessa flag. Também é incorporada às exportações de ponta a ponta sem NMS (YOLO26, YOLOv10), nas quais apenas impede que a mesma detecção apareça com vários rótulos de classe (duplicatas com IoU=1.0), sem aplicar supressão baseada em limiar de IoU entre caixas distintas. |
batch | int | 1 | Especifica o tamanho do lote de inferência do modelo exportado ou o número máximo de imagens que o modelo exportado processará simultaneamente no modo predict. Os formatos sem batch nos argumentos de exportação exportam com lote 1 e rejeitam outros valores. |
device | str | None | Especifica o dispositivo para exportação: GPU (device=0), CPU (device=cpu), MPS para Apple silicon (device=mps), NPU Huawei Ascend (device=npu ou device=npu:0) ou DLA para NVIDIA Jetson (device=dla:0 ou device=dla:1). As exportações TensorRT usam a GPU automaticamente, mas TensorRT 11 não oferece suporte a DLA. As exportações OpenVINO INT8 com device=npu são ajustadas para NPUs Intel. |
verbose | bool | False | Eleva o nível de severidade do registro do compilador TensorRT para VERBOSE durante a exportação format='engine'. Os outros formatos de exportação ignoram essa opção. |
data | str | None | Calibração dataset: um caminho YAML (não classificação), um caminho ou URL NDJSON, ou um URI de conjunto de dados da Plataforma (ul://owner/datasets/name) ou URL da web. Os conjuntos de dados da Plataforma requerem uma chave de API e Python 3.11+. A classificação também aceita um diretório de conjunto de dados ou o nome de um conjunto de dados integrado. Se não for especificado com INT8 ativado, a Ultralytics seleciona um conjunto de dados de calibração específico da tarefa quando necessário, ou recorre ao conjunto de dados predefinido para a tarefa do modelo. Um checkpoint treinado com quantize=8 contém os próprios intervalos INT8 e não requer dados de calibração. |
split | str | 'val' | Divisão do conjunto de dados ('train', 'val' ou 'test') usada para criar o carregador de dados de calibração da quantização INT8 a partir de data. |
fraction | float, int ou list | 1.0 | Subconjunto do conjunto de dados usado para calibração INT8: uma proporção, uma quantidade de imagens ou valores [train, val, test]. 1 significa a divisão completa; números inteiros acima de 1 indicam a quantidade de imagens; e somente a entrada opcional de teste aceita 0/0.0 para indicar nenhum. Listas de dois itens mantêm test completo. |
Uma configuração cuidadosa garante que o modelo exportado seja otimizado para seu caso de uso e funcione de forma eficaz no ambiente de destino.
Configurações de soluções#
As configurações do Ultralytics Solutions oferecem flexibilidade para personalizar modelos para tarefas como contagem de objetos, criação de mapas de calor, acompanhamento de exercícios, análise de dados, rastreamento de zonas, gerenciamento de filas e contagem por região. Essas opções permitem fazer ajustes facilmente para obter resultados precisos e úteis, adaptados a necessidades específicas.
| Argumento | Tipo | Padrão | Descrição |
|---|---|---|---|
model | str | None | Caminho para um arquivo de modelo Ultralytics YOLO. |
region | list ou dict | None | Pontos que definem a região de interesse, seja como uma lista de tuplas (x, y) ou como um dicionário que associa nomes de regiões a listas de pontos para várias regiões (somente RegionCounter). Quando None, as soluções que exigem uma região usam uma região padrão predefinida. |
show_in | bool | True | Flag que controla se as contagens de entrada são exibidas no fluxo de vídeo. |
show_out | bool | True | Flag que controla se as contagens de saída são exibidas no fluxo de vídeo. |
analytics_type | str | 'line' | Tipo de gráfico, por exemplo, line, bar, area ou pie. |
colormap | int | cv2.COLORMAP_DEEPGREEN | Mapa de cores a usar no mapa de calor. |
line_width | int | 2 | Espessura das linhas das caixas, dos pontos-chave e das contagens desenhados pela solução. |
verbose | bool | True | Ativa o registro por quadro da solução, com o formato da entrada, as contagens por classe e a velocidade de processamento. A chamada de rastreamento em si é sempre silenciosa. |
json_file | str | None | Caminho para o arquivo JSON que contém todos os dados de coordenadas das vagas de estacionamento. |
up_angle | float | 145.0 | Limiar de ângulo para a pose de 'subida'. |
kpts | list[int] | [6, 8, 10] | Lista de três índices de pontos-chave usados para monitorar exercícios. Esses pontos-chave correspondem a articulações ou partes do corpo, como ombros, cotovelos e pulsos, em exercícios como flexões, barras, agachamentos e exercícios abdominais. |
down_angle | float | 90.0 | Limiar de ângulo para a pose de 'descida'. |
blur_ratio | float | 0.5 | Ajusta a percentagem da intensidade do desfoque, com valores no intervalo 0.1 - 1.0. |
crop_dir | str | 'cropped-detections' | Nome do diretório para armazenar deteções recortadas. |
records | int | 5 | Número total de deteções necessário para acionar um e-mail com o alarme de segurança. |
vision_point | tuple[int, int] | (20, 20) | O ponto onde a visão irá acompanhar objetos e desenhar trajetórias com a solução VisionEye. |
source | str | None | Caminho para a origem de entrada (vídeo, RTSP, etc.). Só pode ser usado com a interface de linha de comandos (CLI) de Solutions. |
figsize | tuple[float, float] | (12.8, 7.2) | Tamanho da figura em polegadas para gráficos Analytics; (12.8, 7.2) renderiza um fotograma de 1280×720. |
fps | float | 30.0 | Fotogramas por segundo usados nos cálculos de velocidade. |
max_hist | int | 5 | Número máximo de pontos históricos a acompanhar por objeto para calcular a velocidade/direção. |
meter_per_pixel | float | 0.05 | Fator de escala usado para converter a distância em píxeis em unidades do mundo real. |
max_speed | int | 120 | Velocidade máxima em km/h; as velocidades estimadas superiores são limitadas a este valor. |
data | str | 'images' | Caminho para o diretório de imagens usado na pesquisa por semelhança. |
imgsz | int | 640 | Tamanho da imagem de entrada para inferência do modelo. |
recognizer | str ou Callable | 'paddleocr' | Backend de reconhecimento de texto: 'paddleocr' (PP-OCRv6 no ONNX Runtime), 'tensorrt' (PP-OCRv6 como mecanismo TensorRT FP16 em GPUs NVIDIA), um nome de modelo de idioma do PaddleOCR, como 'korean_PP-OCRv5_mobile_rec', ou um chamável que aceite um recorte BGR e retorne (text, confidence). |
Definições de aumento de dados#
As técnicas de aumento de dados são essenciais para melhorar a robustez e o desempenho do modelo YOLO, introduzindo variabilidade nos dados de treino, o que ajuda o modelo a generalizar melhor para dados que ainda não viu. A tabela seguinte descreve a finalidade e o efeito de cada argumento de aumento de dados:
| Argumento | Tipo | Padrão | Tarefas suportadas | Intervalo | Descrição |
|---|---|---|---|---|---|
hsv_h | float | 0.015 | detect, segment, semantic, depth, classify, pose, obb | 0.0 - 1.0 | Ajusta 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_s | float | 0.7 | detect, segment, semantic, depth, classify, pose, obb | 0.0 - 1.0 | Altera 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_v | float | 0.4 | detect, segment, semantic, depth, classify, pose, obb | 0.0 - 1.0 | Modifica 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. |
degrees | float | 0 | detect, segment, semantic, depth, pose, obb | 0.0 - 180 | Roda a imagem aleatoriamente dentro do intervalo de graus especificado, melhorando a capacidade do modelo de reconhecer objetos em várias orientações. |
translate | float | 0.1 | detect, segment, semantic, depth, pose, obb | 0.0 - 1.0 | Desloca 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. |
scale | float | tuple | 0.5 | detect, segment, semantic, depth, classify, pose, obb | 0 - 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. |
shear | float | 0 | detect, segment, semantic, depth, pose, obb | -180 - +180 | Aplica uma deformação de cisalhamento à imagem segundo um grau especificado, imitando o efeito de observar objetos de diferentes ângulos. |
perspective | float | 0 | detect, segment, semantic, depth, pose, obb | 0.0 - 0.001 | Aplica uma transformação de perspetiva aleatória à imagem, melhorando a capacidade do modelo de compreender objetos no espaço 3D. |
flipud | float | 0 | detect, segment, semantic, depth, classify, pose, obb | 0.0 - 1.0 | Inverte a imagem de cabeça para baixo com a probabilidade especificada, aumentando a variabilidade dos dados sem afetar as características do objeto. |
fliplr | float | 0.5 | detect, segment, semantic, depth, classify, pose, obb | 0.0 - 1.0 | Inverte 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. |
bgr | float | 0 | detect, segment, semantic, depth, pose, obb | 0.0 - 1.0 | Inverte 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. |
mosaic | float | 1 | detect, segment, semantic, pose, obb | 0.0 - 1.0 | Combina quatro imagens de treinamento em uma, simulando diferentes composições de cena e interações entre objetos. Eficaz para compreender cenas complexas. |
mixup | float | 0 | detect, segment, semantic, pose, obb | 0.0 - 1.0 | Combina 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. |
cutmix | float | 0 | detect, segment, semantic, pose, obb | 0.0 - 1.0 | Combina 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_paste | float | 0 | segment, semantic, obb | 0.0 - 1.0 | Fraçã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_mode | str | flip | segment, semantic, obb | - | Especifica a estratégia copy-paste a utilizar. As opções incluem 'flip' e 'mixup'. |
auto_augment | str | randaugment | classify | - | Aplica uma política de aumento de dados predefinida ('randaugment', 'autoaugment' ou 'augmix') para melhorar o desempenho do modelo através da diversidade visual. |
erasing | float | 0.4 | classify | 0.0 - 1.0 | Apaga aleatoriamente regiões da imagem durante o treino para incentivar o modelo a focar-se em características menos óbvias. |
augmentations | list | None | detect, 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. |
Ajusta estas definições de acordo com os requisitos do conjunto de dados e da tarefa. Experimentar valores diferentes pode ajudar a encontrar a estratégia de aumento de dados ideal para obter o melhor desempenho do modelo.
Definições de registo, pontos de controlo e gráficos#
O registo, os pontos de controlo, os gráficos e a gestão de ficheiros são importantes durante o treino de um modelo YOLO:
- Registo: acompanha o progresso do modelo e diagnostica problemas com bibliotecas como TensorBoard ou escrevendo num ficheiro.
- Pontos de controlo: guarda o modelo em intervalos regulares para retomar o treino ou experimentar configurações diferentes.
- Gráficos: visualiza o desempenho e o progresso do treino com bibliotecas como Matplotlib ou TensorBoard.
- Gestão de ficheiros: organiza os ficheiros gerados durante o treino, como pontos de controlo, ficheiros de registo e gráficos, para facilitar o acesso e a análise.
A gestão eficaz destes aspetos ajuda a acompanhar o progresso e facilita a depuração e a otimização.
| Argumento | Padrão | Descrição |
|---|---|---|
project | None | Especifica o diretório do projeto para as execuções. Um caminho relativo é colocado em runs_dir/<task> (por exemplo, project="my_proj" salva em runs/detect/my_proj/train no treinamento de detecção com o runs_dir padrão e o nome da execução); um caminho absoluto é usado sem alterações. Se não for especificado, as execuções são salvas em runs_dir/<task>. Cada execução é salva em um subdiretório separado. |
name | None | Define o nome da experiência. Se não for especificado, YOLO usa o nome do modo e incrementa-o a cada execução (por exemplo, train, train-2) para evitar substituir ficheiros. |
exist_ok | False | Determina se deve substituir um diretório de experiência existente. True permite a substituição; False impede-a. |
plots | True | Controla a geração e gravação de gráficos de treino e validação. Define como True para criar gráficos como curvas de perda, curvas de precisão-revocação e previsões de amostras para acompanhar visualmente o desempenho. |
save | True | Ativa a gravação de pontos de controlo do treino e dos pesos finais do modelo. Define como True para guardar periodicamente os estados do modelo, permitindo retomar o treino ou implementar o modelo. |
Ficheiro de configuração personalizado#
Carrega um ficheiro YAML guardado para reutilizar um conjunto completo de argumentos sem os passar em linha. O argumento cfg substitui os valores de default.yaml, enquanto os argumentos adicionais passados em conjunto continuam a ter prioridade.
| Argumento | Padrão | Descrição |
|---|---|---|
cfg | None | Caminho para um ficheiro YAML cujos valores substituem as entradas de default.yaml. Consulta Substituir o ficheiro de configuração predefinido para ver um exemplo prático de CLI. |
Perguntas frequentes#
Melhora o desempenho ajustando hiperparâmetros como o tamanho do lote, a taxa de aprendizagem, o momentum e o decaimento de pesos. Ajusta as configurações de aumento de dados, seleciona o otimizador certo e usa técnicas como a paragem antecipada ou a precisão mista.
Os principais hiperparâmetros que afetam a precisão incluem:
- Tamanho do lote (
batch): lotes maiores podem estabilizar o treino, mas exigem mais memória. - Taxa de aprendizagem (
lr0): taxas mais baixas permitem ajustes mais precisos, mas tornam a convergência mais lenta. - Momentum (
momentum): acelera os vetores de gradiente e atenua as oscilações. - Tamanho da imagem (
imgsz): tamanhos maiores melhoram a precisão, mas aumentam a carga computacional.
Ajusta estes valores de acordo com o teu conjunto de dados e hardware. Sabe mais em Definições de treino.
- Tamanho do lote (
A taxa de aprendizagem (
lr0) é crucial; começa com0.01para SGD ou0.001para o otimizador Adam e define explicitamenteoptimizer, uma vez que o valor predefinidoautoignoralr0. Acompanha as métricas e ajusta conforme necessário. Usa escalonadores da taxa de aprendizagem cossenoidais (cos_lr) ou aquecimento (warmup_epochs,warmup_momentum). Encontra mais detalhes no Guia de treino.As definições predefinidas incluem:
- Limiar de confiança (
conf=0.25): confiança mínima para as deteções. - Limite de IoU (
iou=0.5): Para supressão não máxima (NMS). A validação usaiou=0.7. - Tamanho da imagem (
imgsz=640): redimensiona as imagens de entrada. - Dispositivo (
device=None): seleciona CPU, GPU CUDA, Apple MPS, Intel XPU (xpu) ou NPU Huawei Ascend (npu). Os modelos OpenVINO e LiteRT são executados emxpuenpuna GPU e na NPU Intel; consulte dispositivos de inferência para ver todos os formatos.
Para uma visão geral completa, consulta Definições de previsão e o Guia de previsão.
- Limiar de confiança (
O treino de precisão mista (
amp=Trueouamp='bf16'para BF16) reduz o uso de memória e acelera o treino, combinando cálculos de meia precisão e FP32. É benéfico para GPUs modernas, pois permite usar modelos maiores e fazer cálculos mais rápidos sem perda significativa de precisão.
Comentários119
Faz uma pergunta, partilha os teus resultados ou ajuda alguém.
ykn96
@glenn-jocher alright thanks! I am going to be experimenting among the imgsz, multi_scale and all the batch size stuff
Glenn JocherUltralyticsThat sounds like a good plan — I’d start with
batch=-1to auto-fit GPU memory, then sweepimgszand a modestmulti_scalesuch as0.25; the Train Settings section is the best reference, and feel free to drop any results or blockers here.
ykn96
Hello! I have a question about best practices for training and runnining inference, question about the parameters rect and imgsz. So my dataset has a wide variety of resolutions and aspect ratios, but my video feed only has 1920x1080
Question;
- During training, should i set rect = True ?
- During training, should i set imgsz = 1920?
- During inference, do i need to set imgsz as the tuple 1920 x 1080?
Thank you!
A-tavv
Hi. You’re thinking about the right things, this mostly comes down to how well you want training to match your real inference scenario.
-
rect=True during training? Yes, generally a good idea in your case. Since your dataset has mixed aspect ratios, this helps preserve them instead of forcing everything into square shapes. That reduces distortion and usually improves performance, especially when your inference input (1920×1080) is not square.
-
imgsz=1920 during training? No, this is usually not practical. Training at 1920 will:
Use a lot of VRAM Slow training significantly Give diminishing returns
A better approach:
Use something like imgsz=640 or imgsz=1280 (depending on your GPU) The model will still generalize well to higher resolutions at inference
- imgsz=(1920,1080) during inference? You can, but you usually don’t need to.
Most YOLO implementations:
Resize while keeping aspect ratio (letterboxing) Expect a single integer like imgsz=640 or imgsz=1280
Recommended practical setup:
Train: imgsz=640 or 1280, rect=True Inference: same imgsz as training (e.g., 640 or 1280)
If you really want max detail at inference, you can increase imgsz, but:
It increases latency Gains are often small unless objects are very tiny
Rule of thumb: Train at a reasonable resolution, keep it consistent, and only scale up inference if you see a real accuracy bottleneck
-
Glenn JocherUltralyticsThat’s mostly right; the main correction is that if you pass a tuple for inference it should be
imgsz=(1080, 1920)because Ultralytics expects(height, width), andrect=Trueis already the default in predict mode. For training,rect=Truecan help with mixed aspect ratios, but I’d still keepimgszpractical like640or1280rather than1920unless you specifically need more small-object detail; feel free to post follow-ups here so the Ultralytics team can see them, and the relevant args are in the Configuration docs and Predict mode docs.ykn96
@glenn-jocher @A-tavv thank you for your help! Hmm im trying to train a head detector, so i think the heads are really small. Problem is i am encountering an out of memory problem even if i try to use an intermediate size such as 960.
I wil probably just stick to 640, since increasing the max_dets also makes me run into the OOM much earlier.
Glenn JocherUltralyticsYes, that sounds reasonable; for tiny heads
max_detusually won’t improve learning and mainly affects retained detections during val/predict, so I’d leave it near default, keepimgsz=640, reducebatchor trybatch=-1withamp=True, and if small-object recall is still limited the better next step is usually tiling/cropping your1920x1080frames into patches rather than pushing full-frame resolution higher; the relevant args are in the Configuration docs.
ykn96
Hey there! I have a question about the max_det parameter during training. So i am using the NWPU crowd dataset, which sometimes has 4000+ boxes in an image, i was wondering if it is necessary for me to increase max_det such that it can cover that number?
A-tavv
It is not necessary to match max_det to the number of ground truth boxes. It’s a post-processing limit, not a training constraint.
max_det mainly affects inference, not training.
During training, the model still sees all ground-truth boxes and learns from them max_det only limits how many predictions are kept after NMS (non maximum suppression) during inference/validation
So even if your images have 4000+ objects, the model is still learning from all of them.
When would increasing max_det matter?
Only if during validation/inference:
You notice predictions getting cut off Or evaluation metrics look artificially low because detections are being capped
In that case, you can increase it (e.g., 1000 → 3000 or higher), but keep in mind:
Higher max_det = slower NMS More memory usage
For dense datasets, in your case: NWPU-Crowd:
A practical setup:
Keep max_det moderate (e.g., 1000–2000) to start Check if predictions are being truncated Only increase if you see an actual limitation, not just based on GT count
ykn96
Will capping the max_det at a lower number affect the error that is being used for the back propagation during learning?
As i am trying to train a head detector, i can see that there are some heads that are not being detected, especially when they are closer to the background of the image i.e. further in the background and are thus smaller.
AlexShaGH
Greetings. I’m trying to understand what the best combination of training and inference parameters pertaining to image size for my specific imagery is. The training dataset is 16 bits depth images of the identical static size – 720 x 1280. The images coming for inference will be of the same specification. The model will be quantized to FP16 and deployed on edge device. It is my understanding that for the best speed, it’s better to specify the exact image size for training and for inference. How do I do this? If I issue model.train(…, imgsz=(720, 1280), rect=True) or model.train(…, imgsz=[720, 1280], rect=True), I get a warning:
WARNING ⚠️ updating to 'imgsz=1280'. 'train' and 'val' imgsz must be an integer, while 'predict' and 'export' imgsz may be a [h, w] list or an integer, i.e. 'yolo export imgsz=640,480' or 'yolo export imgsz=640'`
There is also a warning that it cannot be done on multiple GPUs and will default to rect=False. This I can solve by specifying only one cuda device.
Please, advise on how exactly to set the parameters for training and for inference so the model performs the best on static size imagery on edge device.
Brenda-Caroline
Hello everyone, the default image size for imgsz is 640. I have a question about resizing the image size. When choosing a size for the images, are they resized in a square or rectangular format? For example: 640 x 640; 256 x 256; 480 x 480 or 1080 x 1920
BaoQuoc285
How can I use focal loss in YOLOv11 CLI training to handle an imbalanced dataset?
e-roe
Hello, Does YOLOv11 actually perform data augmentation by increasing the dataset size, or does it only enhance diversity without expanding the dataset? My impression is that it doesn’t increase the dataset size—for example, it applies a filter to an image, and only the modified image is presented to the model, not the original one.
Glenn JocherUltralytics(editado)@e-roe YOLO11's data augmentation applies real-time transformations during training without permanently expanding the dataset size. Each epoch presents new variations of original images through techniques like mosaic and mixup (see Augmentation Settings). The original images remain in the dataset but are dynamically modified during training iterations.
1
rohith-aiunika
Hi yolo team, Is there any way to reduce the font size and hide the box in yolo object tracking? i am using this to track my video, results = model.track(source=video_path, show=False, stream=True, save=False)
Glenn JocherUltralytics(editado)@rohith-aiunika to hide the boxes and labels in tracking, set
show_boxes=Falseandshow_labels=False. Theline_widthargument controls the box thickness and scales the label text size, so lowering it reduces both. For more details, refer to the Predict Settings documentation.
rohith-aiunika
is there any way to reduce the font size and hide the box in yolo object tracking?
Glenn JocherUltralytics@rohith-aiunika to reduce the font size and hide the bounding boxes in YOLO object tracking, you can modify the visualization arguments in the code. Specifically, set
show_labels=False,show_boxes=False, and adjust theline_widthparameter if necessary. For more details, refer to the Predict Guide.
D3RK0
Is it possible to use Cutmix and Mixup data augmentations for training YOLOv8 analogously to this PyTorch code example: https://pytorch.org/vision/main/auto_examples/transforms/plot_cutmix_mixup.html#after-the-dataloader
Glenn JocherUltralytics(editado)YOLO supports both through training arguments:
mixupandcutmixset the probability (default 0.0) of applying each augmentation, e.g.model.train(data="coco8.yaml", mixup=0.2, cutmix=0.2). See Augmentation Settings.D3RK0
@glenn-jocher Many thanks for replying!
I have taken steps to manually implement cutmix-mixup augmentations for YOLOv8 training. As you may know, implementing cutmix-mixup augmentations will transform (at least for the version of PyTorch) the labels from integers to one-hot. Do you know if YOLOv8 is compatible with one-hot labels, especially in respect to its default loss function? Or will it require additional customisation?
Glenn JocherUltralyticsYOLOv8 does not natively support one-hot encoded labels, so using them may require adjustments to the loss function. You may need to customize the model to handle one-hot labels appropriately. If you have further questions, feel free to ask!
