Instalar Ultralytics
Ultralytics ofrece una variedad de métodos de instalación, incluyendo pip, conda y Docker. Puedes instalar YOLO a través de ultralytics
paquete pip para la última versión estable, o clonando el repositorio de Ultralytics en GitHub para la versión más actual. Docker es también una opción para ejecutar el paquete en un contenedor aislado, lo que evita la instalación local.
Ver: Guía de inicio rápido de Ultralytics YOLO
Instalar
Instala o actualiza el ultralytics
paquete usando pip ejecutando pip install -U ultralytics
. Para obtener más detalles sobre el ultralytics
paquete, visita el Índice de paquetes de Python (PyPI).
# Install the ultralytics package from PyPI
pip install ultralytics
También puede instalar ultralytics
directamente desde el repositorio de Ultralytics en GitHub. Esto puede ser útil si desea la última versión de desarrollo. Asegúrese de tener instalada la herramienta de línea de comandos Git y, a continuación, ejecute:
# Install the ultralytics package from GitHub
pip install git+https://github.com/ultralytics/ultralytics.git@main
Conda puede utilizarse como un gestor de paquetes alternativo a pip. Para obtener más información, visite Anaconda. El repositorio de fuentes de Ultralytics para actualizar el paquete conda está disponible en GitHub.
# Install the ultralytics package using conda
conda install -c conda-forge ultralytics
Nota
Si está instalando en un entorno CUDA, es una buena práctica instalar ultralytics
, pytorch
, y pytorch-cuda
en el mismo comando. Esto permite que el administrador de paquetes conda resuelva cualquier conflicto. Alternativamente, instale pytorch-cuda
último para anular el específico de la CPU pytorch
paquete específico de la CPU si es necesario.
# Install all packages together using conda
conda install -c pytorch -c nvidia -c conda-forge pytorch torchvision pytorch-cuda=11.8 ultralytics
Imagen Docker de Conda
Las imágenes de Docker de Ultralytics Conda también están disponibles en DockerHub. Estas imágenes se basan en Miniconda3 y proporciona una forma sencilla de empezar a usar ultralytics
en un entorno 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 el repositorio de Ultralytics en GitHub si le interesa contribuir al desarrollo o desea experimentar con el código fuente más reciente. Después de clonar, navegue al directorio e instale el paquete en modo editable -e
usando 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 .
Utilice Docker para ejecutar el ultralytics
paquete en un contenedor aislado, lo que garantiza un rendimiento constante en diversos entornos. Al seleccionar uno de los ultralytics
de Docker Hub, evita la complejidad de la instalación local y obtiene acceso a un entorno de trabajo verificado. Ultralytics ofrece cinco imágenes Docker principales soportadas, cada una diseñada para una alta compatibilidad y eficiencia:
- Dockerfile: Imagen GPU recomendada para el entrenamiento.
- Dockerfile-arm64: Optimizado para la arquitectura ARM64, adecuado para la implementación en dispositivos como Raspberry Pi y otras plataformas basadas en ARM64.
- Dockerfile-cpu: Versión basada en Ubuntu solo para CPU, adecuada para inferencia y entornos sin GPUs.
- Dockerfile-jetson: Diseñado para dispositivos NVIDIA Jetson, integrando soporte de GPU optimizado para estas plataformas.
- Dockerfile-python: Imagen mínima solo con Python y las dependencias necesarias, ideal para aplicaciones ligeras y desarrollo.
- Dockerfile-conda: Basado en Miniconda3 con una instalación de conda del
ultralytics
paquete.
Aquí están los comandos para obtener la última imagen y ejecutarla:
# 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
El comando anterior inicializa un contenedor Docker con la última imagen ultralytics
. El indicador -it
Las flags asignan un pseudo-TTY y mantienen stdin abierto, permitiendo la interacción con el contenedor. El --ipc=host
establece el espacio de nombres IPC (Inter-Process Communication) en el host, lo cual es esencial para compartir memoria entre procesos. El indicador --gpus all
La flag permite el acceso a todas las GPUs disponibles dentro del contenedor, crucial para tareas que requieren computación mediante GPU.
Nota: Para trabajar con archivos en tu máquina local dentro del contenedor, utiliza volúmenes de Docker para montar un directorio local en el contenedor:
# 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
Reemplaza /path/on/host
con la ruta del directorio en tu máquina local, y /path/in/container
con la ruta deseada dentro del contenedor Docker.
Para un uso avanzado de Docker, explora la Guía de Docker de Ultralytics.
Consulte la ultralytics
pyproject.toml para obtener una lista de dependencias. Ten en cuenta que todos los ejemplos anteriores instalan todas las dependencias necesarias.
Consejo
Los requisitos de PyTorch varían según el sistema operativo y los requisitos de CUDA, así que instale PyTorch primero siguiendo las instrucciones en PyTorch.
Métodos de instalación personalizados
Si bien los métodos de instalación estándar cubren la mayoría de los casos de uso, es posible que necesite una configuración más personalizada. Esto podría implicar la instalación de versiones de paquetes específicos, la omisión de dependencias opcionales o la sustitución de paquetes, como la sustitución de opencv-python
sin la GUI opencv-python-headless
para entornos de servidor.
Métodos personalizados
Puede instalar el ultralytics
paquete core sin dependencias utilizando pip --no-deps
indicador. Esto requiere que instale manualmente todas las dependencias necesarias posteriormente.
-
Instalar
ultralytics
núcleo:pip install ultralytics --no-deps
-
Instale las dependencias manualmente: Debes instalar todos los paquetes requeridos que se enumeran en el
pyproject.toml
archivo, sustituyendo o modificando las versiones según sea necesario. Para el ejemplo de OpenCV sin interfaz gráfica:# 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
Gestión de dependencias
Este método brinda control total, pero requiere una gestión cuidadosa de las dependencias. Asegúrate de que todos los paquetes requeridos estén instalados con versiones compatibles haciendo referencia al ultralytics
pyproject.toml
archivo.
Si necesitas modificaciones personalizadas persistentes (como usar siempre opencv-python-headless
), puede bifurcar el repositorio de Ultralytics, realizar cambios en pyproject.toml
u otro código, e instala desde tu fork.
- Haz un fork del repositorio de Ultralytics en GitHub a tu propia cuenta de GitHub.
- Clonar tu bifurcación localmente:
git clone https://github.com/YOUR_USERNAME/ultralytics.git cd ultralytics
- Crear una nueva rama para tus cambios:
git checkout -b custom-opencv
- Modificar
pyproject.toml
: Abrirpyproject.toml
en un editor de texto y reemplaza la línea que contiene"opencv-python>=4.6.0"
con"opencv-python-headless>=4.6.0"
(ajusta la versión según sea necesario). - Confirmar y enviar tus cambios:
git add pyproject.toml git commit -m "Switch to opencv-python-headless" git push origin custom-opencv
- Instalar usando pip con el
git+https
sintaxis, apuntando a su branch:pip install git+https://github.com/YOUR_USERNAME/ultralytics.git@custom-opencv
Este método asegura que tu conjunto de dependencias personalizado se utilice siempre que instales desde esta URL específica. Consulta el Método 4 para usar esto en un requirements.txt
archivo.
De forma similar al método estándar "Git Clone" para el desarrollo, puedes clonar el repositorio localmente, modificar los archivos de dependencia antes de la instalación y, a continuación, instalar en modo editable.
- Clonar el repositorio de Ultralytics:
git clone https://github.com/ultralytics/ultralytics cd ultralytics
- Modificar
pyproject.toml
: Edita el archivo para realizar los cambios deseados. Por ejemplo, usased
(en Linux/macOS) o un editor de texto para reemplazaropencv-python
conopencv-python-headless
. Usandosed
(verifica la línea exacta enpyproject.toml
primero):O editar 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
para cambiar"opencv-python>=...
a datos"opencv-python-headless>=..."
. - Instalar el paquete en modo editable (
-e
). Pip ahora usará supyproject.toml
para resolver e instalar las dependencias:pip install -e .
Este enfoque es útil para probar cambios locales en las dependencias o configuraciones de compilación antes de confirmarlos o para configurar entornos de desarrollo específicos.
Si gestionas las dependencias de tu proyecto utilizando un requirements.txt
archivo, puede especificar su bifurcación personalizada de Ultralytics directamente dentro de él. Esto asegura que cualquiera que configure el proyecto obtenga su versión específica con sus dependencias modificadas (como opencv-python-headless
).
- Crear o editar
requirements.txt
: Añade una línea que apunte a tu fork y branch personalizados (como se preparó en el Método 2).requirements.txtNota: No es necesario enumerar las dependencias que ya requiere su# 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
bifurcación (comoopencv-python-headless
) aquí, ya que pip los instalará basándose en el forkpyproject.toml
. - Instalar dependencias del archivo:
pip install -r requirements.txt
Este método se integra perfectamente con los flujos de trabajo estándar de gestión de dependencias de proyectos de python, al tiempo que te permite fijar ultralytics
a su fuente Git personalizada.
Usar Ultralytics con CLI
La interfaz de línea de comandos (CLI) de Ultralytics permite comandos simples de una sola línea sin necesidad de un entorno de Python. La CLI no requiere personalización ni código de Python; ejecute todas las tareas desde la terminal con el yolo
comando. Para obtener más información sobre el uso de YOLO desde la línea de comandos, consulte la Guía de la CLI.
Ejemplo
Ultralytics yolo
los comandos utilizan la siguiente sintaxis:
yolo TASK MODE ARGS
TASK
(opcional) es uno de (detect, segment, classify, pose, obb)
- MODE
(obligatorio) es uno de (train, val, predict, export, track, benchmark)
- ARGS
(opcional) son arg=value
pares como imgsz=640
que anulan los valores predeterminados.
Ver todo ARGS
en la guía completa de Configuración o con el comando yolo cfg
de la CLI.
Entrena un modelo de detección durante 10 épocas con una tasa de aprendizaje inicial de 0.01:
yolo train data=coco8.yaml model=yolo11n.pt epochs=10 lr0=0.01
Predice un video de YouTube utilizando un modelo de segmentación preentrenado con un tamaño de imagen de 320:
yolo predict model=yolo11n-seg.pt source='https://youtu.be/LNwODJXcvt4' imgsz=320
Validar un modelo de detección preentrenado con un tamaño de lote de 1 y un tamaño de imagen de 640:
yolo val model=yolo11n.pt data=coco8.yaml batch=1 imgsz=640
Exporte un modelo de clasificación YOLOv11n al formato ONNX con un tamaño de imagen de 224x128 (no se requiere TASK):
yolo export model=yolo11n-cls.pt format=onnx imgsz=224,128
Contar objetos en un vídeo o transmisión en vivo usando YOLO11:
yolo solutions count show=True
yolo solutions count source="path/to/video.mp4" # specify video file path
Supervisar los ejercicios de entrenamiento utilizando un 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
Utilice YOLO11 para contar objetos en una cola o región 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
Realice detección de objetos, segmentación de instancias o estimación de poses en un navegador web utilizando Streamlit:
yolo solutions inference
yolo solutions inference model="path/to/model.pt" # use model fine-tuned with Ultralytics Python package
Ejecute comandos especiales para ver la versión, la configuración de la vista, ejecute comprobaciones y más:
yolo help
yolo checks
yolo version
yolo settings
yolo copy-cfg
yolo cfg
yolo solutions help
Advertencia
Los argumentos deben pasarse como arg=value
pares, divididos por un signo =
signo y delimitado por espacios. No usar --
prefijos de argumentos o comas ,
entre argumentos.
yolo predict model=yolo11n.pt imgsz=640 conf=0.25
✅yolo predict model yolo11n.pt imgsz 640 conf 0.25
❌ (faltan=
)yolo predict model=yolo11n.pt, imgsz=640, conf=0.25
❌ (no uses,
)yolo predict --model yolo11n.pt --imgsz 640 --conf 0.25
❌ (no uses--
)yolo solution model=yolo11n.pt imgsz=640 conf=0.25
❌ (usarsolutions
, nosolution
)
Usar Ultralytics con Python
La interfaz de python de Ultralytics YOLO ofrece una integración perfecta en proyectos de python, lo que facilita la carga, ejecución y procesamiento de salidas de modelos. Diseñada para la simplicidad, la interfaz de python permite a los usuarios implementar rápidamente detección de objetos, segmentación y clasificación. Esto convierte a la interfaz de python de YOLO en una herramienta invaluable para incorporar estas funcionalidades en proyectos de python.
Por ejemplo, los usuarios pueden cargar un modelo, entrenarlo, evaluar su rendimiento y exportarlo a formato ONNX con tan solo unas líneas de código. Explora la Guía de Python para obtener más información sobre el uso de YOLO dentro de tus proyectos de Python.
Ejemplo
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")
Ajustes de Ultralytics
La librería Ultralytics incluye un SettingsManager
para un control preciso sobre los experimentos, permitiendo a los usuarios acceder y modificar los ajustes fácilmente. Almacenados en un archivo JSON dentro del directorio de configuración de usuario del entorno, estos ajustes pueden ser vistos o modificados en el entorno de python o a través de la interfaz de línea de comandos (CLI).
Inspección de ajustes
Para ver la configuración actual de sus ajustes:
Ver ajustes
Utilice python para ver su configuración importando el settings
objeto del ultralytics
módulo. Imprime y devuelve la configuración con estos comandos:
from ultralytics import settings
# View all settings
print(settings)
# Return a specific setting
value = settings["runs_dir"]
La interfaz de línea de comandos le permite verificar su configuración con:
yolo settings
Modificación de ajustes
Ultralytics facilita la modificación de la configuración de las siguientes maneras:
Actualizar ajustes
En Python, use el update
método en el 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 la configuración mediante la interfaz de línea de comandos:
# 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
Comprensión de ajustes
La siguiente tabla ofrece una visión general de los ajustes configurables dentro de Ultralytics, incluyendo valores de ejemplo, tipos de datos y descripciones.
Nombre | Valor de ejemplo | Tipo de datos | Descripción |
---|---|---|---|
settings_version |
'0.0.4' |
str |
Versión de la configuración de Ultralytics (distinta de la versión pip de Ultralytics) |
datasets_dir |
'/path/to/datasets' |
str |
Directorio donde se almacenan los conjuntos de datos |
weights_dir |
'/path/to/weights' |
str |
Directorio donde se almacenan los pesos del modelo |
runs_dir |
'/path/to/runs' |
str |
Directorio donde se almacenan las ejecuciones de experimentos |
uuid |
'a1b2c3d4' |
str |
Identificador único para la configuración actual |
sync |
True |
bool |
Opción para sincronizar análisis y fallos con Ultralytics HUB |
api_key |
'' |
str |
Clave API de Ultralytics HUB |
clearml |
True |
bool |
Opción para usar el registro de ClearML |
comet |
True |
bool |
Opción para usar Comet ML para el seguimiento y la visualización de experimentos |
dvc |
True |
bool |
Opción de usar DVC para el seguimiento de experimentos y el control de versiones |
hub |
True |
bool |
Opción de usar la integración de Ultralytics HUB |
mlflow |
True |
bool |
Opción de usar MLFlow para el seguimiento de experimentos |
neptune |
True |
bool |
Opción de usar Neptune para el seguimiento de experimentos |
raytune |
True |
bool |
Opción de usar Ray Tune para el ajuste de hiperparámetros |
tensorboard |
True |
bool |
Opción de usar TensorBoard para la visualización |
wandb |
True |
bool |
Opción de usar el registro de Weights & Biases |
vscode_msg |
True |
bool |
Cuando se detecta una terminal de VS Code, se activa un aviso para descargar la extensión Ultralytics-Snippets. |
Revise estos ajustes a medida que avance en los proyectos o experimentos para asegurar una configuración óptima.
Preguntas frecuentes
¿Cómo instalo Ultralytics usando pip?
Instala Ultralytics con pip usando:
pip install ultralytics
Esto instala la última versión estable de ultralytics
paquete desde PyPI. Para instalar la versión de desarrollo directamente desde GitHub:
pip install git+https://github.com/ultralytics/ultralytics.git
Asegúrate de que la herramienta de línea de comandos Git esté instalada en tu sistema.
¿Puedo instalar Ultralytics YOLO usando conda?
Sí, instala Ultralytics YOLO usando conda con:
conda install -c conda-forge ultralytics
Este método es una excelente alternativa a pip, lo que garantiza la compatibilidad con otros paquetes. Para entornos CUDA, instale ultralytics
, pytorch
, y pytorch-cuda
juntos para resolver conflictos:
conda install -c pytorch -c nvidia -c conda-forge pytorch torchvision pytorch-cuda=11.8 ultralytics
Para obtener más instrucciones, consulta la guía de inicio rápido de Conda.
¿Cuáles son las ventajas de usar Docker para ejecutar Ultralytics YOLO?
Docker proporciona un entorno aislado y consistente para Ultralytics YOLO, lo que garantiza un rendimiento fluido en todos los sistemas y evita las complejidades de la instalación local. Las imágenes oficiales de Docker están disponibles en Docker Hub, con variantes para GPU, CPU, ARM64, NVIDIA Jetson y Conda. Para extraer y ejecutar la última imagen:
# 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 obtener instrucciones detalladas sobre Docker, consulta la guía de inicio rápido de Docker.
¿Cómo clono el repositorio de Ultralytics para el desarrollo?
Clone el repositorio de Ultralytics y configure un entorno de desarrollo 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 .
Esto permite realizar contribuciones al proyecto o experimentar con el código fuente más reciente. Para obtener más información, visite el repositorio de Ultralytics en GitHub.
¿Por qué debería usar la CLI de Ultralytics YOLO?
La CLI YOLO de Ultralytics simplifica la ejecución de tareas de detección de objetos sin código Python, lo que permite comandos de una sola línea para el entrenamiento, la validación y la predicción directamente desde su terminal. La sintaxis básica es:
yolo TASK MODE ARGS
Por ejemplo, para entrenar un modelo de detección:
yolo train data=coco8.yaml model=yolo11n.pt epochs=10 lr0=0.01
Explore más comandos y ejemplos de uso en la Guía de la CLI completa.