Installa Ultralytics
Ultralytics offre una varietà di metodi di installazione, tra cui pip, conda e Docker. Puoi installare YOLO tramite ultralytics
pacchetto pip per l'ultima release stabile, oppure clonando il repository GitHub di Ultralytics per la versione più recente. Docker è anche un'opzione per eseguire il pacchetto in un container isolato, il che evita l'installazione locale.
Guarda: Guida rapida di Ultralytics YOLO
Installa
Installa o aggiorna il ultralytics
package usando pip eseguendo pip install -U ultralytics
. Per maggiori dettagli sul ultralytics
package, visita il Python Package Index (PyPI).
# Install the ultralytics package from PyPI
pip install ultralytics
È anche possibile installare ultralytics
direttamente dalla repository GitHub di Ultralytics. Questo può essere utile se desideri l'ultima versione di sviluppo. Assicurati di avere lo strumento da riga di comando Git installato, quindi esegui:
# Install the ultralytics package from GitHub
pip install git+https://github.com/ultralytics/ultralytics.git@main
Conda può essere utilizzato come gestore di pacchetti alternativo a pip. Per maggiori dettagli, visita Anaconda. Il repository di feedstock di Ultralytics per l'aggiornamento del pacchetto conda è disponibile su GitHub.
# Install the ultralytics package using conda
conda install -c conda-forge ultralytics
Nota
Se stai eseguendo l'installazione in un ambiente CUDA, è consigliabile installare ultralytics
, pytorch
, e pytorch-cuda
nello stesso comando. Ciò consente al gestore di pacchetti conda di risolvere eventuali conflitti. In alternativa, installa pytorch-cuda
ultimo per sovrascrivere quello specifico della CPU pytorch
specifico per la CPU, se necessario.
# Install all packages together using conda
conda install -c pytorch -c nvidia -c conda-forge pytorch torchvision pytorch-cuda=11.8 ultralytics
Immagine Docker Conda
Le immagini Docker di Ultralytics Conda sono disponibili anche da DockerHub. Queste immagini sono basate su Miniconda3 e forniscono un modo semplice per iniziare a utilizzare ultralytics
in un 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
Clona il repository repository GitHub di Ultralytics se sei interessato a contribuire allo sviluppo o desideri sperimentare con il codice sorgente più recente. Dopo aver clonato, accedi alla directory e installa il pacchetto in modalità modificabile -e
utilizzando pip.
# 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 .
Utilizza Docker per eseguire il ultralytics
package in un container isolato, garantendo prestazioni coerenti in vari ambienti. Selezionando uno degli ufficiali ultralytics
da Docker Hub, si evita la complessità dell'installazione locale e si ottiene l'accesso a un ambiente di lavoro verificato. Ultralytics offre cinque immagini Docker principali supportate, ciascuna progettata per un'elevata compatibilità ed efficienza:
- Dockerfile: Immagine GPU consigliata per l'addestramento.
- Dockerfile-arm64: Ottimizzato per l'architettura ARM64, adatto per la distribuzione su dispositivi come Raspberry Pi e altre piattaforme basate su ARM64.
- Dockerfile-cpu: Versione basata su Ubuntu solo CPU, adatta per l'inferenza e ambienti senza GPU.
- Dockerfile-jetson: Realizzato su misura per i dispositivi NVIDIA Jetson, integrando il supporto GPU ottimizzato per queste piattaforme.
- Dockerfile-python: Immagine minima con solo python e le dipendenze necessarie, ideale per applicazioni leggere e sviluppo.
- Dockerfile-conda: Basato su Miniconda3 con un'installazione conda di
ultralytics
package.
Ecco i comandi per ottenere l'immagine più recente ed eseguirla:
# 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
Il comando sopra riportato inizializza un container Docker con l'ultima ultralytics
immagine. Il flag -it
flags assegnano uno pseudo-TTY e mantengono aperto stdin, consentendo l'interazione con il container. Il --ipc=host
imposta il namespace IPC (Inter-Process Communication) sull'host, essenziale per la condivisione della memoria tra i processi. Il flag --gpus all
flag abilita l'accesso a tutte le GPU disponibili all'interno del container, fondamentale per le attività che richiedono calcolo tramite GPU.
Nota: Per lavorare con i file sulla tua macchina locale all'interno del container, usa i volumi Docker per montare una directory locale nel container:
# 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
Sostituisci /path/on/host
con il percorso della directory sulla macchina locale e /path/in/container
con il percorso desiderato all'interno del container Docker.
Per un utilizzo avanzato di Docker, esplora la Guida a Docker di Ultralytics.
Vedere il file ultralytics
pyproject.toml per un elenco delle dipendenze. Si noti che tutti gli esempi precedenti installano tutte le dipendenze richieste.
Suggerimento
I requisiti di PyTorch variano in base al sistema operativo e ai requisiti CUDA, quindi installa prima PyTorch seguendo le istruzioni su PyTorch.
Metodi di installazione personalizzati
Sebbene i metodi di installazione standard coprano la maggior parte dei casi d'uso, potrebbe essere necessaria una configurazione più personalizzata. Ciò potrebbe comportare l'installazione di versioni specifiche dei pacchetti, l'omissione di dipendenze opzionali o la sostituzione di pacchetti come la sostituzione di opencv-python
con l'interfaccia senza GUI opencv-python-headless
per ambienti server.
Metodi personalizzati
Puoi installare il ultralytics
pacchetto core senza dipendenze utilizzando pip --no-deps
flag. Questo richiede l'installazione manuale di tutte le dipendenze necessarie in seguito.
-
Installa
ultralytics
core:pip install ultralytics --no-deps
-
Installa manualmente le dipendenze: Devi installare tutti i pacchetti richiesti elencati nel
pyproject.toml
file, sostituendo o modificando le versioni secondo necessità. Per l'esempio di 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
Gestione delle dipendenze
Questo metodo offre il pieno controllo, ma richiede un'attenta gestione delle dipendenze. Assicurati che tutti i pacchetti richiesti siano installati con versioni compatibili facendo riferimento al ultralytics
pyproject.toml
file.
Se hai bisogno di modifiche personalizzate persistenti (come usare sempre opencv-python-headless
), puoi creare un fork del repository Ultralytics, apportare modifiche a pyproject.toml
o altro codice, e installa dal tuo fork.
- Fork del repository GitHub di Ultralytics sul tuo account GitHub.
- Clona il tuo fork localmente:
git clone https://github.com/YOUR_USERNAME/ultralytics.git cd ultralytics
- Crea un nuovo ramo per le tue modifiche:
git checkout -b custom-opencv
- Modifica
pyproject.toml
: Apripyproject.toml
in un editor di testo e sostituisci la riga contenente"opencv-python>=4.6.0"
con"opencv-python-headless>=4.6.0"
(modificare la versione in base alle esigenze). - Commit e push le tue modifiche:
git add pyproject.toml git commit -m "Switch to opencv-python-headless" git push origin custom-opencv
- Installa utilizzando pip con il
git+https
sintassi, che punta al tuo branch:pip install git+https://github.com/YOUR_USERNAME/ultralytics.git@custom-opencv
Questo metodo garantisce che il tuo set di dipendenze personalizzato venga utilizzato ogni volta che installi da questo URL specifico. Vedi il Metodo 4 per l'utilizzo in un requirements.txt
file.
Simile al metodo standard "Git Clone" per lo sviluppo, puoi clonare il repository localmente, modificare i file di dipendenza prima dell'installazione e quindi installare in modalità modificabile.
- Clona il repository Ultralytics:
git clone https://github.com/ultralytics/ultralytics cd ultralytics
- Modifica
pyproject.toml
: Modifica il file per apportare le modifiche desiderate. Ad esempio, usased
(su Linux/macOS) o un editor di testo per sostituireopencv-python
conopencv-python-headless
. L'utilizzo dised
(verify the exact line inpyproject.toml
primo):Oppure modifica manualmente# 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
pyproject.toml
per modificare"opencv-python>=...
a"opencv-python-headless>=..."
. - Installa il pacchetto in modalità modificabile (
-e
). Pip utilizzerà ora il file modificato.pyproject.toml
per risolvere e installare le dipendenze:pip install -e .
Questo approccio è utile per testare le modifiche locali alle dipendenze o alle configurazioni di build prima di eseguirne il commit o per impostare ambienti di sviluppo specifici.
Se gestisci le dipendenze del tuo progetto utilizzando un requirements.txt
file, puoi specificare il tuo fork personalizzato di Ultralytics direttamente al suo interno. Ciò garantisce che chiunque configuri il progetto ottenga la tua versione specifica con le sue dipendenze modificate (come opencv-python-headless
).
- Crea o modifica
requirements.txt
: Aggiungi una riga che punta al tuo fork e branch personalizzati (come preparato nel Metodo 2).requirements.txtNota: non è necessario elencare le dipendenze già richieste dal tuo custom# 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
ultralytics
fork (comeopencv-python-headless
) qui, dato che pip li installerà in base al forkpyproject.toml
. - Installa dipendenze dal file:
pip install -r requirements.txt
Questo metodo si integra perfettamente con i flussi di lavoro standard di gestione delle dipendenze dei progetti Python, consentendoti al contempo di fissare ultralytics
alla tua sorgente Git personalizzata.
Usa Ultralytics con la CLI
L'interfaccia a riga di comando (CLI) di Ultralytics consente semplici comandi a riga singola senza la necessità di un ambiente Python. La CLI non richiede personalizzazioni o codice Python; esegui tutte le attività dal terminale con il yolo
comando. Per maggiori informazioni sull'utilizzo di YOLO dalla riga di comando, consultare la Guida CLI.
Esempio
Ultralytics yolo
i comandi utilizzano la seguente sintassi:
yolo TASK MODE ARGS
TASK
(opzionale) è uno di (detect, segmentazione, classificazione, pose, obb)
- MODE
(obbligatorio) è uno tra (train, val, predict, export, track, benchmark)
- ARGS
(opzionali) sono arg=value
coppie come imgsz=640
che sovrascrivono le impostazioni predefinite.
Vedi tutti i ARGS
nel completo Guida alla Configurazione o con il comando yolo cfg
CLI.
Addestra un modello di rilevamento per 10 epoche con un tasso di apprendimento iniziale di 0.01:
yolo train data=coco8.yaml model=yolo11n.pt epochs=10 lr0=0.01
Esegui una prediction su un video di YouTube utilizzando un modello di segmentazione pre-addestrato con una dimensione dell'immagine di 320:
yolo predict model=yolo11n-seg.pt source='https://youtu.be/LNwODJXcvt4' imgsz=320
Convalida di un modello di rilevamento pre-addestrato con una dimensione del batch di 1 e una dimensione dell'immagine di 640:
yolo val model=yolo11n.pt data=coco8.yaml batch=1 imgsz=640
Esporta un modello di classificazione YOLOv11n in formato ONNX con una dimensione dell'immagine di 224x128 (nessuna TASK richiesta):
yolo export model=yolo11n-cls.pt format=onnx imgsz=224,128
Conta gli oggetti in un video o in uno streaming live utilizzando YOLO11:
yolo solutions count show=True
yolo solutions count source="path/to/video.mp4" # specify video file path
Monitorare gli esercizi di allenamento utilizzando un modello di posa 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
Utilizza YOLO11 per contare gli oggetti in una coda o regione designata:
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
Esegui il rilevamento di oggetti, la segmentazione di istanze o la stima della posa in un browser web utilizzando Streamlit:
yolo solutions inference
yolo solutions inference model="path/to/model.pt" # use model fine-tuned with Ultralytics Python package
Esegui comandi speciali per visualizzare la versione, le impostazioni, eseguire controlli e altro:
yolo help
yolo checks
yolo version
yolo settings
yolo copy-cfg
yolo cfg
yolo solutions help
Attenzione
Gli argomenti devono essere passati come arg=value
coppie, separate da un segno di uguale =
segno e delimitato da spazi. Non utilizzare --
o virgole per gli argomenti ,
tra gli argomenti.
yolo predict model=yolo11n.pt imgsz=640 conf=0.25
✅yolo predict model yolo11n.pt imgsz 640 conf 0.25
❌ (mancante=
)yolo predict model=yolo11n.pt, imgsz=640, conf=0.25
❌ (non usare,
)yolo predict --model yolo11n.pt --imgsz 640 --conf 0.25
❌ (non usare--
)yolo solution model=yolo11n.pt imgsz=640 conf=0.25
❌ (usasolutions
, nonsolution
)
Usa Ultralytics con Python
L'interfaccia Python di YOLO di Ultralytics offre una perfetta integrazione nei progetti Python, semplificando il caricamento, l'esecuzione e l'elaborazione degli output del modello. Progettata per la semplicità, l'interfaccia Python consente agli utenti di implementare rapidamente object detection, segmentation e classification. Questo rende l'interfaccia Python di YOLO uno strumento prezioso per incorporare queste funzionalità nei progetti Python.
Ad esempio, gli utenti possono caricare un modello, addestrarlo, valutarne le prestazioni ed esportarlo in formato ONNX con poche righe di codice. Consulta la Guida Python per saperne di più sull'utilizzo di YOLO all'interno dei tuoi progetti Python.
Esempio
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")
Impostazioni di Ultralytics
La libreria Ultralytics include un SettingsManager
per un controllo preciso sugli esperimenti, consentendo agli utenti di accedere e modificare facilmente le impostazioni. Memorizzate in un file JSON all'interno della directory di configurazione utente dell'ambiente, queste impostazioni possono essere visualizzate o modificate nell'ambiente Python o tramite l'interfaccia a riga di comando (CLI).
Ispezione delle impostazioni
Per visualizzare la configurazione corrente delle impostazioni:
Visualizza impostazioni
Utilizza python per visualizzare le tue impostazioni importando il settings
oggetto dal ultralytics
modulo. Stampa e restituisci le impostazioni con questi comandi:
from ultralytics import settings
# View all settings
print(settings)
# Return a specific setting
value = settings["runs_dir"]
L'interfaccia a riga di comando consente di verificare le impostazioni con:
yolo settings
Modifica delle impostazioni
Ultralytics semplifica la modifica delle impostazioni nei seguenti modi:
Aggiorna impostazioni
In Python, usa il update
metodo sull'oggetto settings
object:
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()
Per modificare le impostazioni usando l'interfaccia a riga di 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
Comprensione delle impostazioni
La tabella seguente fornisce una panoramica delle impostazioni regolabili all'interno di Ultralytics, inclusi valori di esempio, tipi di dati e descrizioni.
Nome | Valore di esempio | Tipo di dati | Descrizione |
---|---|---|---|
settings_version |
'0.0.4' |
str |
Versione delle impostazioni di Ultralytics (distinta dalla versione pip di Ultralytics) |
datasets_dir |
'/path/to/datasets' |
str |
Directory in cui sono memorizzati i dataset |
weights_dir |
'/path/to/weights' |
str |
Directory in cui vengono salvati i pesi del modello |
runs_dir |
'/path/to/runs' |
str |
Directory in cui vengono salvate le esecuzioni degli esperimenti |
uuid |
'a1b2c3d4' |
str |
Identificatore univoco per le impostazioni correnti |
sync |
True |
bool |
Opzione per sincronizzare analisi e arresti anomali con Ultralytics HUB |
api_key |
'' |
str |
Chiave API Ultralytics HUB |
clearml |
True |
bool |
Opzione per utilizzare il logging di ClearML |
comet |
True |
bool |
Opzione per utilizzare Comet ML per il tracciamento e la visualizzazione degli esperimenti |
dvc |
True |
bool |
Opzione per utilizzare DVC per il tracciamento degli esperimenti e il controllo della versione |
hub |
True |
bool |
Opzione per utilizzare l'integrazione con Ultralytics HUB |
mlflow |
True |
bool |
Opzione per utilizzare MLFlow per il tracciamento degli esperimenti |
neptune |
True |
bool |
Opzione per utilizzare Neptune per il tracciamento degli esperimenti |
raytune |
True |
bool |
Opzione per utilizzare Ray Tune per la regolazione degli iperparametri |
tensorboard |
True |
bool |
Opzione per utilizzare TensorBoard per la visualizzazione |
wandb |
True |
bool |
Opzione per utilizzare il logging di Weights & Biases |
vscode_msg |
True |
bool |
Quando viene rilevato un terminale VS Code, abilita un prompt per scaricare l'estensione Ultralytics-Snippets. |
Rivedi queste impostazioni man mano che avanzi nei progetti o negli esperimenti per garantire una configurazione ottimale.
FAQ
Come posso installare Ultralytics usando pip?
Installa Ultralytics con pip usando:
pip install ultralytics
Questo installa l'ultima versione stabile del ultralytics
pacchetto da PyPI. Per installare la versione di sviluppo direttamente da GitHub:
pip install git+https://github.com/ultralytics/ultralytics.git
Assicurati che lo strumento da riga di comando Git sia installato sul tuo sistema.
Posso installare Ultralytics YOLO usando conda?
Sì, installa Ultralytics YOLO usando conda con:
conda install -c conda-forge ultralytics
Questo metodo è un'ottima alternativa a pip, garantendo la compatibilità con altri pacchetti. Per gli ambienti CUDA, installa ultralytics
, pytorch
, e pytorch-cuda
insieme per risolvere i conflitti:
conda install -c pytorch -c nvidia -c conda-forge pytorch torchvision pytorch-cuda=11.8 ultralytics
Per maggiori istruzioni, consultare la guida rapida di Conda.
Quali sono i vantaggi dell'utilizzo di Docker per eseguire Ultralytics YOLO?
Docker fornisce un ambiente isolato e coerente per Ultralytics YOLO, garantendo prestazioni fluide tra i sistemi ed evitando complessità di installazione locale. Le immagini Docker ufficiali sono disponibili su Docker Hub, con varianti per GPU, CPU, ARM64, NVIDIA Jetson e Conda. Per scaricare ed eseguire l'immagine più 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
Per istruzioni dettagliate su Docker, consulta la guida rapida di Docker.
Come posso clonare il repository Ultralytics per lo sviluppo?
Clona il repository Ultralytics e configura un ambiente di sviluppo con:
# 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 .
Ciò consente di contribuire al progetto o di sperimentare con il codice sorgente più recente. Per i dettagli, visitare il repository GitHub di Ultralytics.
Perché dovrei usare la CLI di Ultralytics YOLO?
La CLI YOLO di Ultralytics semplifica l'esecuzione di attività di object detection senza codice Python, consentendo comandi a riga singola per training, convalida e previsione direttamente dal tuo terminale. La sintassi di base è:
yolo TASK MODE ARGS
Ad esempio, per addestrare un modello di rilevamento:
yolo train data=coco8.yaml model=yolo11n.pt epochs=10 lr0=0.01
Esplora altri comandi ed esempi di utilizzo nella Guida CLI completa.