jevlaya
Español
Documentación

Adopción por etapas

Laya devuelve una decisión tipada, no permiso para ejecutarla. Adopta un motor de decisiones por etapas para que la aplicación conserve el control de la acción real mientras se acumulan evidencias.

Esta guía describe el despliegue del lado de la aplicación alrededor de Laya. Laya aporta la decisión, las probabilidades, la confianza y los eventos de hook; la aplicación es dueña de la acción vigente, la política de despliegue, la frontera de revisión y la reversión.

1. Sombra: observar sin efectos secundarios

Ejecuta Laya sobre tráfico real representativo, pero mantén la acción vigente como autoritativa. Un registro de sombra debería contener suficiente contexto para reproducir una comparación más tarde:

  • la clase de solicitud y el esquema de preguntas de Laya;
  • la respuesta de Laya, las probabilidades por opción, la confianza, el checkpoint y el run_id;
  • la acción vigente y el resultado final revisado o de referencia;
  • la latencia, los errores y cualquier decisión de respaldo o revisión.

Usa los hooks de predicción existentes para la evidencia del lado de Laya. Las funciones de registro de abajo son marcadores de posición de la aplicación; no son API de Laya:

from laya import Router

class ShadowLog:
    def on_predict_end(self, ctx):
        result = ctx.results[0] if ctx.results else None
        write_shadow_record({
            "run_id": ctx.run_id,
            "model": ctx.model,
            "decision": ctx.decision,
            "result": result,
            "elapsed_ms": ctx.elapsed_ms,
            "error": None if ctx.error is None else repr(ctx.error),
        })

router = Router(hooks=[ShadowLog()])

def handle(request):
    try:
        laya_result = router.predict(request.state, request.questions)
    except Exception as exc:
        record_laya_failure(request, exc)
        return run_incumbent_action(request)
    # The shadow result is recorded by the hook; do not execute it here.
    return run_incumbent_action(request)

Mantén censurados los campos sensibles según la política de la aplicación. Captura y registra las excepciones alrededor de router.predict(...) en la frontera de la aplicación. El hook de predicción cubre el ciclo de vida de la predicción, pero los fallos anteriores a ese ciclo de vida requieren captura a nivel de aplicación; no asumas que on_predict_end los vio. Un registrador de sombra no debe convertir el registro en una nueva acción visible para el usuario.

Consulta Hooks de predicción, el ciclo de vida de los hooks y Tracing para el orden de los eventos y la correlación por run_id.

2. Comparar: el desacuerdo es una señal, no un veredicto

Compara Laya con la acción vigente sobre la misma solicitud y el mismo significado de la pregunta. Un desacuerdo no es automáticamente un error: la acción vigente puede estar equivocada, los casos pueden ser ambiguos, o la acción puede requerir juicio humano. Usa etiquetas revisadas o resultados de referencia cuando los tengas, y mantén un cajón explícito de unknown o de revisión en lugar de forzar cada desacuerdo a una puntuación binaria.

Revisa las comparaciones por checkpoint, idioma o ruta, esquema de preguntas, tipo de acción y clase de riesgo. Registra la cobertura y el desacuerdo junto a la precisión. Una tasa de acuerdo alta en un subconjunto fácil no justifica la promoción para otro idioma, acción o forma de pregunta.

3. Elegir una política a partir de evidencia reservada

Un umbral de confianza es una política de la aplicación, no una propiedad que aporte Laya. Ajusta o calibra las puntuaciones de decisión sobre datos reservados representativos, y luego elige un umbral a partir de la precisión medida y el coste del error con la cobertura que tu aplicación pueda tolerar. No hay ningún número universal que se traslade entre checkpoints, tipos de pregunta, idiomas o riesgos de acción.

Registra con la política el checkpoint y la versión del esquema de preguntas, el método de calibración, el umbral, el conjunto de evaluación y el responsable. Vuelve a evaluarla cuando cambien esas entradas. La confianza ordena las decisiones; no establece que una decisión sea correcta, y una confianza alta nunca es por sí sola permiso de ejecución.

Cuatro de esas seis cosas provienen del harness de evaluación: un informe laya-evals run --json registra el commit del checkpoint que respondió (config.revisions), los bytes del conjunto de datos y el esquema de preguntas (config.dataset_sha256, config.questions_sha256) y la puerta bajo la que se puntuó (config.thresholds). El método de calibración y el responsable son cosa de la aplicación. Consulta Harness de evaluación para la identidad de la ejecución y la comprobación de comparabilidad entre una línea base y un candidato.

Las secciones del README Automated Confidence Gating, Calibration y Honest limits dan el contexto existente de calibración y confianza. Mantén las acciones irreversibles o costosas detrás de una frontera de revisión explícita incluso cuando su confianza sea alta.

4. Promover una porción acotada

La promoción debe ser un cambio medido y reversible en lugar de un interruptor global de encendido/apagado. Define una frontera de elegibilidad antes de habilitar la automatización, por ejemplo:

  • el checkpoint, el idioma o ruta y el esquema de preguntas están en el conjunto evaluado;
  • la acción es reversible o tiene una ruta explícita de revisión humana;
  • a la solicitud no le falta contexto obligatorio y no tiene ningún error de Laya;
  • la porción tiene un tope de tamaño o de tráfico y una condición de reversión con nombre.

Empieza con un canario pequeño. Mantén revisión o respaldo para los casos no elegibles, ambiguos y fallidos. Sigue muestreando las decisiones promovidas, compáralas con la acción vigente y los resultados revisados, y monitoriza el desacuerdo, la cobertura, la tasa de respaldo, los errores y la latencia. Revierte cuando se incumpla el guardarraíl acordado; la promoción es un paso acotado, no una declaración permanente de que el modelo es correcto.

La frontera aplicación/Laya

Laya aporta la evidencia de la decisión y la expone a través de la API y los hooks existentes. La aplicación es dueña del resultado vigente, la ejecución de la acción, las reglas de elegibilidad, el umbral, la revisión, el respaldo y la reversión. Los hooks pueden registrar o anotar evidencia, pero no hacen que una acción de alto impacto sea segura de ejecutar.

Un despliegue práctico es por tanto:

real request
    ├─ incumbent action (authoritative)
    └─ Laya shadow decision ──> log, compare, evaluate
                                  └─ bounded eligible slice
                                      └─ review / fallback / rollback

Lista de verificación del despliegue

  • El registro de sombra no tiene efectos secundarios y está correlacionado por run_id.
  • Los datos de comparación incluyen el resultado vigente y las etiquetas revisadas o de referencia cuando estén disponibles.
  • Los umbrales se ajustan y validan sobre datos reservados representativos.
  • Las acciones irreversibles o costosas tienen una frontera de revisión explícita.
  • La promoción es acotada, muestreada y reversible, con una ruta de respaldo y reversión con nombre.
  • Se registran el responsable de la política y el disparador de reevaluación.

Véase también