Ir para o conteúdo

Instalar o Ultralytics

A Ultralytics oferece uma variedade de métodos de instalação, incluindo pip, conda e Docker. Você pode instalar o YOLO através do ultralytics pacote pip para a versão estável mais recente, ou clonando o repositório Ultralytics GitHub para a versão mais atual. O Docker também é uma opção para executar o pacote em um contêiner isolado, o que evita a instalação local.



Assista: Guia de Início Rápido do Ultralytics YOLO

Instalar

PyPI - Versão do Python

Instale ou atualize o ultralytics package usando pip executando pip install -U ultralytics. Para mais detalhes sobre o ultralytics package, visite o Índice de Pacotes Python (PyPI).

PyPI - Versão Downloads

# Install the ultralytics package from PyPI
pip install ultralytics

Também pode instalar ultralytics diretamente do repositório Ultralytics GitHub. Isso pode ser útil se você quiser a versão de desenvolvimento mais recente. Certifique-se de ter a ferramenta de linha de comando Git instalada e execute:

# Install the ultralytics package from GitHub
pip install git+https://github.com/ultralytics/ultralytics.git@main

O Conda pode ser usado como um gerenciador de pacotes alternativo ao pip. Para mais detalhes, visite Anaconda. O repositório de feedstock da Ultralytics para atualizar o pacote conda está disponível em GitHub.

Versão do Conda Downloads do Conda Receita do Conda Plataformas Conda

# Install the ultralytics package using conda
conda install -c conda-forge ultralytics

Nota

Se você estiver instalando em um ambiente CUDA, é uma boa prática instalar ultralytics, pytorch, e pytorch-cuda no mesmo comando. Isso permite que o gerenciador de pacotes conda resolva quaisquer conflitos. Alternativamente, instale pytorch-cuda último a substituir o específico da CPU pytorch pacote específico da CPU, se necessário.

# Install all packages together using conda
conda install -c pytorch -c nvidia -c conda-forge pytorch torchvision pytorch-cuda=11.8 ultralytics

Imagem Docker do Conda

As imagens Ultralytics Conda Docker também estão disponíveis no DockerHub. Essas imagens são baseadas no Miniconda3 e fornecem uma maneira direta de começar a usar ultralytics em um ambiente Conda.

# Set image name as a variable
t=ultralytics/ultralytics:latest-conda

# Pull the latest ultralytics image from Docker Hub
sudo docker pull $t

# Run the ultralytics image in a container with GPU support
sudo docker run -it --ipc=host --gpus all $t            # all GPUs
sudo docker run -it --ipc=host --gpus '"device=2,3"' $t # specify GPUs

Clone o repositório Ultralytics GitHub se você estiver interessado em contribuir para o desenvolvimento ou desejar experimentar o código-fonte mais recente. Após a clonagem, navegue até o diretório e instale o pacote no modo editável -e usando pip.

Último commit do GitHub Atividade de commit do GitHub

# Clone the ultralytics repository
git clone https://github.com/ultralytics/ultralytics

# Navigate to the cloned directory
cd ultralytics

# Install the package in editable mode for development
pip install -e .

Use o Docker para executar o ultralytics package em um contêiner isolado, garantindo um desempenho consistente em vários ambientes. Ao selecionar um dos ultralytics imagens de Docker Hub, você evita a complexidade da instalação local e obtém acesso a um ambiente de trabalho verificado. A Ultralytics oferece cinco imagens Docker principais suportadas, cada uma projetada para alta compatibilidade e eficiência:

Versão da Imagem Docker Puxadas do Docker

  • Dockerfile: Imagem de GPU recomendada para treinamento.
  • Dockerfile-arm64: Otimizado para arquitetura ARM64, adequado para implantação em dispositivos como Raspberry Pi e outras plataformas baseadas em ARM64.
  • Dockerfile-cpu: Versão baseada em Ubuntu somente para CPU, adequada para inferência e ambientes sem GPUs.
  • Dockerfile-jetson: Projetado para dispositivos NVIDIA Jetson, integrando suporte a GPU otimizado para essas plataformas.
  • Dockerfile-python: Imagem mínima com apenas python e dependências necessárias, ideal para aplicações leves e desenvolvimento.
  • Dockerfile-conda: Baseado no Miniconda3 com uma instalação conda do ultralytics package.

Aqui estão os comandos para obter a imagem mais recente e executá-la:

# Set image name as a variable
t=ultralytics/ultralytics:latest

