Solução de problemas comuns do YOLO#

Este guia aborda os problemas mais comuns que você pode encontrar ao trabalhar com o Ultralytics YOLO26, agrupados por etapa: instalação, treinamento do modelo, previsão e implantação. Vá para a categoria correspondente ao seu erro ou consulte as perguntas frequentes para obter respostas rápidas. Cada tópico descreve o problema e uma solução concreta que você pode aplicar diretamente.

Problemas comuns#

Erros de instalação#

Erros de instalação podem ocorrer por vários motivos, como versões incompatíveis, dependências ausentes ou configurações incorretas do ambiente. Primeiro, confira se você está fazendo o seguinte:

• Você está usando Python 3.8 ou posterior, conforme recomendado.
• Verifique se a versão correta do PyTorch (1.8 ou posterior) está instalada.
• Considere usar ambientes virtuais para evitar conflitos.
• Siga o guia oficial de instalação passo a passo.

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

Erros de importação ou problemas com dependências#

Se você receber erros ao importar o YOLO26 ou encontrar conflitos entre dependências, tente estas etapas:

• Instalação limpa: começar com uma instalação limpa pode resolver problemas inesperados, especialmente após atualizações que alteram a estrutura ou a funcionalidade do pacote.
• Atualize regularmente: use a versão mais recente da biblioteca, pois versões antigas podem não ser compatíveis com atualizações recentes.
• Verifique as dependências: confirme se todas as dependências necessárias estão instaladas corretamente e se as versões são compatíveis.
• Revise as alterações: se você instalou uma versão antiga, consulte a documentação oficial ou o changelog para entender as principais alterações estruturais.

Executar o YOLO26 na GPU#

Se você estiver com dificuldades para executar o YOLO26 em uma GPU, considere estas etapas de solução de problemas:

• Verifique a compatibilidade e a instalação do CUDA: confirme se sua GPU é compatível com CUDA e se o CUDA está instalado corretamente. Use o comando nvidia-smi para verificar o status da GPU NVIDIA e a versão do CUDA.
• Verifique a integração do PyTorch com o CUDA: confirme se o PyTorch consegue usar o CUDA executando import torch; print(torch.cuda.is_available()) em um terminal Python. Se o resultado for 'True', o PyTorch está configurado para usar o CUDA.
• Ativação do ambiente: confirme se você está no ambiente correto, onde todos os pacotes necessários estão instalados.
• Atualize seus pacotes: pacotes desatualizados podem não ser compatíveis com sua GPU. Mantenha-os atualizados.
• Configuração do programa: verifique se seu código solicita o uso da GPU. Você pode definir o argumento device ao executar o treinamento ou a previsã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 treinamento do modelo#

Veja abaixo os problemas comuns de treinamento e suas soluções.

Verificação das configurações#

Problema: você não tem certeza se as configurações no arquivo .yaml estão sendo aplicadas corretamente durante o treinamento do modelo.

Solução: as configurações do conjunto de dados e as configurações de treinamento ficam em arquivos .yaml diferentes e são passadas por argumentos diferentes de model.train(). Para garantir que essas configurações sejam aplicadas corretamente, siga estas etapas:

• Confirme se os caminhos para seus arquivos .yaml estão corretos.

• Passe o .yaml do seu conjunto de dados (caminhos, nomes de classes, divisões) como o argumento data e um .yaml personalizado para as configurações de treinamento (por exemplo, epochs ou lr0) como o argumento cfg. Os argumentos passados diretamente para model.train() têm prioridade sobre ambos:

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

Acelerar o treinamento com várias GPUs#

Problema: o treinamento está lento em uma única GPU, e você quer acelerar o processo usando várias GPUs.

Solução: aumentar o tamanho do lote pode acelerar o treinamento, mas é essencial considerar a capacidade de memória da GPU. Para acelerar o treinamento com várias GPUs, siga estas etapas:

• Confirme se você tem várias GPUs disponíveis.

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

• Aumente o tamanho do lote adequadamente para aproveitar ao máximo as várias GPUs sem exceder os limites de memória.

• Modifique o comando de treinamento para usar várias GPUs:

  # Ajuste o tamanho do lote e outras configurações conforme necessário para otimizar a velocidade do treinamento
  model.train(data="/path/to/your/data.yaml", batch=32, device=[0, 1, 2, 3])

Parâmetros para monitoramento contínuo#

Problema: você quer saber quais parâmetros devem ser monitorados continuamente durante o treinamento, além da perda.

Solução: embora a perda seja uma métrica crucial a monitorar, também é essencial acompanhar outras métricas para otimizar o desempenho do modelo. Algumas métricas importantes para acompanhar durante o treinamento incluem:

