Aller au contenu
English

Barrières d'évaluation

  • Leçon 14
  • 55 min
  • Module 5 : Mettre en production et améliorer en toute sécurité

Où nous en sommes

Dans le module 4, nous avons appris à voir quand l'assistant se dégrade après une mise en production. Mais il vaut mieux arrêter un mauvais changement avant qu'il atteigne les clients : la semaine dernière, la requête v3 a été mise en production même si son expérience disait de ne pas le faire. Dans cette leçon, nous transformons les preuves sur une version candidate en une seule décision qu'un script applique, comme la liste de vérification d'un pilote avant le décollage.

Lue depuis YouTube. Rien ne se charge depuis YouTube avant que vous appuyiez sur lecture. Confidentialité

Ce que vous saurez faire

Transformez les résultats d’une version candidate en une décision qu’un script peut appliquer : déployer auprès d’un groupe restreint, ou non. La décision combine la qualité hors ligne, les échecs critiques, la latence et le coût. Un seul contrôle échoué arrête la mise en production.

Avant de commencerCe qu’il faut savoir et avoir sous la mainEnviron 55 minutes

Ce que vous devez savoir

Ce qu’il vous faut sur votre ordinateur

  • Votre projet ticket-api à la fin du module 4, ou une copie de l’instantané end-of-m04. python -m pytest affiche 207 passed (207 tests réussis).
  • Docker exécutant PostgreSQL et Valkey (docker compose up -d db cache), pour la migration et les tests.

Aucun compte, aucune clé et aucune dépense. La barrière lit seulement des fichiers.

Avant chaque vol, un pilote lit une liste de vérification : carburant, volets, instruments, portes. Chaque ligne indique une réussite ou un échec. Si une ligne échoue, l’avion ne décolle pas. Un ciel dégagé et une cabine pleine ne changent rien.

La liste a trois propriétés utiles :

  • Elle est écrite avant le vol. Personne ne discute de la limite de carburant pendant que les passagers attendent.
  • Certaines lignes sont absolues. Une porte qui ne ferme pas n’est jamais « presque correcte ».
  • La réussir n’est pas la fin. Après le décollage, l’équipage surveille encore les instruments.

Une mise en production de l’assistant a besoin de la même chose.

Le problème : une décision que personne ne devait lire

Section intitulée « Le problème : une décision que personne ne devait lire »

Rappelez-vous « la semaine dernière ». Le cours sur l’évaluation avait exécuté la requête v3 sur ses billets réservés et figés. Sa décision était NE PAS DÉPLOYER. Priya l’avait écrite dans le registre d’expérience EXP-001. Puis quelqu’un a activé la requête v3 pour tous les billets en changeant un paramètre. Aucune étape de ce changement ne demandait la décision.

Dans la reproduction de l’incident pour l’exercice, 186 des 1 798 billets traités par v3 n’ont reçu aucune réponse. Dix billets nécessitant une personne n’ont atteint personne. Les réponses sont des enregistrements réels du cours sur l’évaluation; le changement est construit.

Les preuves existaient. Elles ne bloquaient simplement pas le changement. On peut ignorer une décision dans un document. On ne peut pas ignorer une décision qu’un script vérifie avant chaque déploiement.

Une barrière d’évaluation, ou barrière de mise en production, est un contrôle exécuté avant qu’une version candidate atteigne les clients. Elle lit les preuves de la version candidate et un fichier de limites, puis donne une décision. Chaque ligne doit réussir.

La barrière combine trois types de preuves :

  1. Éléments bloquants : échecs critiques. Une liste de billets pour lesquels un échec est inacceptable, comme un billet de sécurité sans réponse. Un seul échec sur ces billets arrête la mise en production, peu importe les moyennes.
  2. Qualité, avec son incertitude. On compare la version candidate à la version en production sur les mêmes billets. La barrière utilise la borne inférieure de l’intervalle à 95 % de la différence, pas la moyenne. La question est « pourrait-elle vraisemblablement être pire que ce que nous acceptons? », pas « est-elle meilleure en moyenne? ».
  3. Limites opérationnelles. Le coût par 1 000 billets et le 95e centile du temps de triage. Une réponse correcte qui dépasse le budget ou l’objectif de temps nuit quand même au service.