# Pull the latest ultralytics image from Docker Hub
sudo docker pull $t

# Run the ultralytics image in a container with GPU support
sudo docker run -it --ipc=host --gpus all $t            # all GPUs
sudo docker run -it --ipc=host --gpus '"device=2,3"' $t # specify GPUs

O comando acima inicializa um contêiner Docker com a versão mais recente da ultralytics imagem. A flag -it flags atribuem um pseudo-TTY e mantêm o stdin aberto, permitindo a interação com o contêiner. O --ipc=host define o namespace IPC (Inter-Process Communication) para o host, o que é essencial para compartilhar memória entre processos. A flag --gpus all flag permite o acesso a todas as GPUs disponíveis dentro do contêiner, crucial para tarefas que exigem computação de GPU.

Observação: Para trabalhar com arquivos em sua máquina local dentro do contêiner, use volumes Docker para montar um diretório local no contêiner:

# Mount local directory to a directory inside the container
sudo docker run -it --ipc=host --gpus all -v /path/on/host:/path/in/container $t

Substitua /path/on/host com o caminho do diretório em sua máquina local e /path/in/container pelo caminho desejado dentro do contêiner Docker.

Para uso avançado do Docker, explore o Guia do Docker da Ultralytics.

Veja o arquivo ultralytics pyproject.toml para obter uma lista de dependências. Observe que todos os exemplos acima instalam todas as dependências necessárias.

Dica

Os requisitos do PyTorch variam de acordo com o sistema operacional e os requisitos do CUDA, portanto, instale o PyTorch primeiro seguindo as instruções em PyTorch.

Instruções de Instalação do PyTorch

Métodos de Instalação Personalizados

Embora os métodos de instalação padrão cubram a maioria dos casos de uso, você pode precisar de uma configuração mais personalizada. Isso pode envolver a instalação de versões de pacotes específicos, a omissão de dependências opcionais ou a substituição de pacotes como a substituição de opencv-python com o sem GUI opencv-python-headless para ambientes de servidor.

Métodos Personalizados

Você pode instalar o ultralytics pacote core sem quaisquer dependências usando o pip --no-deps flag. Isso exige que você instale manualmente todas as dependências necessárias posteriormente.

  1. Instalar ultralytics core:

    pip install ultralytics --no-deps
    

  2. Instale as dependências manualmente: Você precisa instalar todos os pacotes necessários listados no pyproject.toml arquivo, substituindo ou modificando versões conforme necessário. Para o exemplo OpenCV headless:

    # Install other core dependencies
    pip install torch torchvision numpy matplotlib polars pyyaml pillow psutil requests scipy seaborn ultralytics-thop
    
    # Install headless OpenCV instead of the default
    pip install opencv-python-headless
    

Gestão de Dependências

Este método oferece controle total, mas requer gerenciamento cuidadoso das dependências. Garanta que todos os pacotes necessários estejam instalados com versões compatíveis, consultando o ultralytics pyproject.toml ficheiro.

Se você precisar de modificações personalizadas persistentes (como usar sempre opencv-python-headless), você pode fazer um fork do repositório Ultralytics, fazer alterações em pyproject.toml ou outro código, e instale a partir do seu fork.

  1. Faça um fork do repositório Ultralytics no GitHub para sua própria conta do GitHub.
  2. Clone seu fork localmente:
    git clone https://github.com/YOUR_USERNAME/ultralytics.git
    cd ultralytics
    
  3. Criar um novo branch para as suas alterações:
    git checkout -b custom-opencv
    
  4. Modificar pyproject.toml: Abrir pyproject.toml em um editor de texto e substitua a linha que contém "opencv-python>=4.6.0" com "opencv-python-headless>=4.6.0" (ajuste a versão conforme necessário).
  5. Commit e push suas alterações:
    git add pyproject.toml
    git commit -m "Switch to opencv-python-headless"
    git push origin custom-opencv
    
  6. Instalar usando pip com o git+https sintaxe, apontando para sua branch:
    pip install git+https://github.com/YOUR_USERNAME/ultralytics.git@custom-opencv
    

Este método garante que seu conjunto de dependências personalizado seja usado sempre que você instalar a partir deste URL específico. Consulte o Método 4 para usar isso em um requirements.txt ficheiro.

