Solução de problemas comuns do YOLO#

Este guia abrange os problemas mais comuns que encontrarás ao trabalhar com o Ultralytics YOLO26, agrupados pelo local onde ocorrem: installation, model training, prediction e deployment. Vai diretamente para a categoria correspondente ao teu erro ou consulta a FAQ para respostas rápidas. Cada entrada indica o problema e uma solução concreta que podes aplicar diretamente.

Problemas Comuns#

Erros de instalação#

Erros de instalação podem surgir devido a vários motivos, como versões incompatíveis, dependências ausentes ou configurações de ambiente incorretas. Primeiro, verifica se estás a fazer o seguinte:

• Estás a usar o Python 3.8 ou posterior conforme recomendado.
• Certifica-te de que tens a versão correta do PyTorch (1.8 ou posterior) instalada.
• Considera usar ambientes virtuais para evitar conflitos.
• Segue o official installation guide passo a passo.

Além disso, aqui tens soluções para problemas comuns de instalação.

Erros de Importação ou Problemas de Dependências#

Se obtiveres erros ao importar o YOLO26 ou se encontrares conflitos de dependências, tenta estes passos:

• Instalação Limpa: Começar com uma instalação limpa pode resolver problemas inesperados, especialmente após atualizações que alteram a estrutura ou funcionalidade do pacote.
• Atualiza Regularmente: Usa a versão mais recente da biblioteca, uma vez que versões antigas podem não ser compatíveis com atualizações recentes.
• Verifica Dependências: Confirma se todas as dependências necessárias estão corretamente instaladas e se possuem versões compatíveis.
• Analisa Alterações: Se instalaste uma versão antiga, consulta a documentação oficial ou o registo de alterações para compreender quaisquer mudanças estruturais importantes.

Executar o YOLO26 no GPU#

Se estás com dificuldades em executar o YOLO26 num GPU, considera os seguintes passos de resolução de problemas:

• Verifica a Compatibilidade e a Instalação do CUDA: Certifica-te de que a tua GPU é compatível com o CUDA e de que o CUDA está corretamente instalado. Usa o comando nvidia-smi para verificar o estado da tua GPU NVIDIA e a versão do CUDA.
• Verifica a Integração entre o PyTorch e o CUDA: Certifica-te de que o PyTorch consegue utilizar o CUDA executando import torch; print(torch.cuda.is_available()) num terminal Python. Se devolver 'True', o PyTorch está configurado para usar o CUDA.
• Ativação do Ambiente: Garante que estás no ambiente correto onde todos os pacotes necessários estão instalados.
• Atualiza os Teus Pacotes: Pacotes desatualizados podem não ser compatíveis com o teu GPU. Mantém-nos atualizados.
• Configuração do Programa: Verifica se o teu código solicita a utilização de GPU. Podes definir o argumento device ao executar o treino ou a predição (por exemplo, device=0).

import torch

cap = torch.cuda.get_device_capability(0) if torch.cuda.is_available() else (0, 0)
cudnn = torch.backends.cudnn.version() or 0
ok = "not compatible" if cudnn >= 91100 and (cap[0] < 7 or (cap[0] == 7 and cap[1] < 5)) else "should be ok"
print(f"Compute capability: SM {cap[0]}.{cap[1]}, cuDNN: {cudnn} => {ok}")

Problemas de Treino do Modelo#

Os problemas comuns de treino e as suas correções são abordados abaixo.

Verificação das Definições de Configuração#

Problema: Tens dúvidas sobre se as definições de configuração no ficheiro .yaml estão a ser aplicadas corretamente durante o treino do modelo.

Solução: As definições de configuração no ficheiro .yaml devem ser aplicadas ao utilizar a função model.train(). Para garantir que estas definições são aplicadas corretamente, segue estes passos:

• Confirma que o caminho para o teu ficheiro de configuração .yaml está correto.

• Certifica-te de que passas o caminho para o teu ficheiro .yaml como o argumento data ao chamar model.train(), conforme mostrado abaixo:

  model.train(data="/path/to/your/data.yaml", batch=4)

Acelerar o Treino com Múltiplos GPUs#

Problema: O treino é lento num único GPU e queres acelerar o processo usando múltiplos GPUs.