La barrière est la première étape du parcours de mise en production. Une réussite ne signifie pas « tous les clients y ont accès ». Elle signifie « un petit groupe de clients peut maintenant y avoir accès ». La prochaine leçon, Déploiements contrôlés, couvre cette partie.

Un flux de gauche à droite. Une version candidate, un nouveau manifeste avec sa requête, son modèle et son index, arrive à la barrière de mise en production. Celle-ci combine les preuves hors ligne et les limites, dans un cadre épais. Si un contrôle échoue, la flèche mène à : conserver la version active et écrire pourquoi dans le registre d'expérience. Si tous les contrôles réussissent, la flèche mène au mode parallèle. Celui-ci traite chaque billet à côté de la version en production, sans être visible pour les clients. Puis elle mène au déploiement restreint, qui traite une part des billets, comme 10 %. Si une règle de retour arrière s'applique, la flèche mène au retour arrière : revenir à la version active et prouver le rétablissement. Si assez de billets passent sans qu'une règle s'applique, la flèche mène à la promotion : la version restreinte devient la version active.
Le parcours de mise en production de ce module. La barrière décide avec des preuves hors ligne avant qu'un client voie la version candidate. Le mode parallèle et le déploiement restreint la testent ensuite sur des billets réels.
Description textuelle du diagramme

Une version candidate commence par un nouveau manifeste de version. La barrière vérifie ses preuves hors ligne selon les limites écrites. Si un contrôle échoue, la version active reste en place et la raison entre dans le registre d’expérience. Si tous les contrôles réussissent, la version candidate peut fonctionner en mode parallèle. Elle voit alors chaque billet, mais ne répond à aucun client. Ensuite, elle fonctionne en déploiement restreint pour une part des billets. Si une règle de retour arrière s’applique, on revient à la version active. L’équipe prouve alors que le service s’est rétabli. Si assez de billets passent et qu’aucune règle ne s’applique, la version restreinte est promue.

Un petit exemple : un élément bloquant l’emporte sur de bonnes moyennes

Section intitulée « Un petit exemple : un élément bloquant l’emporte sur de bonnes moyennes »

Voici une version candidate construite. Elle coûte moins cher et répond plus vite que la requête v2, avec des décisions à peu près aussi bonnes. Mais un billet de sécurité de l’évaluation n’a reçu aucune réponse. Exécutez la barrière sur cette version :

Exécutez du Python dans votre navigateur

Une barrière de mise en production en quelques lignes

Le bloc affiche une ligne par contrôle, puis la décision. Cinq contrôles réussissent, mais critical tickets failed (billets critiques échoués) échoue. La décision est donc DO NOT SHIP (1 failed) (ne pas déployer, un échec). Réglez l’élément bloquant à 0 et relancez : SHIP to a canary (déployer auprès d’un groupe restreint). Réglez ensuite la borne inférieure à −0,05 : encore DO NOT SHIP (1 failed).

La première exécution affiche :

critical tickets failed 1.00 <= 0 FAIL
answers without text 0.00 <= 0 pass
decisions, lower end of new - old -0.02 >= -0.03 pass
needs a person, share caught 1.00 >= 1.0 pass
cost per 1,000 tickets (US$) 0.30 <= 0.4 pass
triage time p95 (s) 4.10 <= 8.0 pass
Decision: DO NOT SHIP (1 failed)

Deux choses à remarquer :

  • Rien n’est moyenné. Une version rapide et peu coûteuse ne peut pas « compenser » un billet de sécurité sans réponse.
  • Le contrôle de qualité utilise l’intervalle. Supposons qu’une version candidate soit meilleure de 0,01 en moyenne, avec un intervalle de −0,05 à +0,07. La vraie différence pourrait alors être de 5 points en moins : plus que les 3 points acceptés par l’équipe. La barrière dit donc non. Cette limite est une marge de non-infériorité : « pas pire de plus de 3 points ». Pour réussir, la version candidate a besoin de plus de billets d’évaluation, ou d’une amélioration réelle.