Semelhante ao método padrão "Git Clone" para desenvolvimento, você pode clonar o repositório localmente, modificar os arquivos de dependência antes da instalação e, em seguida, instalar no modo editável.

  1. Clone o repositório Ultralytics:
    git clone https://github.com/ultralytics/ultralytics
    cd ultralytics
    
  2. Modificar pyproject.toml: Edite o arquivo para fazer as alterações desejadas. Por exemplo, use sed (no Linux/macOS) ou um editor de texto para substituir opencv-python com opencv-python-headless. Usando sed (verifique a linha exata em pyproject.toml primeiro):
    # Example: Replace the line starting with "opencv-python..."
    # Adapt the pattern carefully based on the current file content
    sed -i'' -e 's/^\s*"opencv-python>=.*",/"opencv-python-headless>=4.8.0",/' pyproject.toml
    
    Ou edite manualmente pyproject.toml para alterar "opencv-python>=... para "opencv-python-headless>=...".
  3. Instalar o pacote em modo editável (-e). O Pip agora usará seu pyproject.toml para resolver e instalar as dependências:
    pip install -e .
    

Esta abordagem é útil para testar alterações locais nas dependências ou configurações de construção antes de commitá-las ou para configurar ambientes de desenvolvimento específicos.

Se você gerencia as dependências do seu projeto usando um requirements.txt arquivo, você pode especificar seu fork Ultralytics personalizado diretamente nele. Isso garante que qualquer pessoa que configurar o projeto obtenha sua versão específica com suas dependências modificadas (como opencv-python-headless).

  1. Criar ou editar requirements.txt: Adicione uma linha apontando para o seu fork e branch personalizados (conforme preparado no Método 2).
    requirements.txt
    # Core dependencies
    numpy
    matplotlib
    polars
    pyyaml
    Pillow
    psutil
    requests>=2.23.0
    torch>=1.8.0 # Or specific version/variant
    torchvision>=0.9.0 # Or specific version/variant
    
    # Install ultralytics from a specific git commit or branch
    # Replace YOUR_USERNAME and custom-branch with your details
    git+https://github.com/YOUR_USERNAME/ultralytics.git@custom-branch
    
    # Other project dependencies
    flask
    # ... etc
    
    Nota: Não precisa de listar as dependências já exigidas pelo seu personalizado ultralytics fork (como opencv-python-headless) aqui, pois o pip os instalará com base no fork pyproject.toml.
  2. Instalar dependências do ficheiro:
    pip install -r requirements.txt
    

Este método integra-se perfeitamente com os fluxos de trabalho padrão de gerenciamento de dependências de projetos Python, ao mesmo tempo que permite fixar ultralytics para a sua fonte Git personalizada.

Usar o Ultralytics com CLI

A interface de linha de comando (CLI) Ultralytics permite comandos simples de linha única sem a necessidade de um ambiente Python. A CLI não requer personalização ou código Python; execute todas as tarefas a partir do terminal com o yolo comando. Para mais informações sobre como usar o YOLO a partir da linha de comando, consulte a Guia da CLI.

Exemplo

Ultralytics yolo comandos usam a seguinte sintaxe:

yolo TASK MODE ARGS
- TASK (opcional) é um de (detect, segment, classify, pose, obb) - MODE (obrigatório) é um de (train, val, predict, export, track, benchmark) - ARGS (opcional) são arg=value pares como imgsz=640 que substituem os padrões.

Veja todos os ARGS no completo Guia de Configuração ou com o yolo cfg comando da CLI.

Treine um modelo de detecção por 10 épocas com uma taxa de aprendizado inicial de 0,01:

yolo train data=coco8.yaml model=yolo11n.pt epochs=10 lr0=0.01

Preveja um vídeo do YouTube usando um modelo de segmentação pré-treinado no tamanho de imagem 320:

yolo predict model=yolo11n-seg.pt source='https://youtu.be/LNwODJXcvt4' imgsz=320

Validar um modelo de detecção pré-treinado com um tamanho de lote de 1 e tamanho de imagem de 640:

yolo val model=yolo11n.pt data=coco8.yaml batch=1 imgsz=640

Exporte um modelo de classificação YOLOv11n para o formato ONNX com um tamanho de imagem de 224x128 (sem necessidade de TASK):

yolo export model=yolo11n-cls.pt format=onnx imgsz=224,128

Contar objetos em um vídeo ou transmissão ao vivo usando YOLO11:

yolo solutions count show=True

yolo solutions count source="path/to/video.mp4" # specify video file path

Monitore os exercícios de treino usando um modelo de pose YOLO11:

yolo solutions workout show=True

yolo solutions workout source="path/to/video.mp4" # specify video file path