Solução: Aumentar o batch size pode acelerar o treino, mas é essencial ter em conta a capacidade de memória da GPU. Para acelerar o treino com multiple GPUs, segue estes passos:

• Garante que tens múltiplos GPUs disponíveis.

• Define o argumento device como uma lista de índices de GPU, por exemplo, device=[0,1,2,3].

• Aumenta o batch size correspondentemente para utilizar totalmente os múltiplos GPUs sem exceder os limites de memória.

• Modifica o teu comando de treino para utilizar múltiplos GPUs:

  # Adjust the batch size and other settings as needed to optimize training speed
  model.train(data="/path/to/your/data.yaml", batch=32, device=[0, 1, 2, 3])

Parâmetros de Monitorização Contínua#

Problema: Queres saber que parâmetros devem ser monitorizados continuamente durante o treino, além da loss.

Solução: Embora a loss seja uma métrica crucial para monitorizar, também é essencial acompanhar outras métricas para a otimização do desempenho do modelo. Algumas métricas chave a monitorizar durante o treino incluem:

• Precisão
• Recall
• Mean Average Precision (mAP)

Podes aceder a estas métricas a partir dos registos de treino ou usando ferramentas como o TensorBoard ou wandb para visualização. Implementar paragem antecipada (early stopping) com base nestas métricas pode ajudar-te a alcançar melhores resultados.

Ferramentas para Rastrear o Progresso do Treino#

Problema: Estás à procura de recomendações de ferramentas para rastrear o progresso do treino.

Solução: Para rastrear e visualizar o progresso do treino, podes considerar o uso das seguintes ferramentas:

• TensorBoard: O TensorBoard é uma escolha popular para visualizar métricas de treino, incluindo perda, accuracy e muito mais. Podes integrá-lo no teu processo de treino do YOLO26.
• Comet: O Comet disponibiliza um conjunto abrangente de ferramentas para o seguimento e comparação de experiências. Permite-te seguir métricas, hiperparâmetros e até pesos do modelo. A integração com os modelos YOLO também é simples, proporcionando uma visão geral completa do teu ciclo de experiências.
• Ultralytics Platform: A Ultralytics Platform oferece um ambiente especializado para o seguimento de modelos YOLO, dando-te uma plataforma centralizada para gerir métricas, conjuntos de dados e até colaborar com a tua equipa. Dado o seu foco adaptado ao YOLO, disponibiliza opções de seguimento mais personalizadas.

Como verificar se o treino está a ocorrer no GPU#

Problema: O valor de 'device' nos registos de treino é 'null' e não tens a certeza se o treino está a acontecer no GPU.

Solução: O valor de 'device' como 'null' significa habitualmente que o processo de treino está configurado para selecionar automaticamente uma GPU disponível, que é o comportamento predefinido. Para treinar numa GPU específica, define o argumento device quando iniciares o treino. O argumento device é um argumento de treino, pelo que defini-lo no .yaml do teu conjunto de dados não produz qualquer efeito:

from ultralytics import YOLO

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

# Use GPU 0; device=[0, 1] for multiple GPUs, device="cpu" for CPU
model.train(data="path/to/data.yaml", device=0)

Mantém-te atento à pasta 'runs' para registos e métricas para monitorizar o progresso do treino eficazmente.

Considerações Chave para um Treino de Modelo Eficaz#

Aqui estão algumas coisas a ter em mente, se estás a enfrentar problemas relacionados com o treino de modelos.

Formato do Dataset e Etiquetas

• Importância: A base de qualquer modelo de machine learning assenta na qualidade e no formato dos dados com que é treinado.
• Recomendação: Garante que o teu dataset personalizado e as suas etiquetas associadas cumprem o formato esperado. É crucial verificar se as anotações são precisas e de alta qualidade. Anotações incorretas ou de baixa qualidade podem descarrilar o processo de aprendizagem do modelo, levando a resultados imprevisíveis.

Convergência do Modelo

• Importância: A obtenção da convergência do modelo garante que este aprendeu o suficiente a partir dos training data.
• Recomendação: Ao treinar um modelo 'de raiz', é fundamental assegurar que o modelo atinge um nível satisfatório de convergência. Isto pode exigir uma duração de treino mais longa, com mais epochs, em comparação com o ajuste fino de um modelo existente.

Learning Rate e Tamanho de Lote

