Predecir una imagen
Ejecuta un modelo YOLO26 preentrenado desde Python, lee las clases, las confianzas y las cajas en píxeles de los resultados, y ajusta los argumentos que resuelven la mayoría de los casos en los que no se detecta un objeto.
Todo uso real de un detector —contar existencias en una estantería, recortar caras para difuminarlas o enviar cajas a una API JSON— empieza por leer correctamente el objeto de resultado. Si te equivocas en un detalle, como indexar los nombres de clase con un tensor, la aplicación se bloqueará con la primera imagen.
Un modelo YOLO26 de detección preentrenado ya conoce las 80 clases de COCO. En esta lección ejecutarás el modo de predicción desde Python, extraerás de los resultados todos los campos útiles y aprenderás qué argumento cambiar cuando haya detecciones omitidas, duplicadas o de objetos pequeños. Más adelante, tu propio modelo entrenado devolverá el mismo objeto de resultado.
Práctico
Predice e imprime todas las detecciones#
Al llamar al modelo con una fuente, se ejecuta el modo de predicción y se devuelve una lista con un objeto Results por imagen. Si solo hay una imagen, lee results[0].
from ultralytics import YOLO
model = YOLO("yolo26n.pt")
results = model("https://ultralytics.com/images/bus.jpg")
result = results[0]
for box in result.boxes:
name = result.names[int(box.cls)]
conf = float(box.conf)
x1, y1, x2, y2 = box.xyxy[0].tolist()
print(f"{name:>8} {conf:.2f} ({x1:.0f}, {y1:.0f}) -> ({x2:.0f}, {y2:.0f})")
result.save("bus_annotated.jpg")Salida real de predict.py, después de la línea de registro habitual:
bus 0.88 (0, 230) -> (803, 751)
person 0.87 (49, 398) -> (240, 902)
person 0.86 (223, 405) -> (345, 861)
person 0.85 (670, 395) -> (810, 880)
person 0.65 (0, 553) -> (60, 871)Cómo leerla:
bus 0.88: nombre de clase y confianza. Las cajas están ordenadas por confianza, de mayor a menor.(0, 230) -> (803, 751): esquinas superior izquierda e inferior derecha en píxeles de la imagen original de 810×1080, con el origen en la esquina superior izquierda. Puedes recortar o dibujar directamente con estas coordenadas.person 0.65en(0, 553): una quinta persona, cortada por el borde izquierdo, obtiene una puntuación más baja. Los objetos parciales suelen tenerla.
result.save() escribe la imagen anotada; result.show() la abre en una ventana.
Qué contiene un resultado#
Todas las tareas devuelven el mismo tipo Results; solo cambian los campos que se rellenan. Consulta todos los campos disponibles en la guía de uso de Python.
| Atributo | Contiene |
|---|---|
boxes | Detecciones: píxeles xyxy, formato normalizado de centro xywhn, conf, cls y id cuando se usa seguimiento |
masks, keypoints, obb, probs | Salidas de los modelos de segmentación, pose, OBB y clasificación (None para un modelo de detección) |
names | Diccionario de índice de clase → nombre de clase |
orig_img, orig_shape | La imagen de entrada como matriz NumPy y su alto × ancho |
speed | Tiempo de preprocesamiento, inferencia y posprocesamiento en ms |
path, save_dir | De dónde procede la entrada y dónde se escribieron las salidas |
Para la detección de objetos, normalmente solo necesitas boxes, las cajas delimitadoras. result.summary() devuelve las mismas detecciones como una lista de diccionarios simples, lista para una API JSON.
Ajusta la predicción#
Los valores predeterminados sirven para la mayoría de las imágenes. Si no es así, cambia un argumento cada vez:
| Problema que observas | Parámetro | Predeterminado | Qué cambiar |
|---|---|---|---|
| Detecciones omitidas: un objeto visible no tiene caja | conf | 0.25 | Bájalo, por ejemplo, 0.1 |
| Falsos positivos: aparecen cajas donde no hay nada | conf | 0.25 | Súbelo, por ejemplo, 0.5 |
| Dos cajas para un mismo objeto | iou | 0.7 | Bájalo: el umbral de solapamiento (IoU) de NMS para fusionar duplicados |
| No se detectan objetos pequeños y lejanos | imgsz | 640 | Súbelo, por ejemplo, 1280 (se redondea a un múltiplo de 32) |
| Solo importan algunas clases | classes | todas | Por ejemplo, classes=[0] para personas |
| Hardware incorrecto | device | automático | cpu, mps o un índice de GPU como 0 |
La confianza cambia el resultado, no solo la cantidad. En la misma imagen de un autobús:
from ultralytics import YOLO
model = YOLO("yolo26n.pt")
model("https://ultralytics.com/images/bus.jpg", conf=0.5, classes=[0]) # 4 persons
model("https://ultralytics.com/images/bus.jpg", conf=0.1) # 5 personas, 1 autobús, 1 señal de stopCon conf=0.1, el modelo también informa de una señal de stop sobre la que no estaba seguro. Bajar conf es la forma más rápida de ver lo que el modelo casi ha detectado. Encontrarás todos los demás argumentos en la referencia de configuración.
Si una predicción no devuelve resultados, sigue estos pasos:
Ejecuta el modelo en varias imágenes#
Pasa una lista, una carpeta o un patrón glob como "photos/*.jpg". El valor predeterminado de Predict es batch=1; establece batch para procesar varias imágenes a la vez, lo que es mucho más rápido en una GPU:
from ultralytics import YOLO
model = YOLO("yolo26n.pt")
images = ["https://ultralytics.com/images/bus.jpg", "https://ultralytics.com/images/zidane.jpg"]
for result in model(images, batch=2):
print(result.path, len(result.boxes), result.verbose())image0.jpg 5 4 persons, 1 bus,
image1.jpg 3 2 persons, 1 tie,Evita estos errores#
Síntoma: KeyError: tensor([5.]). Causa: box.cls y box.conf son tensores de PyTorch, y result.names es un diccionario con claves int. Solución: conviértelos primero: result.names[int(box.cls)], float(box.conf), box.xyxy[0].tolist().
Síntoma: una función auxiliar que llama a YOLO("yolo26n.pt") dentro de la función se ejecuta lentamente. En la CPU de un portátil, volver a cargar el modelo para cada imagen tardó 71 ms, frente a 25 ms con el modelo cargado una sola vez. Solución: crea el modelo una vez al iniciar y reutilízalo con cada imagen.
model(list_or_folder) recopila todos los objetos Results en memoria antes de devolverlos. Para carpetas grandes y vídeos, pasa stream=True y recorre el generador: los resultados llegan de uno en uno. La lección sobre vídeo lo explica en profundidad.
Mostrar solución
from ultralytics import YOLO
model = YOLO("yolo26n.pt") # load once
images = ["https://ultralytics.com/images/bus.jpg", "https://ultralytics.com/images/zidane.jpg"]
for result in model(images, verbose=False):
top3 = sorted(result.summary(), key=lambda d: d["confidence"], reverse=True)[:3]
print(f"{result.path}: {len(result.boxes)} detections")
for d in top3:
print(f" {d['name']:>8} {d['confidence']:.2f}")image0.jpg: 5 detections
bus 0.90
person 0.85
person 0.85
image1.jpg: 3 detections
person 0.89
person 0.79
tie 0.59summary() ya devuelve nombres simples y números decimales, así que no hay que convertir tensores. Las confianzas difieren ligeramente de predict.py porque las imágenes de una lista se rellenan hasta alcanzar una forma común. Con conf=0.1, bus.jpg añade una señal de stop.