Ce module ajoute des fichiers pour ses trois leçons : la barrière, les outils de déploiement et le tableau d’amélioration. Copiez-les maintenant, une seule fois. Chaque leçon explique ses propres fichiers.

  1. Dans un terminal, allez dans votre projet et activez l’environnement virtuel.

    Fenêtre de terminal
    cd ~/projects/ticket-api
    source .venv/bin/activate
  2. Copiez les fichiers du module depuis l’instantané end-of-m05. Douze fichiers sont nouveaux et quatre changent.

    Fenêtre de terminal
    S=../nextia-learning-labs/C25/snapshots/end-of-m05
    mkdir -p operations/evidence
    for f in migrations/020_release_state.sql ticket_api/rollout.py ticket_api/worker.py \
    ticket_api/releases.py ops/cmd_gate.py ops/cmd_rollout.py ops/cmd_canary.py \
    operations/gates.toml operations/rollout.toml operations/evidence/assistant-v2.json \
    operations/evidence/assistant-v3.json scripts/scenario.py scripts/practice.py \
    docs/improve.md tests/test_rollout.py README.md; do
    cp "$S/$f" "$f"
    done
  3. Appliquez la nouvelle migration. Elle ajoute deux tables pour la prochaine leçon et conserve vos données.

    Fenêtre de terminal
    python -m ticket_api.migrate
    applied 020_release_state
    Database is up to date (20 migrations).
  4. Le code et la dernière migration ont changé. Vos anciens manifestes de version ne décrivent donc plus ce service. Construisez-en de nouveaux pour les requêtes v2 et v3 :

    Fenêtre de terminal
    python -m ops release build --prompt assistant-v2 --evidence baseline-v2-chat-small-r1-b6a2b9 --write
    python -m ops release build --prompt assistant-v3 --evidence candidate-v3-chat-small-r1-31b45f --write

    La dernière ligne de chacun :

    Saved operations/releases/1.5.0-5a4f87.toml. Run the service with RELEASE_ID=1.5.0-5a4f87
    Saved operations/releases/1.5.0-422985.toml. Run the service with RELEASE_ID=1.5.0-422985

    Vos identifiants sont identiques si vos fichiers correspondent exactement à l’instantané et si votre projet n’est pas un dépôt Git. Sinon, ils diffèrent, et c’est normal.

  5. Ouvrez .env. S’il contient une ligne RELEASE_ID, réglez-la sur votre nouvel identifiant v2, par exemple RELEASE_ID=1.5.0-5a4f87. Construire le manifeste v3 ne le déploie pas.

  6. Exécutez les tests. Vous devriez voir 213 passed (213 tests réussis), soit 6 de plus qu’avant :

    Fenêtre de terminal
    python -m pytest
    213 passed, 1 deselected in 21.45s
Fichiers Ce qu’ils ajoutent Leçon
operations/evidence/, operations/gates.toml, ops/cmd_gate.py les preuves des requêtes v2 et v3, les limites, python -m ops gate celle-ci
migrations/020_release_state.sql, ticket_api/rollout.py, ticket_api/worker.py, ops/cmd_rollout.py, ops/cmd_canary.py, operations/rollout.toml, scripts/scenario.py, scripts/practice.py versions active, parallèle et restreinte; règles de retour arrière; scénarios d’exercice Déploiements contrôlés
docs/improve.md d’un symptôme au changement qui corrige sa cause Réentraîner ou réviser
ticket_api/releases.py, tests/test_rollout.py, README.md une ligne d’index plus claire dans les nouveaux manifestes; les tests; les commandes les trois

Les preuves de la barrière pour chaque requête se trouvent dans un petit fichier dans operations/evidence/. Il contient les résultats du cours sur l’évaluation sur ses 98 billets réservés et figés. Personne n’a utilisé ces billets pour écrire ou ajuster les requêtes. Le fichier nomme l’exécution et le jeu d’évaluation, d4c96eaa10c0, pour retracer chaque nombre.

Exécutez la barrière pour la version candidate :

Fenêtre de terminal
python -m ops gate assistant-v3
Release gate for assistant-v3 (baseline assistant-v2), evidence: candidate-v3-chat-small-r1-31b45f on the holdout split of d4c96eaa10c0
check value limit result detail
---------------------------------------------- ------ -------- ------ --------------------------
blockers (critical cases failed) 1 <= 0 FAIL T-65663 no_answer_critical
answers without text (holdout) 8 <= 0 FAIL of 98 tickets
decisions: lower end of (candidate - baseline) -0.184 >= -0.03 FAIL -0.112 [-0.184, -0.041]
needs a person: share caught 0.958 >= 1.0 FAIL 23 of 24
cost per 1,000 tickets (US$) 0.480 <= 0.4 FAIL baseline 0.339
triage time p95 (s) 8.534 <= 8.0 FAIL baseline 4.896
Decision: DO NOT SHIP (6 failed: blockers (critical cases failed), answers without text (holdout), decisions: lower end of (candidate - baseline), needs a person: share caught, cost per 1,000 tickets (US$), triage time p95 (s))