• Importância: Estes hiperparâmetros desempenham um papel fundamental na determinação de como o modelo atualiza os seus pesos durante o treino.
• Recomendação: Avalia regularmente se a taxa de aprendizagem e o batch size escolhidos são ideais para o teu dataset específico. Parâmetros que não estão em harmonia com as características do dataset podem prejudicar o desempenho do modelo.

Distribuição de Classes

• Importância: A distribuição de classes no teu dataset pode influenciar as tendências de previsão do modelo.
• Recomendação: Avalia regularmente a distribuição de classes dentro do teu dataset. Se houver um desequilíbrio de classes, há o risco de o modelo desenvolver uma tendência para a classe mais prevalente. Esta tendência pode ser evidente na matriz de confusão, onde o modelo pode prever predominantemente a classe maioritária.

Verificação Cruzada com Pesos Pré-treinados

• Importância: Aproveitar pesos pré-treinados pode fornecer um ponto de partida sólido para o treino do modelo, especialmente quando os dados são limitados.
• Recomendação: Como passo de diagnóstico, considera treinar o teu modelo usando os mesmos dados, mas inicializando-o com pesos pré-treinados. Se esta abordagem produzir uma matriz de confusão bem formada, pode sugerir que o modelo treinado 'do zero' pode precisar de mais treino ou ajustes.

Problemas Relacionados com Previsões do Modelo#

Os problemas comuns encontrados durante a previsão de modelos e as suas correções são abordados abaixo.

Obter Previsões de Bounding Box com o Teu Modelo Personalizado YOLO26#

Problema: Ao executar previsões com um modelo personalizado YOLO26, existem desafios com o formato e visualização das coordenadas das bounding boxes.

Solução:

• Formato de Coordenadas: O YOLO26 fornece coordenadas de bounding box em valores absolutos de píxeis. Para convertê-las para coordenadas relativas (variando de 0 a 1), precisas de dividir pelas dimensões da imagem. Por exemplo, digamos que o tamanho da tua imagem é 640x640. Então farias o seguinte:

  # Convert absolute coordinates to relative coordinates
  x1 = x1 / 640  # Divide x-coordinates by image width
  x2 = x2 / 640
  y1 = y1 / 640  # Divide y-coordinates by image height
  y2 = y2 / 640

• Nome do Ficheiro: Para obter o nome do ficheiro da imagem na qual estás a fazer previsões, acede ao caminho do ficheiro da imagem diretamente a partir do objeto de resultado dentro do teu ciclo de previsão.

Filtrar Objetos em Previsões YOLO26#

Problema: Enfrentar problemas sobre como filtrar e exibir apenas objetos específicos nos resultados de previsão ao executar o YOLO26 usando a biblioteca Ultralytics.

Solução: Para detetar classes específicas, usa o argumento classes para especificar as classes que queres incluir na saída. Por exemplo, para detetar apenas carros (assumindo que 'carros' têm o índice de classe 2):

yolo task=segment mode=predict model=yolo26n-seg.pt source='path/to/car.mp4' show=True classes=2

Compreender as Métricas de Precisão no YOLO26#

Problema: Confusão relativamente à diferença entre a precisão da caixa, a precisão da máscara e a precisão da confusion matrix no YOLO26.

Solução: A precisão da caixa mede a exatidão das caixas delimitadoras previstas em comparação com as caixas reais de referência, utilizando o IoU (Intersection over Union) como métrica. A precisão da máscara avalia a concordância entre as máscaras de segmentação previstas e as máscaras de referência na classificação de objetos ao nível do píxel. Por sua vez, a precisão da matriz de confusão foca-se na exatidão geral da classificação em todas as classes e não tem em conta a exatidão geométrica das previsões. É importante notar que uma bounding box pode ser geometricamente exata (verdadeiro positivo) mesmo que a previsão da classe esteja errada, o que gera diferenças entre a precisão da caixa e a precisão da matriz de confusão. Estas métricas avaliam aspetos distintos do desempenho de um modelo, refletindo a necessidade de diferentes métricas de avaliação em várias tarefas.

Extrair Dimensões de Objetos no YOLO26#

Problema: Dificuldade em recuperar o comprimento e altura dos objetos detetados no YOLO26, especialmente quando múltiplos objetos são detetados numa imagem.

