Saltar al contenido principal

Conceptos clave

Antes de empezar a utilizar la API, es importante comprender algunos conceptos fundamentales sobre cómo funciona la plataforma y cómo se procesan las solicitudes.

Solicitud (Request)​

Una solicitud es la petición enviada a la API para procesar un fichero o recurso. Puede incluir:

  • El archivo directamente.
  • Una referencia al recurso.
  • Parámetros adicionales de configuración.

Cada solicitud inicia un flujo de procesamiento interno gestionado por la plataforma.

Ejecución (Run)​

Cuando la API recibe una solicitud válida, esta se convierte en una ejecución (run) dentro del sistema.

La tarea representa la unidad interna de procesamiento y contiene:

  • El identificador único del proceso.
  • El estado actual.
  • La referencia al fichero.
  • Los resultados generados.

Este desacoplamiento permite que la recepción de la petición y su procesamiento no dependan del mismo proceso síncrono.

Sistema de colas​

La plataforma utiliza un sistema de colas para gestionar las tareas pendientes de procesamiento.

Esto permite:

  • Desacoplar la API del procesamiento intensivo.
  • Evitar bloqueos ante picos de carga.
  • Gestionar múltiples solicitudes concurrentes.
  • Garantizar que ninguna tarea se pierda.

Cuando una solicitud se transforma en tarea, se coloca en una cola y queda pendiente hasta que un worker la procese.

Estado de una tarea​

Cada tarea pasa por distintos estados durante su ciclo de vida, por ejemplo:

  1. pending: en cola, pendiente de procesamiento.

  2. processing: en ejecución por un worker.

  3. completed: finalizada correctamente.

  4. failed: error durante el procesamiento.

La API permite consultar el estado para saber cuándo el resultado está disponible.

Resultado (Result)​

El resultado es la salida generada tras el procesamiento del fichero. Se devuelve en formato estructurado (JSON) y puede incluir:

  • Metadatos del análisis.
  • Resultados del modelo de IA.
  • Indicadores o métricas asociadas.
  • El diseño de los resultados facilita su integración en otros sistemas.

Resumen del flujo​

De forma simplificada:

  1. El cliente envía una solicitud a la API.
  2. La solicitud se convierte en una tarea.
  3. La tarea entra en la cola.
  4. Un worker procesa la tarea.
  5. El resultado queda disponible para su consulta.