Resolução de problemas comuns do YOLO#

Este guia aborda os problemas mais comuns que encontrarás ao trabalhar com o Ultralytics YOLO26, agrupados pelo ponto onde ocorrem: instalação, treino do modelo, predição e implementação. Salta para a categoria correspondente ao teu erro ou consulta as FAQ para obter respostas rápidas. Cada entrada descreve o problema e uma solução concreta que podes aplicar diretamente.

Problemas comuns#

Erros de instalação#

Os erros de instalação podem ocorrer por vários motivos, como versões incompatíveis, dependências em falta ou configurações incorretas do ambiente. Primeiro, verifica se estás a fazer o seguinte:

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

Além disso, seguem algumas 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 encontrares conflitos de dependências, experimenta estes passos:

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

Executar o YOLO26 numa GPU#

Se estiveres a ter problemas ao executar o YOLO26 numa GPU, considera os seguintes passos de resolução:

• Verifica a compatibilidade e a instalação do CUDA: Certifica-te de que a tua GPU é compatível com 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 do PyTorch com 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: Certifica-te de que estás no ambiente correto, onde todos os pacotes necessários estão instalados.
• Atualiza os teus pacotes: Os pacotes desatualizados podem não ser compatíveis com a tua GPU. Mantém-nos atualizados.
• Configuração do programa: Verifica se o teu código solicita a utilização da 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 no treino do modelo#

Os problemas comuns de treino e as respetivas soluções são apresentados abaixo.

Verificação das definições de configuração#

Problema: Não tens a certeza de que 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 usar 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 argumento data ao chamar model.train(), conforme mostrado abaixo:

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

Acelerar o treino com várias GPUs#

Problema: O treino está lento numa única GPU e queres acelerar o processo utilizando várias GPUs.

Solução: Aumentar o tamanho do batch pode acelerar o treino, mas é essencial considerar a capacidade de memória da GPU. Para acelerar o treino com várias GPUs, segue estes passos:

• Certifica-te de que tens várias GPUs disponíveis.

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

• Aumenta o tamanho do batch de forma correspondente para utilizar plenamente as várias GPUs sem exceder os limites de memória.

• Modifica o comando de treino para utilizar várias 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 quais os parâmetros que devem ser monitorizados continuamente durante o treino, além da loss.

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

• Precision
• Recall
• Média da precisão média (mAP)

Podes aceder a estas métricas a partir dos registos de treino ou utilizando ferramentas como o TensorBoard ou o Weights & Biases para visualização. A implementação de paragem antecipada com base nestas métricas pode ajudar-te a obter melhores resultados.

Ferramentas para acompanhar o progresso do treino#

Problema: Procuras recomendações de ferramentas para acompanhar o progresso do treino.

Solução: Para acompanhar e visualizar o progresso do treino, podes considerar utilizar as seguintes ferramentas:

• TensorBoard: O TensorBoard é uma opção popular para visualizar métricas de treino, incluindo loss, precisão e muito mais. Podes integrá-lo no teu processo de treino do YOLO26.
• Comet: O Comet fornece um conjunto abrangente de ferramentas para acompanhar e comparar experiências. Permite acompanhar métricas, hiperparâmetros e até os pesos do modelo. A integração com modelos YOLO também é simples, fornecendo-te uma visão completa do ciclo da tua experiência.
• Ultralytics Platform: A Ultralytics Platform oferece um ambiente especializado para acompanhar modelos YOLO, proporcionando uma plataforma centralizada para gerir métricas, conjuntos de dados e até colaborar com a tua equipa. Graças ao seu foco específico no YOLO, disponibiliza opções de acompanhamento mais personalizadas.

Como verificar se o treino está a decorrer na GPU#

Problema: O valor de 'device' nos registos de treino é 'null' e não tens a certeza de que o treino está a decorrer na GPU.

Solução: O valor 'device' ser 'null' normalmente significa 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. device é um argumento de treino, pelo que defini-lo no teu .yaml do conjunto de dados não tem 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)