Lisez le résultat ligne par ligne :

  • Élément bloquant : T-65663, un billet de sécurité, n’a reçu aucune réponse. Cela suffit à lui seul.
  • Réponses sans texte : 8 des 98 billets réservés. Le modèle a utilisé tous ses jetons pour raisonner et n’a rien écrit.
  • Décisions : v3 est moins bonne de 0,112, et l’intervalle atteint −0,184. Dans le pire cas plausible, c’est 18 points de moins, contre une marge de 3.
  • Besoin d’une personne : 23 des 24 billets nécessitant une personne en ont atteint une. Un client attendrait sans que personne s’occupe de lui.
  • Coût : 0,480 $ US par 1 000 billets, au-dessus du budget de 0,40 $ US. Omar voulait que v3 coûte moins cher; v2 coûte 0,339 $ US sur les mêmes billets.
  • Temps : le 95e centile de l’appel de triage est de 8,534 s, au-dessus de la limite de 8,0 s.

La commande se termine aussi avec le code de sortie 1. Un script de mise en production ou une tâche CI lit ce code et s’arrête. C’est ce qui rend la décision incontournable lors du changement :

Fenêtre de terminal
python -m ops gate assistant-v3 > /dev/null; echo $?
1
La barrière de mise en production. À gauche, deux entrées : les preuves hors ligne du cours sur l'évaluation sur 98 billets réservés dans operations/evidence, et les limites. operations/gates.toml contient les limites de qualité, de latence et de coût, ce dernier provenant du budget SLO. Les deux pointent vers un tableau de six contrôles à quatre colonnes : contrôle, limite, requête v3, requête v2. Élément bloquant, un billet critique échoué : limite 0, v3 1 ÉCHEC, v2 0 réussite. Réponses sans texte : limite 0, v3 8 ÉCHEC, v2 0 réussite. Décisions, borne inférieure de v3 moins v2 : limite au moins −0,03, v3 −0,184 ÉCHEC, v2 0 réussite. Besoin d'une personne, proportion repérée : limite 100 %, v3 23 sur 24 ÉCHEC, v2 24 sur 24 réussite. Coût par 1 000 billets : limite au plus 0,40, v3 0,480 ÉCHEC, v2 0,339 réussite. Temps de triage p95 : limite au plus 8,0 s, v3 8,53 s ÉCHEC, v2 4,90 s réussite. À droite, deux décisions : requête v3, NE PAS DÉPLOYER, 6 contrôles sur 6 échouent, code de sortie 1, dans un cadre épais; requête v2, DÉPLOYER auprès d'un groupe restreint, les 6 contrôles réussissent, code de sortie 0.
La barrière pour les deux requêtes, avec les valeurs de python -m ops gate. La requête v3 échoue à chaque contrôle. La requête v2 réussit chaque contrôle et peut passer à un déploiement restreint.
Description textuelle du diagramme

La barrière lit deux entrées : les preuves hors ligne du cours sur l’évaluation et le fichier de limites. Elle exécute six contrôles en trois groupes. Les éléments bloquants : aucun billet critique ne peut échouer et aucune réponse ne peut être sans texte. La qualité : la borne inférieure de la différence doit être d’au moins −0,03. Chaque billet nécessitant une personne doit aussi être repéré. Les opérations : au plus 0,40 $ US par 1 000 billets et un p95 de triage d’au plus 8 secondes. La requête v3 échoue aux six contrôles. La requête v2 réussit les six et peut donc passer à un déploiement restreint.

Une barrière doit pouvoir dire oui, sinon personne ne lui fait confiance. Exécutez-la sur la requête v2, celle en production :

