jevlaya
Français
Documentation

Adoption par étapes

Laya renvoie une décision typée, pas la permission de l’exécuter. Adopte un moteur de décision par étapes pour que l’application garde le contrôle de l’action réelle pendant que les preuves s’accumulent.

Ce guide décrit le déploiement côté application autour de Laya. Laya fournit la décision, les probabilités, la confiance et les événements de hook ; l’application possède l’action en place, la politique de déploiement, la frontière de revue et le rollback.

1. Ombre : observer sans effets de bord

Exécute Laya sur du trafic réel représentatif, mais garde l’action en place comme source de vérité. Un enregistrement d’ombre doit contenir assez de contexte pour reproduire une comparaison plus tard :

  • la classe de requête et le schéma de questions Laya ;
  • la réponse de Laya, les probabilités par option, la confiance, le checkpoint et le run_id ;
  • l’action en place et le résultat final revu ou de référence ;
  • la latence, les erreurs et toute décision de fallback ou de revue.

Utilise les hooks de prédiction existants pour les preuves côté Laya. Les fonctions de journalisation ci-dessous sont des espaces réservés propres à l’application ; ce ne sont pas des API 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)

Garde les champs sensibles masqués selon la politique de l’application. Attrape et journalise les exceptions autour de router.predict(...) à la frontière de l’application. Le hook de prédiction couvre le cycle de vie de la prédiction, mais les échecs antérieurs à ce cycle exigent une capture au niveau applicatif ; ne suppose pas que on_predict_end les ait vus. Un journal d’ombre ne doit pas transformer la journalisation en une nouvelle action visible par l’utilisateur.

Voir Hooks de prédiction, le cycle de vie des hooks, et Traçage pour l’ordre des événements et la corrélation par run_id.

2. Comparer : un désaccord est un signal, pas un verdict

Compare Laya à l’action en place sur la même requête et le même sens de question. Un désaccord n’est pas automatiquement une erreur : l’action en place peut se tromper, les cas peuvent être ambigus, ou l’action peut exiger un jugement humain. Utilise des étiquettes revues ou des résultats de référence quand ils existent, et garde un compartiment explicite unknown ou de revue au lieu de forcer chaque désaccord dans un score binaire.

Passe en revue les comparaisons par checkpoint, langue ou route, schéma de questions, type d’action et classe de risque. Consigne la couverture et le désaccord à côté de l’exactitude. Un fort taux d’accord sur un sous-ensemble facile ne justifie pas une promotion pour une autre langue, action ou forme de question.

3. Choisir une politique à partir de preuves mises de côté

Un seuil de confiance est une politique d’application, pas une propriété fournie par Laya. Ajuste ou calibre les scores de décision sur des données représentatives mises de côté, puis choisis un seuil à partir de l’exactitude mesurée et du coût des erreurs à la couverture que ton application peut tolérer. Il n’existe pas de nombre universel qui se transfère entre checkpoints, types de question, langues ou risques d’action.

Consigne le checkpoint et la version du schéma de questions, la méthode de calibration, le seuil, l’ensemble d’évaluation et le responsable avec la politique. Réévalue-la quand ces entrées changent. La confiance ordonne les décisions ; elle n’établit pas qu’une décision est correcte, et une confiance élevée n’est jamais à elle seule une permission d’exécution.

Quatre de ces six éléments viennent du harnais d’évaluation : un rapport laya-evals run --json enregistre le commit de checkpoint qui a répondu (config.revisions), les octets et le schéma de questions du jeu de données (config.dataset_sha256, config.questions_sha256) et la porte sous laquelle il a été évalué (config.thresholds). La méthode de calibration et le responsable sont à consigner par l’application. Voir Harnais d’évaluation pour l’identité d’exécution et la vérification de comparabilité entre une référence et un candidat.

Les sections gating automatique par confiance, Calibration et limites honnêtes du README donnent le contexte existant sur la calibration et la confiance. Garde les actions irréversibles ou coûteuses derrière une frontière de revue explicite, même quand leur confiance est élevée.

4. Promouvoir une tranche bornée

La promotion doit être un changement mesuré et réversible plutôt qu’un interrupteur global marche/arrêt. Définis une frontière d’éligibilité avant d’activer l’automatisation, par exemple :

  • le checkpoint, la langue/route et le schéma de questions sont dans l’ensemble évalué ;
  • l’action est réversible ou a un chemin de revue humaine explicite ;
  • la requête ne manque pas de contexte obligatoire et ne présente aucune erreur Laya ;
  • la tranche a un plafond de taille ou de trafic et une condition de rollback nommée.

Commence par un petit canari. Garde la revue ou le fallback pour les cas inéligibles, ambigus et échoués. Continue d’échantillonner les décisions promues, compare-les à l’action en place et aux résultats revus, et surveille le désaccord, la couverture, le taux de fallback, les erreurs et la latence. Reviens en arrière quand le garde-fou convenu est enfreint ; la promotion est un pas borné, pas une déclaration permanente que le modèle est correct.

La frontière application/Laya

Laya fournit les preuves de la décision et les expose via l’API et les hooks existants. L’application possède le résultat en place, l’exécution de l’action, les règles d’éligibilité, le seuil, la revue, le fallback et le rollback. Les hooks peuvent journaliser ou annoter des preuves, mais ils ne rendent pas une action à fort impact sûre à exécuter.

Un déploiement pratique est donc :

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

Liste de vérification du déploiement

  • Le journal d’ombre est sans effet de bord et corrélé par run_id.
  • Les données de comparaison incluent le résultat en place et les étiquettes revues ou de référence quand elles sont disponibles.
  • Les seuils sont ajustés et validés sur des données représentatives mises de côté.
  • Les actions irréversibles ou coûteuses ont une frontière de revue explicite.
  • La promotion est bornée, échantillonnée et réversible, avec un chemin de fallback et de rollback nommé.
  • Le responsable de la politique et le déclencheur de réévaluation sont consignés.

Voir aussi