Inferencia#

Ultralytics Platform ofrece inferencia en el navegador para probar modelos entrenados y endpoints dedicados para el acceso mediante programación.

Pestaña de predicción#

Todos los modelos que incluyen pesos tienen una pestaña Predict para realizar inferencias en el navegador:

1. Ve a tu modelo
2. Haz clic en la pestaña Predict
3. Sube una imagen, usa un ejemplo o abre tu cámara web
4. Revisa la superposición específica de la tarea, el resumen de predicciones, los tiempos y la respuesta sin procesar

Los modelos sin pesos muestran un estado vacío; primero entrena el modelo o sube los pesos.

Métodos de entrada#

El panel de predicción admite varios métodos de entrada:

graph LR
    A[Upload Image]:::start --> D[Auto-Inference]:::proc
    B[Example Image]:::start --> D
    C[Webcam Capture]:::start --> D
    D --> E[Results + Overlays]:::out

    classDef start fill:#4CAF50,color:#fff
    classDef proc fill:#2196F3,color:#fff
    classDef out fill:#9C27B0,color:#fff

Subir imagen#

Arrastra y suelta o haz clic para subir:

• Formatos compatibles: JPEG, PNG, WebP, AVIF, HEIC, JP2, TIFF, BMP
• Tamaño máximo: 10 MB
• Inferencia automática: los resultados aparecen automáticamente después de la carga

Imágenes de ejemplo#

El panel de predicción muestra hasta dos imágenes de ejemplo del conjunto de datos vinculado a tu modelo y da prioridad a la partición val, después a test y, por último, a train. Si no hay ningún conjunto de datos vinculado, se usan imágenes de ejemplo predeterminadas:

En los modelos OBB, se muestran en su lugar imágenes aéreas de barcos y de un aeropuerto.

Cámara web#

Selecciona Cámara web encima del área de imagen para iniciar una transmisión en directo de la cámara:

1. Concede permiso para usar la cámara cuando se te solicite
2. Haz clic en la vista previa del vídeo para capturar un fotograma
3. La inferencia se ejecuta automáticamente en el fotograma capturado
4. Haz clic en Volver a la cámara web para volver a la transmisión en directo

En la pestaña Predict de tu propio despliegue, la cámara web ejecuta inferencias continuamente. Consulta Inferencia con cámara en directo.

Ver resultados#

Los resultados de la inferencia muestran la salida correspondiente a la tarea del modelo: cajas, máscaras, puntos clave, cajas orientadas, puntuaciones de clasificación, cobertura semántica o un mapa de profundidad. Cuando están disponibles, los resultados de los objetos usan los colores de clase del conjunto de datos. El panel también muestra los tiempos de preprocesamiento, inferencia, posprocesamiento y red.

El panel de resultados muestra:

Cuando aparecen los resultados, hay dos controles sobre la vista previa: haz clic en la imagen para ampliarla sin perder las superposiciones y usa el botón de descarga para guardar un JPEG anotado del resultado actual.

Parámetros de inferencia#

Ajusta el comportamiento de inferencia con los tres controles deslizantes situados debajo de la imagen (los modelos de profundidad solo muestran Tamaño de imagen):

Umbral de confianza#

Filtra las predicciones por confianza:

• Más alto (0.5+): menos predicciones y más seguras
• Más bajo (0.1-0.25): más predicciones, con algo de ruido
• Predeterminado (0.25): equilibrado para la mayoría de los casos de uso

Umbral de IoU#

Controla la supresión no máxima:

• Más alto (0.7+): permite más cajas superpuestas
• Más bajo (0.3-0.5): suprime las detecciones superpuestas de forma más agresiva
• Predeterminado (0.7): comportamiento de NMS equilibrado para la mayoría de los casos de uso

Predicción en el despliegue#

Cada endpoint dedicado en ejecución incluye una pestaña Predict en su página de despliegue. Esta pestaña utiliza el propio servicio de inferencia del despliegue, en lugar del servicio de predicción compartido, para que puedas probar el endpoint desplegado desde el navegador.