Solução: Para obter as dimensões da caixa delimitadora, usa primeiro o modelo Ultralytics YOLO26 para predict objects numa imagem. Em seguida, extrai a informação de largura e altura das caixas delimitadoras a partir dos resultados da predição.

from ultralytics import YOLO

# Load a pretrained YOLO26 model
model = YOLO("yolo26n.pt")

# Specify the source image
source = "https://ultralytics.com/images/bus.jpg"

# Make predictions
results = model.predict(source, save=True, imgsz=320, conf=0.25)

# Extract bounding box dimensions
boxes = results[0].boxes.xywh.cpu()
for box in boxes:
    x, y, w, h = box
    print(f"Width of Box: {w}, Height of Box: {h}")

Desafios de Implementação#

Problemas de Implementação em GPU#

Problema: Implementar modelos num ambiente multi-GPU pode, por vezes, levar a comportamentos inesperados como uso de memória inesperado, resultados inconsistentes entre GPUs, etc.

Solução: Verifica a inicialização padrão do GPU. Alguns frameworks, como o PyTorch, podem inicializar operações CUDA num GPU padrão antes de transitar para os GPUs designados. Para contornar inicializações padrão inesperadas, especifica o GPU diretamente durante a implementação e previsão. Em seguida, usa ferramentas para monitorizar a utilização do GPU e o uso de memória para identificar quaisquer anomalias em tempo real. Além disso, garante que estás a usar a versão mais recente do framework ou biblioteca.

Problemas de Conversão/Exportação de Modelos#

Problema: Durante o processo de conversão ou exportação de modelos de machine learning para diferentes formatos ou plataformas, os utilizadores podem encontrar erros ou comportamentos inesperados.

Solução: Repassa os formatos suportados e as opções por formato na documentação do Export mode e, em seguida, verifica estes pontos:

• Verificação de Compatibilidade: Garante que estás a usar versões de bibliotecas e frameworks que são compatíveis entre si. Versões incompatíveis podem levar a erros inesperados durante a conversão.
• Reinicialização do Ambiente: Se estás a usar um ambiente interativo como o Jupyter ou Colab, considera reiniciar o teu ambiente após fazeres alterações ou instalações significativas. Um novo começo pode, por vezes, resolver problemas subjacentes.
• Documentação Oficial: Consulta sempre a documentação oficial da ferramenta ou biblioteca que estás a usar para a conversão. Frequentemente, contém diretrizes específicas e melhores práticas para a exportação de modelos.
• Suporte da Comunidade: Verifica o repositório oficial da biblioteca ou framework para problemas semelhantes reportados por outros utilizadores. Os responsáveis ou a comunidade podem ter fornecido soluções ou alternativas em tópicos de discussão.
• Atualiza Regularmente: Garante que estás a usar a versão mais recente da ferramenta ou biblioteca. Os programadores lançam frequentemente atualizações que corrigem bugs conhecidos ou melhoram a funcionalidade.
• Testa de Forma Incremental: Antes de realizar uma conversão completa, testa o processo com um modelo ou dataset menor para identificar potenciais problemas precocemente.

Comunidade e Suporte#

Obtém ajuda e partilha soluções através destes canais e recursos.

Fóruns e Canais para Obter Ajuda#

Problemas no GitHub: O repositório do YOLO26 no GitHub tem uma Issues tab onde podes fazer perguntas, relatar bugs e sugerir novos recursos. A comunidade e os mantenedores são ativos aqui, e este é um ótimo lugar para obter ajuda com problemas específicos.

Servidor do Discord da Ultralytics: A Ultralytics tem um Discord server onde podes interagir com outros utilizadores e com os desenvolvedores.

Documentação Oficial e Recursos#

Documentação do Ultralytics YOLO26: A official documentation fornece uma visão geral abrangente do YOLO26, juntamente com guias sobre instalação, utilização e resolução de problemas.

Conclusão#

A maioria dos problemas do YOLO26 deve-se a um pequeno conjunto de causas: incompatibilidades de versões, formatação do conjunto de dados e configuração da GPU. Quando um erro não estiver aqui coberto, pesquisa no separador GitHub Issues ou pergunta no Discord server — é provável que alguém já o tenha resolvido. Para problemas mais complexos de training, consulta o guia Model Training Tips para obteres conselhos práticos sobre como alcançar melhores resultados nos teus projetos de computer vision.

FAQ#