Acompanha a pasta 'runs' para consultar registos e métricas e monitorizar eficazmente o progresso do treino.

Considerações importantes para um treino eficaz do modelo#

Eis alguns aspetos a ter em conta se estiveres a enfrentar problemas relacionados com o treino do modelo.

Formato e etiquetas do conjunto de dados

• Importância: A base de qualquer modelo de aprendizagem automática reside na qualidade e no formato dos dados com os quais é treinado.
• Recomendação: Certifica-te de que o teu conjunto de dados personalizado e as respetivas etiquetas seguem o formato esperado. É crucial verificar se as anotações são precisas e de alta qualidade. Anotações incorretas ou de qualidade insuficiente podem comprometer o processo de aprendizagem do modelo, conduzindo a resultados imprevisíveis.

Convergência do modelo

• Importância: Alcançar a convergência do modelo garante que este aprendeu suficientemente a partir dos dados de treino.
• Recomendação: Ao treinar um modelo 'from scratch', é essencial garantir que este atinge um nível de convergência satisfatório. Isto pode exigir uma duração de treino maior, com mais épocas, do que ao ajustar um modelo existente.

Taxa de aprendizagem e tamanho do batch

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

Distribuição das classes

• Importância: A distribuição das classes no teu conjunto de dados pode influenciar as tendências de predição do modelo.
• Recomendação: Avalia regularmente a distribuição das classes no teu conjunto de dados. Se existir um desequilíbrio entre classes, há o risco de o modelo desenvolver um viés em favor da classe mais prevalente. Este viés pode ser evidente na matriz de confusão, onde o modelo poderá prever predominantemente a classe maioritária.

Validaçã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 utilizando os mesmos dados, mas inicializando-o com pesos pré-treinados. Se esta abordagem produzir uma matriz de confusão bem formada, isso poderá sugerir que o modelo 'from scratch' necessita de mais treino ou de ajustes.

Problemas relacionados com as predições do modelo#

Os problemas comuns encontrados durante a predição do modelo e as respetivas soluções são apresentados abaixo.

Obter predições de caixas delimitadoras com o teu modelo YOLO26 personalizado#

Problema: Ao executar predições com um modelo YOLO26 personalizado, surgem dificuldades relacionadas com o formato e a visualização das coordenadas das caixas delimitadoras.

Solução:

• Formato das coordenadas: O YOLO26 fornece as coordenadas das caixas delimitadoras em valores absolutos de píxeis. Para as converter em coordenadas relativas (entre 0 e 1), tens de as dividir pelas dimensões da imagem. Por exemplo, supondo que o tamanho da tua imagem é 640x640, deves fazer 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 sobre a qual estás a fazer a predição, acede diretamente ao caminho do ficheiro de imagem a partir do objeto de resultado dentro do teu ciclo de predição.

Filtrar objetos nas predições do YOLO26#

Problema: Estás a ter problemas para filtrar e apresentar apenas objetos específicos nos resultados da predição ao executar o YOLO26 utilizando a biblioteca Ultralytics.

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

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

Compreender as métricas de precisão no YOLO26#

Problema: Existe confusão relativamente à diferença entre a precisão das caixas, a precisão das máscaras e a precisão da matriz de confusão no YOLO26.

Solução: A precisão das caixas mede a exatidão das caixas delimitadoras previstas em comparação com as caixas reais de ground truth, utilizando IoU (Interseção sobre União) como métrica. A precisão das máscaras avalia a concordância entre as máscaras de segmentação previstas e as máscaras de ground truth na classificação de objetos ao nível dos píxeis. Já a precisão da matriz de confusão centra-se na exatidão global da classificação em todas as classes e não considera a exatidão geométrica das predições. É importante notar que uma caixa delimitadora pode ser geometricamente precisa (verdadeiro positivo) mesmo que a predição da classe esteja errada, originando diferenças entre a precisão das caixas e a precisão da matriz de confusão. Estas métricas avaliam aspetos distintos do desempenho de um modelo, refletindo a necessidade de métricas de avaliação diferentes em várias tarefas.