En un endpoint listo, las imágenes procesadas también se incluyen en la pestaña Monitoring. Sus ejemplos y gráficos agregados son datos temporales y ligeros que se guardan en memoria; detener, reiniciar, volver a desplegar, cambiar el tamaño o sustituir el modelo puede borrarlos. Guarda los ejemplos en un conjunto de datos para conservarlos.

Inferencia con cámara en directo#

En la pestaña Predict de un despliegue que te pertenece, selecciona Cámara web o Cámara IP para ejecutar el endpoint sobre vídeo en directo:

La inferencia en directo usa la clave API asociada al endpoint, que solo puede cargar el propietario del espacio de trabajo; para los demás miembros del equipo, la cámara web captura fotogramas individuales y Cámara IP no está disponible, igual que en la pestaña Predict de un modelo. La cámara IP debe ser accesible desde Internet: el endpoint rechaza direcciones de redes locales como 192.168.x.x. Cada resultado corresponde al fotograma más reciente, por lo que se omiten fotogramas si la inferencia se retrasa. Los cambios en los controles deslizantes se aplican al siguiente fotograma de la cámara web y reinician una transmisión de cámara IP. La inferencia en directo se pausa cuando la pestaña del navegador queda oculta. Haz clic en la vista previa para capturar un fotograma o en Desconectar para dejar de ver la cámara IP.

Cámara en segundo plano#

Un endpoint con un tamaño personalizado de CPU y memoria puede seguir vigilando una cámara IP después de que te desconectes o cierres la página. Cuando la cámara conectada muestre resultados, activa Mantener en ejecución en segundo plano. El encabezado del despliegue muestra Cámara activada, y los resultados aparecen en la pestaña Supervisión como ejemplos temporales y estadísticas de predicción.

• Ajustes: La cámara en segundo plano siempre usa la confianza predeterminada (0.25), IoU (0.7) y el tamaño de imagen de entrenamiento del modelo; los controles deslizantes no se aplican a esta cámara.
• Coste: Se ejecuta en la instancia activa del endpoint sin coste adicional; se aplica la tarifa por hora de tiempo de actividad tanto si la cámara está encendida como si está apagada.
• Cambios: Al encender o apagar la cámara, o cambiar a otra, se reinicia la instancia del endpoint, que queda lista de nuevo, pero se borran sus datos temporales de supervisión.
• Detención: Apaga el interruptor. Desconectarte o cerrar la página no detiene la cámara, y cambiar el tamaño del endpoint al predeterminado la elimina. Si la cámara se desconecta, el endpoint sigue intentando conectarse de nuevo.
• Ciclo de vida del endpoint: Al detener el endpoint, se detienen la cámara y los cargos; al iniciarlo de nuevo, se reanuda la cámara guardada.

Los endpoints de tamaño predeterminado ofrecen inferencia en directo con cámara web y cámara IP, pero no la opción de segundo plano. Para guardar una cámara en segundo plano desde la API, usa la acción camera del despliegue.

Transmitir resultados desde la API#

Envía una URL RTSP o RTSPS como source con el encabezado Accept: text/event-stream a una URL de endpoint dedicado para recibir resultados como eventos enviados por el servidor:

curl -N -X POST \
  "https://YOUR_DEPLOYMENT_URL.run.app/predict" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: text/event-stream" \
  -F "source=rtsp://user:password@camera.example.com:554/stream" \
  -F "conf=0.25"

Cada evento de fotograma incluye images con el formato de respuesta, con coordenadas normalizadas (0-1), una URL de datos JPEG preview del fotograma y metadata con la tarea y los nombres de las clases. Solo se aplican conf, iou y imgsz, y la transmisión de la URL de la cámara en segundo plano del endpoint usa los ajustes predeterminados. Los eventos que solo contienen status no incluyen ningún fotograma, y un evento con un mensaje error (no se ha podido leer la cámara o el endpoint no puede ejecutar el modelo) finaliza la transmisión. La transmisión también se cierra cuando se reinicia el endpoint o la solicitud alcanza su límite de tiempo; si termina sin error, vuelve a conectarte con un intervalo de espera creciente. La ruta de predicción de despliegues de Platform API y el SDK no transmiten resultados; envía las solicitudes de cámara a la URL del endpoint con la clave API asociada. Una source de cámara sin el encabezado devuelve 400.

