Treine seu primeiro modelo YOLO·Configuração·Aula 1/10

Aulainiciante

Instalar o Ultralytics

Instale o Ultralytics em um ambiente limpo, leia o relatório de verificações do yolo para confirmar seu dispositivo e comprove a configuração com uma previsão.

Uma execução de treinamento que recua silenciosamente para a CPU pode levar um dia em vez de uma hora, e você só vai perceber quando for tarde demais. Uma instalação com problemas se manifesta da mesma forma: no meio de uma aula, como um erro de importação ou uma GPU ausente.

Dez minutos aqui evitam os dois problemas. Você instalará o pacote ultralytics em um ambiente novo, lerá o relatório yolo checks linha por linha e executará uma primeira previsão do YOLO26 para comprovar que tudo está conectado.

Resultado

Você consegue instalar o Ultralytics em um ambiente limpo e descobrir, por uma única linha de yolo checks, se ele será executado com CUDA, MPS ou CPU.

Via rápida

Se já sabes orientar-te, aqui está a versão resumida.

Crie e ative um ambiente virtual novo com Python 3.10 ou mais recente.
Em uma máquina NVIDIA, instale primeiro o PyTorch com CUDA; depois, pip install ultralytics.
Execute yolo checks e leia o dispositivo no final da primeira linha.
Execute yolo predict model=yolo26n.pt source=https://ultralytics.com/images/bus.jpg e abra a imagem salva.

Prático

Criar um ambiente limpo#

O pacote ultralytics é instalado no Python 3.8 ou mais recente, mas as versões atuais do PyTorch exigem Python 3.10 ou mais recente; por isso, comece novos projetos com uma versão atual, como a 3.12. Um ambiente virtual novo mantém o pacote e suas dependências separados dos outros projetos:

python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
python --version                 # 3.10 or newer

O guia de início rápido do Ultralytics aborda a mesma configuração com Conda ou Docker, caso prefira essas opções.

Instale a versão certa do PyTorch e, depois, o Ultralytics#

Seletor "Começar localmente" do PyTorch, com seleção do sistema operacional, gerenciador de pacotes, linguagem e plataforma computacional para gerar o comando pip install correspondente

O Ultralytics é executado no PyTorch, e o pip instala uma versão padrão do PyTorch se nenhuma estiver presente. Essa versão padrão é a principal causa dos problemas do tipo "por que está usando minha CPU?", então escolha a versão primeiro:

Sua máquina	Faça isto primeiro	Depois
GPU NVIDIA	Instale a versão com CUDA correspondente ao seu driver usando o seletor do PyTorch	`pip install ultralytics` cuida disso
Mac com Apple Silicon	Nada: a versão padrão inclui MPS	`pip install ultralytics`
Somente CPU	Nada	`pip install ultralytics`

pip install ultralytics

Esse único comando instala o pacote Python ultralytics, a ferramenta de linha de comando yolo e dependências como OpenCV e NumPy.

Leia o relatório `yolo checks`#

yolo checks exibe as versões e o hardware que o Ultralytics usará. Saída real de um MacBook, resumida:

Ultralytics 8.4.175 🚀 Python-3.12.12 torch-2.14.1 CPU (Apple M5 Pro)
Setup complete ✅ (18 CPUs, 48.0 GB RAM, 594.4/926.3 GB disk)

OS                     macOS-27.0.1-arm64-arm-64bit
Python                 3.12.12
Install                pip
GPU                    None

Linha por linha:

Ultralytics 8.4.175 ... torch-2.14.1: as versões do pacote e do PyTorch. Informe-as em qualquer relatório de bug.
CPU (Apple M5 Pro): o dispositivo usado quando você não informa device. Esta é a linha importante.
Setup complete ✅: a instalação está funcionando corretamente.
GPU None: o PyTorch não detecta nenhuma GPU CUDA. É esperado em um Mac; é um problema em uma máquina NVIDIA.

Aja de acordo com o dispositivo indicado na linha 1:

Você não precisa de uma GPU para este curso: todos os exemplos são dimensionados para terminar em poucos minutos em uma CPU de laptop. Uma GPU faz diferença quando você treina em tamanho total, sendo muitas vezes 10× mais rápida ou mais.

Comprove com uma previsão#