Extrair dimensões de objetos no YOLO26#

Problema: Dificuldade em obter o comprimento e a altura dos objetos detetados no YOLO26, especialmente quando são detetados vários objetos numa imagem.

Solução: Para obter as dimensões das caixas delimitadoras, utiliza primeiro o modelo Ultralytics YOLO26 para prever objetos numa imagem. Em seguida, extrai as informações 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: A implementação de modelos num ambiente com várias GPUs pode, por vezes, provocar comportamentos inesperados, como utilização inesperada de memória, resultados inconsistentes entre GPUs, etc.

Solução: Verifica a inicialização predefinida da GPU. Algumas frameworks, como o PyTorch, podem inicializar operações CUDA numa GPU predefinida antes de transitarem para as GPUs designadas. Para evitar inicializações predefinidas inesperadas, especifica diretamente a GPU durante a implementação e a predição. Em seguida, utiliza ferramentas para monitorizar a utilização da GPU e da memória e identificar anomalias em tempo real. Além disso, certifica-te de que estás a utilizar a versão mais recente da framework ou biblioteca.

Problemas de conversão/exportação do modelo#

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

Solução: Consulta os formatos suportados e as opções específicas de cada formato na documentação do modo de exportação e, em seguida, executa estas verificações:

• Verificação de compatibilidade: Certifica-te de que estás a utilizar versões de bibliotecas e frameworks compatíveis entre si. Versões incompatíveis podem provocar erros inesperados durante a conversão.
• Reposição do ambiente: Se estiveres a utilizar um ambiente interativo, como Jupyter ou Colab, considera reiniciar o ambiente depois de efetuares alterações significativas ou instalações. Um novo início pode, por vezes, resolver problemas subjacentes.
• Documentação oficial: Consulta sempre a documentação oficial da ferramenta ou biblioteca que estás a utilizar para a conversão. Esta contém frequentemente orientações específicas e boas práticas para a exportação de modelos.
• Suporte da comunidade: Consulta o repositório oficial da biblioteca ou framework para verificar se existem problemas semelhantes comunicados por outros utilizadores. Os responsáveis pela manutenção ou a comunidade podem ter fornecido soluções ou alternativas em tópicos de discussão.
• Atualize regularmente: certifique-se de que está a utilizar a versão mais recente da ferramenta ou biblioteca. Os programadores lançam frequentemente atualizações que corrigem erros conhecidos ou melhoram a funcionalidade.
• Teste incrementalmente: antes de realizar uma conversão completa, teste o processo com um modelo ou conjunto de dados mais pequeno para identificar possíveis problemas antecipadamente.

Comunidade e suporte#

Obtenha ajuda e partilhe soluções através destes canais e recursos.

Fóruns e canais para obter ajuda#

GitHub Issues: O repositório da Ultralytics no GitHub tem uma aba Issues onde podes colocar perguntas, reportar bugs e sugerir novas funcionalidades. A comunidade e os mantenedores são ativos aqui, e é um excelente lugar para obteres ajuda com problemas específicos.

Servidor Discord da Ultralytics: A Ultralytics tem um servidor Discord onde podes interagir com outros utilizadores e com os programadores.

Documentação e recursos oficiais#

Documentação do Ultralytics YOLO26: A documentação oficial fornece uma visão 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 algumas causas principais: incompatibilidades de versões, formatação do conjunto de dados e configuração da GPU. Quando um erro não estiver abrangido aqui, pesquisa no separador GitHub Issues ou pergunta no servidor do Discord — é provável que alguém já o tenha resolvido. Para problemas mais complexos de treino, consulta o guia Dicas para o treino de modelos para obter conselhos práticos sobre como conseguir melhores resultados nos teus projetos de visão computacional.

Perguntas frequentes#