# Use keypoints for ab-workouts
yolo solutions workout kpts="[5, 11, 13]" # left side
yolo solutions workout kpts="[6, 12, 14]" # right side

Use o YOLO11 para contar objetos em uma fila ou região designada:

yolo solutions queue show=True

yolo solutions queue source="path/to/video.mp4" # specify video file path

yolo solutions queue region="[(20, 400), (1080, 400), (1080, 360), (20, 360)]" # configure queue coordinates

Realize detecção de objetos, segmentação de instâncias ou estimativa de pose em um navegador da web usando Streamlit:

yolo solutions inference

yolo solutions inference model="path/to/model.pt" # use model fine-tuned with Ultralytics Python package

Execute comandos especiais para ver a versão, visualizar as configurações, executar verificações e muito mais:

yolo help
yolo checks
yolo version
yolo settings
yolo copy-cfg
yolo cfg
yolo solutions help

Aviso

Os argumentos devem ser passados como arg=value pares, separados por um sinal de igual = sinal e delimitado por espaços. Não use -- prefixos de argumentos ou vírgulas , entre os argumentos.

  • yolo predict model=yolo11n.pt imgsz=640 conf=0.25
  • yolo predict model yolo11n.pt imgsz 640 conf 0.25 ❌ (ausente =)
  • yolo predict model=yolo11n.pt, imgsz=640, conf=0.25 ❌ (não use ,)
  • yolo predict --model yolo11n.pt --imgsz 640 --conf 0.25 ❌ (não use --)
  • yolo solution model=yolo11n.pt imgsz=640 conf=0.25 ❌ (use solutions, não solution)

Guia da CLI

Usar o Ultralytics com Python

A interface Python do Ultralytics YOLO oferece integração perfeita em projetos Python, facilitando o carregamento, a execução e o processamento das saídas do modelo. Projetada para a simplicidade, a interface Python permite que os usuários implementem rapidamente detecção de objetos, segmentação e classificação. Isso torna a interface Python do YOLO uma ferramenta inestimável para incorporar essas funcionalidades em projetos Python.

Por exemplo, os usuários podem carregar um modelo, treiná-lo, avaliar seu desempenho e exportá-lo para o formato ONNX com apenas algumas linhas de código. Explore o Guia Python para saber mais sobre como usar o YOLO em seus projetos Python.

Exemplo

from ultralytics import YOLO

# Create a new YOLO model from scratch
model = YOLO("yolo11n.yaml")

# Load a pretrained YOLO model (recommended for training)
model = YOLO("yolo11n.pt")

# Train the model using the 'coco8.yaml' dataset for 3 epochs
results = model.train(data="coco8.yaml", epochs=3)

# Evaluate the model's performance on the validation set
results = model.val()

# Perform object detection on an image using the model
results = model("https://ultralytics.com/images/bus.jpg")

# Export the model to ONNX format
success = model.export(format="onnx")

Guia Python

Configurações do Ultralytics

A biblioteca Ultralytics inclui um SettingsManager para um controlo preciso sobre as experiências, permitindo aos utilizadores aceder e modificar as configurações facilmente. Armazenadas num ficheiro JSON dentro do diretório de configuração do utilizador do ambiente, estas configurações podem ser visualizadas ou modificadas no ambiente Python ou através da Command-Line Interface (CLI).

Inspecionando as Configurações

Para visualizar a configuração atual de suas configurações:

Visualizar configurações

Use o python para visualizar suas configurações importando o settings objeto do ultralytics módulo. Imprima e retorne as configurações com estes comandos:

from ultralytics import settings

# View all settings
print(settings)

# Return a specific setting
value = settings["runs_dir"]

A interface de linha de comando permite que você verifique suas configurações com:

yolo settings

Modificando as Configurações

A Ultralytics facilita a modificação de configurações das seguintes maneiras:

Atualizar configurações

Em Python, use o update no objeto settings objeto:

from ultralytics import settings

# Update a setting
settings.update({"runs_dir": "/path/to/runs"})

# Update multiple settings
settings.update({"runs_dir": "/path/to/runs", "tensorboard": False})

# Reset settings to default values
settings.reset()

Para modificar as configurações usando a interface de linha de comando:

# Update a setting
yolo settings runs_dir='/path/to/runs'

# Update multiple settings
yolo settings runs_dir='/path/to/runs' tensorboard=False

# Reset settings to default values
yolo settings reset

Entendendo as Configurações