Uma previsão testa toda a pilha: baixa os pesos nano do YOLO26, busca uma imagem, executa o modelo e grava uma cópia anotada.

yolo predict model=yolo26n.pt source=https://ultralytics.com/images/bus.jpg

image 1/1 bus.jpg: 640x480 4 persons, 1 bus, 20.1ms
Speed: 0.7ms preprocess, 20.1ms inference, 0.5ms postprocess per image at shape (1, 3, 640, 480)
Results saved to runs/detect/predict

640x480 4 persons, 1 bus: a imagem foi redimensionada para 640×480 para o modelo, que encontrou cinco objetos.
20.1ms: tempo de inferência nesta CPU. Anote o seu; será sua primeira referência de velocidade.
runs/detect/predict: onde foi salvo o bus.jpg anotado. Execute o comando novamente e você obterá predict-2: o Ultralytics nunca substitui uma execução anterior.

Todos os valores padrão desse comando — confiança, tamanho da imagem e local para salvar — estão listados na referência de configuração.

Corrija os problemas comuns#

Treinamento silencioso na CPU

Sintoma: yolo checks mostra CPU e GPU None em uma máquina com GPU NVIDIA, e o treinamento é dolorosamente lento. Causa: o pip instalou uma versão do PyTorch apenas para CPU. Solução: desinstale torch e torchvision, instale a versão com CUDA no seletor do PyTorch e execute novamente yolo checks até que a primeira linha mostre CUDA:0.

yolo: comando não encontrado

Causa: o ambiente virtual não está ativo neste terminal, então o script yolo não está no seu PATH. Solução: execute source .venv/bin/activate (ou o equivalente no Windows) em cada novo terminal antes de usar yolo.

Sintoma	Causa	Solução
`requirements: ... not found, attempting AutoUpdate` e depois `No module named pip`	Ambiente criado sem pip, então o Ultralytics não consegue instalar automaticamente um pacote adicional	Instale o pacote indicado com a ferramenta do seu ambiente, por exemplo, `uv pip install lap`
O download dos pesos ou do conjunto de dados expira	A rede bloqueia os recursos de lançamento do GitHub	Baixe `yolo26n.pt` uma vez em outro local e informe o caminho local
`PermissionError` gravando `runs/`	O diretório de trabalho é somente leitura	`cd` em uma pasta de projeto com permissão de gravação

Para qualquer outro problema, o guia de problemas comuns reúne soluções conhecidas, e os issues encerrados no repositório do Ultralytics geralmente contêm a resposta — pesquise neles antes de abrir um novo.

Experimente

Em um ambiente novo, instale o Ultralytics, execute yolo checks e faça a previsão do ônibus. Entregue um registro de configuração de três linhas: suas versões do Ultralytics e do PyTorch, o dispositivo indicado na primeira linha de yolo checks (e, em uma máquina NVIDIA, a confirmação de que aparece CUDA:0) e o tempo de inferência informado para bus.jpg.

Concluído quando

Você concluiu a aula quando todos estes critérios forem atendidos.

yolo checks termina com Setup complete ✅ e indica o dispositivo esperado.
runs/detect/predict/bus.jpg existe, com quatro pessoas e um ônibus delimitados por caixas.
Você anotou suas versões, o dispositivo e o tempo de inferência de bus.jpg.

Mostrar solução

python -m venv .venv
source .venv/bin/activate
# NVIDIA only: install the CUDA PyTorch build from pytorch.org first
pip install ultralytics
yolo checks
yolo predict model=yolo26n.pt source=https://ultralytics.com/images/bus.jpg

Versions: Ultralytics 8.4.175, torch 2.14.1
Device:   CPU (Apple M5 Pro); use device=mps for the Apple GPU
bus.jpg:  20.1 ms inference at 640x480

Em uma CPU de laptop, espere cerca de 10–60 ms para bus.jpg; em uma GPU NVIDIA recente, alguns milissegundos. Se yolo checks indicar o dispositivo errado, corrija o PyTorch antes de prosseguir.

Próximos passos

O ambiente está a funcionar. A seguir, executa a mesma previsão em Python e aprende a interpretar todos os campos devolvidos pelo modelo.

Entre para salvar seu progresso

Get Started