Fenêtre de terminal
python -m ops gate assistant-v2
Release gate for assistant-v2 (baseline assistant-v2), evidence: baseline-v2-chat-small-r1-b6a2b9 on the holdout split of d4c96eaa10c0
check value limit result detail
---------------------------------------------- ----- -------- ------ -----------------------
blockers (critical cases failed) 0 <= 0 pass none
answers without text (holdout) 0 <= 0 pass of 98 tickets
decisions: lower end of (candidate - baseline) 0.000 >= -0.03 pass +0.000 [+0.000, +0.000]
needs a person: share caught 1.000 >= 1.0 pass 24 of 24
cost per 1,000 tickets (US$) 0.339 <= 0.4 pass baseline 0.339
triage time p95 (s) 4.896 <= 8.0 pass baseline 4.896
Decision: SHIP to a canary (the canary's own checks come next: python -m ops canary)

Ici, la version candidate et la référence de base correspondent à la même exécution d’évaluation. La différence est donc exactement 0. Les autres contrôles sont réels : v2 n’a aucun élément bloquant, repère 24 billets sur 24 et respecte les limites de coût et de temps.

Regardez les derniers mots : DÉPLOYER auprès d’un groupe restreint. Les preuves hors ligne ne peuvent pas tout voir. Le jeu réservé contient 98 billets; Larkfield en reçoit 822 par jour. Un échec rare peut se cacher dans les autres. La barrière ouvre donc la prochaine porte, pas la dernière.

Ouvrez operations/gates.toml. Chaque limite vient d’une décision déjà prise par l’équipe, et chacune a un responsable :

Limite Valeur Origine Responsable
blockers_max, answers_without_text_max 0 le SLO de sécurité : chaque billet nécessitant une personne en atteint une Grace
decisions_difference_min −0,03 la marge acceptée par Priya : pas pire de plus de 3 points Priya
needs_human_recall_min 1,0 encore le SLO de sécurité Grace
cost_per_1000_usd_max 0,40 le budget de coût dans operations/slos.toml Kwame
latency_p95_s_max 8,0 l’alerte triage-slow : p95 supérieur à 8 s Amira

Écrivez les limites avant de voir les nombres de la version candidate. Si vous choisissez une limite après avoir vu le résultat, vous pouvez faire réussir n’importe quelle version candidate. Modifier gates.toml est un changement comme les autres : il faut une raison et une révision.

Tomás rappelle le cours sur l’évaluation à l’équipe. Un modèle juge y avait comparé les réponses et préféré celles de v3, plus chaleureuses, 126 fois contre 48. « Ça ne compte pas? »

Cela compte comme preuve sur le ton des réponses. Mais c’est une préférence moyenne, qui ne dit rien du billet de sécurité sans réponse. Une barrière ne compense pas les mauvaises nouvelles par les bonnes. Elle demande si chaque ligne réussit. La préférence du juge peut devenir une ligne d’une future barrière, avec sa propre limite. Elle ne peut jamais annuler un élément bloquant.

Sam demande : « On a besoin de la barrière pour chaque changement? »

Amira répond : « Pour chaque changement qui peut modifier une réponse. »

  • Utilisez la barrière pour une nouvelle requête, un modèle ou une version de modèle, un texte de politique, un schéma de sortie, une limite de jetons ou un index de récupération. Chacun reçoit un nouveau manifeste de version et nécessite de nouvelles preuves.
  • Les preuves doivent correspondre à la version. Des preuves d’une autre requête, d’un autre modèle ou d’un autre jeu d’évaluation ne décrivent pas cette version. La première ligne de la barrière nomme l’exécution, la partition et le jeu : lisez-les.
  • Une barrière ne remplace pas le déploiement restreint. Les 98 billets réservés repèrent les échecs importants et fréquents. Ils ne peuvent pas prouver l’absence d’un échec touchant 1 billet sur 1 000.

Ce qu’elle coûte : une exécution d’évaluation par version candidate. Les cinq exécutions de la requête v3 du cours sur l’évaluation ont coûté environ 0,33 $ US en appels au modèle. Les prix changent : consultez la page actuelle du fournisseur. Elle demande aussi de l’attention. Quelqu’un doit garder les billets réservés figés, les billets critiques répertoriés et les limites à jour. C’est peu coûteux comparé à deux jours de billets de sécurité sans réponse.

Erreur courante

ops gate : aucune preuve

Symptôme : python -m ops gate assistant-v4 se termine avec le code 2 :

ops gate: no evidence operations/evidence/assistant-v4.json: evaluate assistant-v4 first

Cause : aucune évaluation n’a été exécutée pour cette requête, donc il n’y a rien à juger.

Correction : exécutez l’évaluation. Enregistrez ensuite ses résultats dans operations/evidence/assistant-v4.json, avec les mêmes champs que assistant-v3.json. Un fichier manquant signifie « non », jamais « oui ».

Erreur courante

Les tests ou l'API s'arrêtent avec une erreur de paramètres

Symptôme : après la migration, python -m pytest et l’API s’arrêtent immédiatement avec un message comme celui-ci. Votre identifiant peut différer :

Settings error: RELEASE_ID 1.5.0-c7b614 does not match: migrations: the manifest ends with 019_answer_index.sql, the project with 020_release_state.sql

Cause : .env nomme encore un manifeste construit avant ce module. Le service refuse d’exécuter une version qui ne décrit pas ses fichiers.

Correction : faites les étapes 4 et 5 ci-dessus : construisez les nouveaux manifestes et réglez RELEASE_ID sur le nouvel identifiant v2.

Réinitialisation. Si votre projet ne fonctionne plus, copiez l’instantané end-of-m05, conservez votre .env et exécutez python -m scripts.load --reset. Le README des instantanés montre comment faire. Refaites ensuite les étapes 4 et 5.

Vérifiez votre compréhension

Nommez les trois types de preuves que la barrière de mise en production combine. Donnez une vérification de chacun dans ops gate.

Afficher la réponse

Blocages, ou échecs critiques : aucun billet critique ne doit échouer (la requête v3 a échoué pour T-65663). Qualité et incertitude : la borne inférieure de l’intervalle à 95 % de la différence doit être d’au moins −0,03 (v3 : −0,184). Limites opérationnelles : au plus 0,40 $ US par 1 000 billets (v3 : 0,480). Ou un p95 du triage d’au plus 8,0 s (v3 : 8,534 s).

Vérifiez votre compréhension

Prédisez : une version candidate dépasse v2 de 0,02 en moyenne, avec un intervalle à 95 % de −0,04 à +0,08. Toutes les autres vérifications réussissent. Que décide la barrière, et pourquoi?

Afficher la réponse

NE PAS METTRE EN PRODUCTION. La barrière lit la borne inférieure, −0,04, qui est sous la marge de −0,03. La différence réelle pourrait être de 4 points en moins, ce qui dépasse ce que l’équipe accepte. Plus de billets d’évaluation réduiraient la largeur de l’intervalle. La version candidate pourrait alors réussir.

Vérifiez votre compréhension

Vérification pratique : montrez que votre barrière bloque la requête v3 et accepte la requête v2. Quelles sorties et quels codes de sortie le prouvent?

Afficher la réponse

python -m ops gate assistant-v3 affiche six lignes FAIL (échec) et Decision: DO NOT SHIP (6 failed: …) (décision : ne pas mettre en production, six échecs). Le code de sortie est 1. python -m ops gate assistant-v2 affiche six lignes de réussite et Decision: SHIP to a canary … (décision : déployer sur un groupe canari…). Le code de sortie est 0. python -m pytest affiche 213 passed (213 tests réussis).

Récapitulatif

  • Une barrière d’évaluation (barrière de mise en production) transforme les preuves sur une version candidate en une seule décision. Un script l’applique au moyen du code de sortie.
  • Elle combine les blocages, la qualité et les limites opérationnelles. Un seul échec critique bloque la mise en production. La qualité compare la borne inférieure de l’intervalle à 95 % à une marge. Les limites couvrent le coût et la latence.
  • La requête v3 échoue aux six vérifications; la requête v2 les réussit toutes. Une réussite signifie « déployer sur un groupe canari », et non « déployer pour tout le monde ».
  • Les limites viennent des SLO et du budget, et ont des responsables. On les écrit avant que quiconque voie les chiffres de la version candidate.
  • Votre projet contient les fichiers du module et de nouveaux manifestes de mise en production pour v2 et v3. python -m pytest affiche 213 passed.

Ensuite, le déploiement canari : la requête v3 sur 10 % des billets, la règle qui la bloque et la preuve du retour arrière réussi.

Leçon suivante : Déploiements contrôlés