API del endpoint dedicado#

La tarjeta API Docs de la pestaña Predict del modelo contiene ejemplos de solicitudes en Python, JavaScript y cURL, con los valores de confianza, IoU y tamaño de imagen configurados actualmente en los controles deslizantes. La URL y la clave son marcadores de posición hasta que despliegues el modelo; el botón Deploy, junto a las pestañas de código, te lleva a la pestaña Deploy del modelo. Tras el despliegue, la pestaña de resultados Docs de la pestaña Predict de la página de despliegue completa la URL de ese endpoint y, para los propietarios del espacio de trabajo, su clave de API asociada, lista para copiar y ejecutar.

Autenticación#

Incluye tu clave de API en las solicitudes:

Authorization: Bearer YOUR_API_KEY

Endpoint#

Los endpoints dedicados reciben solicitudes en su propia URL:

POST https://YOUR_DEPLOYMENT_URL.run.app/predict

La inferencia compartida utiliza la API de Platform con la ruta completa del modelo:

POST https://platform.ultralytics.com/api/models/{owner}/{project}/{model}/predict

Ambos aceptan el mismo cuerpo multipart/form-data y devuelven la misma estructura de respuesta. Con el SDK de Python, utiliza client.models.predict(owner, project, model, body=...) para la inferencia compartida o client.deployments.predict(owner, deployment, body=...) para un despliegue dedicado. Ambos métodos del SDK llaman a la API de Platform, por lo que se aplican sus límites de frecuencia y el límite de tamaño de las solicitudes. Para evitarlos, envía la solicitud directamente a la URL de un endpoint dedicado, como se muestra en Solicitud. Ejemplo de inferencia compartida:

from ultralytics_platform import Platform

client = Platform()  # reads ULTRALYTICS_API_KEY
with open("image.jpg", "rb") as f:
    results = client.models.predict("acme-vision", "inspection", "v3", body={"file": f, "conf": 0.25})

Solicitud#

import requests

url = "https://YOUR_DEPLOYMENT_URL.run.app/predict"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
data = {"conf": 0.25, "iou": 0.7, "imgsz": 640}

with open("image.jpg", "rb") as image_file:
    response = requests.post(url, headers=headers, files={"file": image_file}, data=data)
print(response.json())

Parámetros de la solicitud#

Respuesta#

{
    "images": [
        {
            "shape": [1080, 1920],
            "results": [
                {
                    "class": 0,
                    "name": "person",
                    "confidence": 0.92,
                    "box": { "x1": 100, "y1": 50, "x2": 300, "y2": 400 }
                },
                {
                    "class": 2,
                    "name": "car",
                    "confidence": 0.87,
                    "box": { "x1": 400, "y1": 200, "x2": 600, "y2": 350 }
                }
            ],
            "speed": {
                "preprocess": 1.2,
                "inference": 12.5,
                "postprocess": 2.3
            }
        }
    ],
    "metadata": {
        "imageCount": 1,
        "classNames": ["person", "bicycle", "car", "..."],
        "functionTimeAlive": 1284.51,
        "functionTimeCall": 0.018,
        "task": "detect",
        "version": {
            "ultralytics": "8.x.x",
            "torch": "2.6.0",
            "torchvision": "0.21.0",
            "python": "3.13.0"
        }
    }
}

Campos de la respuesta#

Respuestas específicas de cada tarea#

El formato de la respuesta varía según la tarea:

{
  "class": 0,
  "name": "person",
  "confidence": 0.92,
  "box": {"x1": 100, "y1": 50, "x2": 300, "y2": 400}
}

Límites de frecuencia#

La API del modelo compartido está limitada a 20 solicitudes/minuto por cada clave de API, usuario autenticado o IP anónima. La ruta de predicción del despliegue de Platform (POST /api/deployments/{owner}/{deployment}/predict) tiene el mismo límite. Cuando se alcanza el límite, la API devuelve 429 con una cabecera Retry-After. Consulta la referencia completa sobre límites de frecuencia para conocer todas las categorías de endpoints.

Gestión de errores#

Respuestas de error habituales:

Preguntas frecuentes#