• Precisão
• Revocação
• Precisão média média (mAP)

Você pode acessar essas métricas nos registros de treinamento ou usar ferramentas como TensorBoard ou Weights & Biases para visualizá-las. Implementar a parada antecipada com base nessas métricas pode ajudar você a obter melhores resultados.

Ferramentas para acompanhar o progresso do treinamento#

Problema: você está procurando recomendações de ferramentas para acompanhar o progresso do treinamento.

Solução: para acompanhar e visualizar o progresso do treinamento, considere usar as seguintes ferramentas:

• TensorBoard: o TensorBoard é uma opção popular para visualizar métricas de treinamento, incluindo perda, acurácia e muito mais. Você pode integrá-lo ao processo de treinamento do YOLO26.
• Comet: o Comet oferece um amplo conjunto de ferramentas para acompanhar e comparar experimentos. Ele permite acompanhar métricas, hiperparâmetros e até pesos do modelo. A integração com modelos YOLO também é simples, oferecendo uma visão completa do ciclo do experimento.
• Plataforma Ultralytics: a Ultralytics Platform oferece um ambiente especializado para acompanhar modelos YOLO, reunindo em uma única plataforma o gerenciamento de métricas e conjuntos de dados, além da colaboração com sua equipe. Por ser focada em YOLO, oferece opções de acompanhamento mais personalizadas.

Como verificar se o treinamento está sendo executado na GPU#

Problema: o valor de 'device' nos registros de treinamento é 'null', e você não tem certeza se o treinamento está sendo executado na GPU.

Solução: o valor 'null' para 'device' geralmente significa que o processo de treinamento está configurado para selecionar automaticamente uma GPU disponível, que é o comportamento padrão. Para treinar em uma GPU específica, defina o argumento device ao iniciar o treinamento. device é um argumento de treinamento, portanto, defini-lo no .yaml do conjunto de dados não tem efeito:

from ultralytics import YOLO

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

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

Acompanhe a pasta 'runs' para consultar registros e métricas e monitorar o progresso do treinamento com eficiência.

Principais considerações para um treinamento eficaz do modelo#

Se você estiver enfrentando problemas relacionados ao treinamento do modelo, tenha em mente alguns pontos:

Formato do conjunto de dados e rótulos

• Importância: a base de qualquer modelo de aprendizado de máquina está na qualidade e no formato dos dados usados no treinamento.
• Recomendação: confirme se seu conjunto de dados personalizado e os rótulos associados seguem o formato esperado. É fundamental verificar se as anotações são precisas e de alta qualidade. Anotações incorretas ou de baixa qualidade podem prejudicar o aprendizado do modelo e levar a resultados imprevisíveis.

Convergência do modelo

• Importância: alcançar a convergência do modelo garante que ele tenha aprendido o suficiente com os dados de treinamento.
• Recomendação: ao treinar um modelo 'do zero', é fundamental garantir que ele alcance um nível satisfatório de convergência. Isso pode exigir um treinamento mais longo, com mais épocas, em comparação com o ajuste fino de um modelo existente.

Taxa de aprendizado e tamanho do lote

• Importância: esses hiperparâmetros desempenham um papel fundamental na determinação de como o modelo atualiza seus pesos durante o treinamento.
• Recomendação: avalie regularmente se a taxa de aprendizado e o tamanho do lote escolhidos são ideais para seu conjunto de dados específico. Parâmetros incompatíveis com as características do conjunto de dados podem prejudicar o desempenho do modelo.

Distribuição de classes

• Importância: a distribuição de classes no conjunto de dados pode influenciar as tendências de previsão do modelo.
• Recomendação: avalie regularmente a distribuição de classes no conjunto de dados. Se houver um desequilíbrio entre as classes, existe o risco de o modelo desenvolver um viés em favor da classe mais frequente. Esse viés pode ficar evidente na matriz de confusão, em que o modelo pode prever predominantemente a classe majoritária.

Verificação cruzada com pesos pré-treinados

• Importância: Aproveitar pesos pré-treinados pode proporcionar um ponto de partida sólido para o treinamento do modelo, especialmente quando há poucos dados.
• Recomendação: Como etapa de diagnóstico, considera treinar o teu modelo com os mesmos dados, mas inicializando-o com pesos pré-treinados. Se essa abordagem produzir uma matriz de confusão bem formada, isso pode indicar que o modelo treinado «do zero» precisa de mais treinamento ou ajustes.

Problemas relacionados com as previsões do modelo#

Abaixo, abordamos problemas comuns encontrados durante a previsão do modelo e as respetivas soluções.

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

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

Solução:

• Formato das coordenadas: 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 dividir pelas dimensões da imagem. Por exemplo, suponhamos que a imagem tem 640x640. Nesse caso, deves fazer o seguinte:

  # Converter coordenadas absolutas em coordenadas relativas
  x1 = x1 / 640  # Dividir as coordenadas x pela largura da imagem
  x2 = x2 / 640
  y1 = y1 / 640  # Dividir as coordenadas y pela altura da imagem
  y2 = y2 / 640

• Nome do ficheiro: Para obter o nome do ficheiro da imagem na qual estás a fazer previsões, lê o caminho do ficheiro de imagem do atributo path de cada objeto de resultado (por exemplo, result.path) dentro do ciclo de previsão.

Filtrar objetos nas previsões YOLO26#

Problema: Dificuldade em filtrar e apresentar apenas objetos específicos nos resultados da previsão ao executar YOLO26 com a biblioteca Ultralytics.

Solução: Para detetar classes específicas, usa o argumento classes para indicar as classes que queres incluir na saída. Por exemplo, para detetar apenas carros (supondo que «carros» têm 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 em YOLO26#

Problema: Dúvidas sobre a diferença entre a precisão das caixas, a precisão das máscaras e a precisão da matriz de confusão em YOLO26.

Solução: A precisão das caixas mede a exatidão das caixas delimitadoras previstas em comparação com as caixas de referência reais, usando 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 referência na classificação de objetos ao nível dos píxeis. Por outro lado, a precisão da matriz de confusão centra-se na exatidão geral da classificação em todas as classes e não considera a exatidão geométrica das previsões. É importante notar que uma caixa delimitadora pode ser geometricamente exata (verdadeiro positivo), mesmo que a previsão da classe esteja errada, o que leva a 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 para várias tarefas.

Extrair as dimensões dos objetos em YOLO26#

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

Solução: Para obter as dimensões das caixas delimitadoras, começa por usar o modelo Ultralytics YOLO26 para prever objetos numa imagem. Em seguida, extrai as informações de largura e altura das caixas delimitadoras dos resultados da previsã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 GPU pode, por vezes, causar comportamentos inesperados, como utilização de memória imprevista, resultados inconsistentes entre GPU, etc.

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

Problemas de conversão/exportação de modelos#

Problema: Durante a 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 de cada formato na documentação do modo Export e, em seguida, verifica o seguinte:

• Verificação de compatibilidade: Certifica-te de que estás a usar versões de bibliotecas e frameworks compatíveis entre si. Versões incompatíveis podem causar erros inesperados durante a conversão.
• Reinicialização do ambiente: Se estiveres a usar um ambiente interativo como Jupyter ou Colab, considera reiniciar o ambiente depois de fazer alterações importantes ou instalar componentes. Recomeçar do zero 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. Muitas vezes, contém diretrizes específicas e boas práticas para exportar modelos.
• Apoio da comunidade: Consulta o repositório oficial da biblioteca ou framework para ver se outros utilizadores relataram problemas semelhantes. Os responsáveis pela manutenção ou a comunidade podem ter apresentado soluções ou alternativas nos tópicos de discussão.
• Atualizações regulares: Certifica-te de que estás a usar a versão mais recente da ferramenta ou biblioteca. Os programadores lançam atualizações frequentemente para corrigir erros conhecidos ou melhorar as funcionalidades.
• Testes incrementais: Antes de fazer uma conversão completa, testa o processo com um modelo ou conjunto de dados menor para identificar possíveis problemas com antecedência.

Comunidade e apoio#

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

Fóruns e canais de ajuda#

Problemas no GitHub: O repositório da Ultralytics no GitHub tem uma guia Issues, onde você pode fazer perguntas, relatar bugs e sugerir novos recursos. A comunidade e os responsáveis pela manutenção são ativos por lá, e esse é um ótimo lugar para obter ajuda com problemas específicos.

Servidor Discord da Ultralytics: A Ultralytics tem um servidor Discord onde você pode interagir com outros usuários e desenvolvedores.

Documentação e recursos oficiais#

Documentação Ultralytics YOLO26: A documentação oficial apresenta uma visão abrangente de YOLO26, bem como guias de instalação, utilização e resolução de problemas.

Conclusão#

A maioria dos problemas com YOLO26 deve-se a algumas causas comuns: incompatibilidades de versões, formatação do conjunto de dados e configuração da GPU. Se não encontrares aqui a resposta para um erro, pesquisa no separador Issues do GitHub ou pergunta no servidor Discord — é provável que alguém já o tenha resolvido. Para problemas mais complexos de treinamento, consulta o guia Dicas de treinamento de modelos para obter conselhos práticos sobre como conseguir melhores resultados nos teus projetos de visão computacional.

Perguntas frequentes#