A tabela abaixo apresenta as configurações ajustáveis dentro do Ultralytics, incluindo valores de exemplo, tipos de dados e descrições.

Nome Valor de Exemplo Tipo de Dado Descrição
settings_version '0.0.4' str Versão das configurações Ultralytics (distinta da versão pip da Ultralytics)
datasets_dir '/path/to/datasets' str Diretório onde os conjuntos de dados são armazenados
weights_dir '/path/to/weights' str Diretório onde os pesos do modelo são armazenados
runs_dir '/path/to/runs' str Diretório onde as execuções de experimentos são armazenadas
uuid 'a1b2c3d4' str Identificador único para as configurações atuais
sync True bool Opção para sincronizar análises e falhas com o Ultralytics HUB
api_key '' str Chave de API do Ultralytics HUB
clearml True bool Opção para usar o registro ClearML
comet True bool Opção para usar o Comet ML para rastreamento e visualização de experimentos
dvc True bool Opção para usar o DVC para rastreamento de experimentos e controle de versão
hub True bool Opção para usar a integração do Ultralytics HUB
mlflow True bool Opção para usar o MLFlow para rastreamento de experimentos
neptune True bool Opção para usar o Neptune para rastreamento de experimentos
raytune True bool Opção para usar o Ray Tune para ajuste de hiperparâmetros
tensorboard True bool Opção para usar o TensorBoard para visualização
wandb True bool Opção para usar o registro Weights & Biases
vscode_msg True bool Quando um terminal VS Code é detectado, habilita um prompt para baixar a extensão Ultralytics-Snippets.

Revisite estas configurações à medida que avança nos projetos ou experimentos para garantir uma configuração ideal.

FAQ

Como instalo o Ultralytics usando pip?

Instale o Ultralytics com o pip usando:

pip install ultralytics

Isto instala a versão estável mais recente do ultralytics pacote de PyPI. Para instalar a versão de desenvolvimento diretamente do GitHub:

pip install git+https://github.com/ultralytics/ultralytics.git

Certifique-se de que a ferramenta de linha de comando Git esteja instalada em seu sistema.

Posso instalar o Ultralytics YOLO usando o conda?

Sim, instale o Ultralytics YOLO usando conda com:

conda install -c conda-forge ultralytics

Este método é uma ótima alternativa ao pip, garantindo a compatibilidade com outros pacotes. Para ambientes CUDA, instale ultralytics, pytorch, e pytorch-cuda juntos para resolver conflitos:

conda install -c pytorch -c nvidia -c conda-forge pytorch torchvision pytorch-cuda=11.8 ultralytics

Para obter mais instruções, consulte o guia de início rápido do Conda.

Quais são as vantagens de usar o Docker para executar o Ultralytics YOLO?

O Docker fornece um ambiente isolado e consistente para Ultralytics YOLO, garantindo um desempenho suave entre os sistemas e evitando complexidades de instalação local. As imagens oficiais do Docker estão disponíveis no Docker Hub, com variantes para GPU, CPU, ARM64, NVIDIA Jetson e Conda. Para extrair e executar a imagem mais recente:

# Pull the latest ultralytics image from Docker Hub
sudo docker pull ultralytics/ultralytics:latest

# Run the ultralytics image in a container with GPU support
sudo docker run -it --ipc=host --gpus all ultralytics/ultralytics:latest

Para instruções detalhadas do Docker, consulte o guia de início rápido do Docker.

Como faço para clonar o repositório Ultralytics para desenvolvimento?

Clone o repositório Ultralytics e configure um ambiente de desenvolvimento com:

# Clone the ultralytics repository
git clone https://github.com/ultralytics/ultralytics

# Navigate to the cloned directory
cd ultralytics

# Install the package in editable mode for development
pip install -e .

Isso permite contribuições para o projeto ou experimentação com o código-fonte mais recente. Para detalhes, visite o repositório Ultralytics no GitHub.

Por que devo usar a CLI Ultralytics YOLO?

A Ultralytics YOLO CLI simplifica a execução de tarefas de detecção de objetos sem código Python, permitindo comandos de linha única para treinamento, validação e previsão diretamente do seu terminal. A sintaxe básica é:

yolo TASK MODE ARGS

Por exemplo, para treinar um modelo de detecção:

yolo train data=coco8.yaml model=yolo11n.pt epochs=10 lr0=0.01

Explore mais comandos e exemplos de uso no Guia da CLI completo.



📅 Criado há 1 ano ✏️ Atualizado há 5 dias

Comentários