Conceptos
Todo lo que un proveedor necesita entender antes de escribir código. La referencia tiene el detalle campo por campo.
El BlastCase
Un caso es todo lo que un modelo puede leer sobre una voladura. La plataforma lo arma a partir del diseño, los receptores y las leyes ajustadas a las mediciones del sitio, y agrega la pregunta que se hace. El contrato también lleva el registro de lo ejecutado y los datos de calibración sin procesar, para cuando la plataforma los complete.
design: los barrenos del collar al pie como cargas espaciadas (decks), los productos, los retardos, el sistema de iniciación y la precisión de perforación, además de la carga instantánea máxima tal como la plataforma la calculó para el cumplimiento. Los campos de barrenos y de carga siguen IREDES, el estándar de intercambio de datos de perforación y voladura, de modo que un proveedor que ya lee IREDES los mapea campo por campo. Una pregunta hipotética puede llevar solo la carga.asBuilt: los barrenos tal como se perforaron y cargaron, y el registro de disparo tomado del registro de detonadores. Ausente antes de la voladura.site: los dominios de roca y, cuando un modelo la necesita, una superficie del terreno pasada por referencia.receivers: monitores, estructuras, linderos y puntos de interés, cada uno con una posición, la distancia que la plataforma determinó hasta él (levantada, ingresada o a la carga más cercana), o ambas, y los límites que se aplican allí.calibration: lo que el sitio ha medido (consulte Datos de calibración).measured: los registros de movimiento del terreno de la propia voladura, una vez disparada. Se envía solo para un diagnóstico.request: los tipos de salida solicitados, receptores o una cuadrícula, los percentiles a informar y una semilla de muestreo.consent: las condiciones del propietario de los datos para este caso, y su propósito: una predicción, o un diagnóstico de una voladura disparada.
El caseId es el SHA-256 del JSON canónico del caso, sin caseId ni createdAt, y sin el uri de ningún BlobRef (cualquier objeto que lleve uri, sha256 y mediaType): los bytes se nombran por su hash, y una URL firmada cambia de una ejecución a otra. La misma voladura con la misma pregunta siempre tiene el mismo id, y un proveedor puede recalcularlo para comprobar lo que recibió.
El manifiesto
Un modelo se describe a sí mismo en un manifiesto servido en GET /manifest: su id y versión, los tipos de salida que produce, las entradas que necesita cada uno, el dominio en el que está validado, cómo se ejecuta, cuánto cuesta y cómo trata los datos.
Las entradas se declaran como rutas del caso, por ejemplo calibration.seedWaveforms: obligatorias, opcionales o en un grupo cuyas entradas se sustituyen entre sí (requiredAnyOf, por ejemplo la carga a partir de la MIC declarada o a partir de los barrenos). Un modelo al que le falta una entrada obligatoria, o todas las entradas de un grupo, declina con missing_input. La plataforma quita todo lo que un modelo no declara antes de enviar el caso, y vuelve a calcular el hash del id del caso sobre lo que queda. Un proveedor nunca recibe datos que no pidió, y un cambio en datos que no lee nunca lo vuelve a ejecutar.
El precio es uno de included, per_run, per_hole, quote (un precio vinculante por caso obtenido de POST /quote) o licence, donde el operador aporta su propia licencia y la ejecución en sí no se cobra.
El ModelResult
Un resultado es una lista de salidas tipadas, cada una discriminada por kind. Cada salida lleva un veredicto de validez: within, dentro del dominio en el que se validó el modelo; extrapolated, más allá de él; o outside, fuera de él, con un code que indica en qué sentido, como above_fitted_range o near_field.
Una salida que el modelo no va a producir va bajo unavailable con un motivo: not_supported, missing_input, outside_validity o insufficient_calibration. Un tipo que se responde por receptor nombra en receiverId el receptor en el que declina, o null cuando declina en todos los receptores; un tipo que se responde para todo el caso no nombra ninguno. Omitirla no es una respuesta. Declinar es mejor que dar una cifra segura de sí misma fuera del dominio del modelo.
provenance fija el resultado al id del modelo, la versión exacta, el id del caso, las entradas realmente leídas y los parámetros que el modelo haya ajustado. Los informes lo citan.
Algunas preguntas van en sentido inverso. max_charge pide la mayor carga por retardo cuya predicción, en el percentil de diseño del caso, se mantiene bajo el límite de cada receptor: la cifra con la que se planifica una voladura.
La incertidumbre es parte de la respuesta
Las cantidades son objetos Estimate: una mediana más los percentiles que pidió el caso y, opcionalmente, los miembros del ensamble sin procesar. Las decisiones de cumplimiento se toman con los percentiles superiores, no con las medianas, y una predicción sin dispersión no puede puntuarse por cobertura.
Cuando un receptor tiene un límite, informe la probabilidad de excederlo. Es la cifra con la que actúa un operador.
Datos de calibración
Los macizos rocosos no son homogéneos, y las propiedades constitutivas que necesita un modelo de primeros principios rara vez pueden medirse en terreno. Las magnitudes que sí pueden medirse, como la velocidad de partícula, la velocidad de detonación y el desplazamiento, hacen que un modelo sea más fácil de calibrar y de validar. El contrato tiene un lugar para cada una. Hoy, un caso de la plataforma lleva las leyes ajustadas del sitio y de onda aérea.
siteLaw: la ley de atenuación por distancia escalada ajustada a las lecturas del propio sitio, con las estadísticas del ajuste que necesita un intervalo de predicción (los grados de libertad, la dispersión de las distancias escaladas) y la frecuencia dominante que el sitio registra a cada distancia.airblastLaw: lo mismo para la sobrepresión, con distancia escalada por raíz cúbica.seedWaveforms: registros de movimiento del terreno de un solo barreno, con carga y distancia; la entrada para la superposición de formas de onda semilla.vod: la velocidad de detonación medida por barreno.outcomes: lecturas de voladuras anteriores en el sitio.strainAmplitude: el ajuste del sitio de la deformación que una voladura induce en la roca cerca de las cargas, como un factor sobre la amplitud que un modelo de daño extrapola hacia dentro desde la ley del sitio, con aquello a lo que se ajustó (sobreexcavación, conteo de medias cañas, un escaneo o un arreglo de deformación) y el modelo y la versión con que se ajustó.
Diagnóstico de una voladura disparada
La mayoría de los tipos predice. hole_diagnosis lee una voladura ya disparada: a partir de los registros de movimiento del terreno de la propia voladura y de su registro de detonadores, qué hizo cada barreno. Un caso así tiene consent.purpose igual a diagnosis, pide solo hole_diagnosis y lleva los registros como measured.records: las filas de datos de cada uno, el receptor donde se tomó y cómo están orientados sus ejes. No se conoce el tiempo de un registro respecto de T0, ya que un registrador arranca cuando le llega el movimiento; encontrarlo es trabajo del modelo.
Cada barreno cargado recibe un veredicto (a tiempo, tardío, anticipado, no detectado, débil o fuerte) y una confianza que cubre solo lo que el veredicto afirma: que el barreno disparó y cuándo, su tamaño, o que no disparó. El tamaño es además una afirmación propia (size.call), de modo que un barreno puede estar a tiempo y ser débil a la vez, y las alternatives son afirmaciones separadas que no tienen por qué sumar uno. evidence lleva el movimiento que el modelo atribuye solo a ese barreno, para que un lector vea en qué se apoya un veredicto.
Los ejemplos publicados incluyen una voladura disparada como caso de diagnóstico, sus dos registros y la respuesta de la propia plataforma: /developers/examples/v0/diagnosis-case.json y /developers/examples/v0/diagnosis-run.json. Su segunda fila dispara tarde, su tercera fila no dispara, y tiene un barreno fuerte y uno débil.
strain_amplitude también lee una voladura disparada: a partir de la sobreexcavación observada detrás de algunos de sus barrenos (measured.backbreak), el factor sobre la amplitud de un modelo de daño que hace que el radio que informa en cada uno sea la distancia observada. La respuesta es lo que un caso posterior del sitio lleva como calibration.strainAmplitude, con el modelo y la versión que lo ajustaron como fittedWith, ya que un factor solo tiene sentido para el modelo que lo produjo.
Ejecuciones síncronas y asíncronas
Un modelo síncrono responde a POST /runs en menos de 30 segundos con la ejecución en succeeded. Un modelo asíncrono responde 202 con la ejecución en queued y luego envía run.running, run.succeeded o run.failed a la URL de callback. Como respaldo, la plataforma consultará GET /runs/{runId}.
Cada POST /runs lleva una Idempotency-Key. Una solicitud reintentada con la misma clave debe devolver la ejecución original, no iniciar una segunda. Entregue los webhooks al menos una vez; cada uno lleva un id de evento, para que un duplicado pueda reconocerse y descartarse.
Caché y reproducibilidad
Los resultados se guardan por id de caso y versión del modelo. Un caso idéntico enviado a la misma versión se responde desde lo guardado: no se ejecuta de nuevo ni se cobra de nuevo. Una nueva versión del modelo es una clave nueva, de modo que los resultados anteriores quedan exactamente como se emitieron.
Los modelos que muestrean deben respetar request.seed, para que una ejecución pueda reproducirse solo a partir de su caso.
Puntuación frente a las mediciones
Cuando una voladura se dispara, los monitores de la plataforma registran lo que ocurrió en los receptores. Cada predicción registrada para esa voladura se contrasta con esas lecturas en el mismo receptor: bajo el P50, dentro del P95 o por encima de él. Los modelos propios de la plataforma se puntúan así y, en acceso anticipado, también los modelos conectados de un equipo. A lo largo de muchas voladuras, las mismas puntuaciones se acumulan en sesgo, cobertura del P95 y habilidad predictiva, por sitio y por modelo.
Las puntuaciones son privadas de la cuenta del operador. Un equipo que conecta su propio modelo ve las respuestas y las puntuaciones de ese modelo en su propia cuenta, y nada se publica sin el acuerdo del proveedor.
Consentimiento y tratamiento de datos
Cada caso indica para qué es (una predicción, o un diagnóstico, que envía los registros de la propia voladura), cuánto tiempo puede conservarlo el proveedor y si puede usarse para entrenamiento (nunca, salvo que el propietario de los datos lo autorice expresamente). Un proveedor que no pueda respetar esas condiciones debe rechazar la ejecución con consent_refused. El manifiesto declara dónde se procesan los casos, para que un operador pueda ver adónde iría un caso antes de elegir un modelo.
Versionado
Cada documento lleva specVersion. Durante la vista previa, la v0 puede ganar campos, y los lectores deben ignorar los campos que no conozcan. Los cambios incompatibles llegarán como una nueva versión mayor con un periodo de obsolescencia, anunciada a los socios con antelación.
Convenciones: unidades del SI en todo (metros, kilogramos, milisegundos, mm/s, pascales). Las coordenadas son +X este, +Y norte, +Z arriba, en el sistema de coordenadas del caso. Las horas son UTC en ISO 8601. Los tiempos de disparo son milisegundos desde T0. Un campo ausente significa desconocido, nunca cero.