Aller au contenu
English

Lignée des artefacts

  • Leçon 5
  • 55 min
  • Module 2 : Versionner et reproduire le système

Où nous en sommes

Dans le module 1, nous avons listé ce que nous exploitons, fixé des objectifs et donné un responsable à chaque partie. Mais la semaine dernière, personne ne pouvait même dire quels billets avaient reçu une réponse avec la requête v3. Dans cette leçon, nous donnons à chaque réponse un identifiant de version qui remonte à toutes les versions qui l'ont produite, comme le numéro de lot sur un pot de yogourt.

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

Ce que vous saurez faire

Pour toute réponse du service, retrouvez les versions exactes du code, de la base de données, de la requête, du modèle et des données utilisées. Sans ce lien, une mauvaise semaine vous laisse des plaintes, sans moyen de savoir quel changement les a causées.

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 1, ou une copie de l’instantané end-of-m01. python -m pytest affiche 185 passed (185 tests réussis).
  • Docker exécutant PostgreSQL, Azurite et Valkey (docker compose up -d db azurite cache), Python 3.12 ou plus récent, VS Code et quatre terminaux.
  • Le dépôt des exercices dans ~/projects/nextia-learning-labs, pour la télémétrie enregistrée et les manifestes du cours.

Aucun compte, aucune clé et aucuns frais. Les étapes qui lisent les fichiers enregistrés ne nécessitent pas Docker.

Regardez le couvercle d’un pot de yogourt. À côté de la date, un code court apparaît, par exemple L2318B. C’est le numéro de lot. Vous ne le lisez jamais, et l’usine espère que vous n’en aurez jamais besoin.

Imaginez maintenant une mauvaise semaine à l’usine. Des clients tombent malades après avoir mangé le même yogourt. L’usine lit le numéro sur un pot et retrouve tout ce qui a servi à ce lot : la livraison de lait, la version de la recette, la machine. Elle rappelle seulement ce lot et sait quel changement annuler.

Sans ce numéro, l’usine sait seulement que « du yogourt était mauvais la semaine dernière ». Elle doit tout rappeler et deviner la cause.

Le service de soutien de Larkfield a vécu ce genre de semaine.

Vous connaissez l’histoire grâce à Faire tourner le service en production. Pendant environ deux jours, des clients ont attendu des réponses à leurs billets de soutien concernant la sécurité, sans que personne le remarque. Le SLI d’acceptation est resté à 100,00 %. Mais le SLI de rédaction est tombé à 91,79 %. Dix billets qui exigeaient une intervention humaine n’ont atteint personne.

Dans ce cours, vous étudiez cette semaine comme une reconstitution de l’incident pour vous exercer; les réponses sont de vrais enregistrements. La cause était un seul changement de paramètre sur le serveur : ASSISTANT_PROMPT=assistant-v3. La requête v3 est la candidate testée dans le cours sur l’évaluation, et son évaluation indiquait NE PAS METTRE EN PRODUCTION. Personne n’a créé de version, exécuté de barrière ou essayé la requête sur quelques billets d’abord.

Après cette semaine, Grace pose trois questions à Amira :

  1. « Quelles réponses venaient de la nouvelle requête, et depuis quand? »
  2. « Était-ce la même requête que Priya avait testée, ou une copie modifiée? »
  3. « Qu’est-ce qui a changé en même temps : le code, la base de données, le modèle? »

Amira ouvre la base de données. Chaque ligne de ai_runs contient une colonne prompt_version, et les lignes récentes indiquent assistant-v3. Cela répond en partie à la question 1. Rien ne répond au reste :

  • assistant-v3 est un nom de fichier. N’importe qui peut modifier le fichier et garder son nom. La ligne ne permet pas de savoir quel texte a été envoyé.
  • La ligne ne précise ni le code, ni les migrations, ni la version du modèle. Le fournisseur peut changer son modèle sans changer son nom.
  • Rien ne relie la requête à l’évaluation de Priya ou à son résultat. Les preuves indiquant NE PAS METTRE EN PRODUCTION étaient dans un autre projet, et le serveur n’en savait rien.

Amira peut donc dire « certaines réponses utilisaient quelque chose appelé v3 ». Elle ne peut pas dire exactement ce qui les a produites, ni si quelqu’un l’a approuvé. C’est l’usine sans numéros de lot.

L’idée : un registre de toutes les versions, et son identifiant sur chaque résultat

Section intitulée « L’idée : un registre de toutes les versions, et son identifiant sur chaque résultat »

Les réponses du service dépendent de plusieurs éléments que des personnes créent et modifient. Le code, l’image du conteneur, les migrations de la base de données, les fichiers de requêtes, le modèle, l’index de recherche et le jeu d’évaluation sont tous des artefacts. Un artefact est un fichier, ou un ensemble de fichiers, dont dépend le comportement du service et qui possède des versions.

La lignée est le chemin enregistré qui relie un résultat à tout ce qui l’a produit : les artefacts et l’entrée. Elle répond à « d’où cela vient-il? », comme le numéro de lot du yogourt.

Le projet obtient une lignée en deux étapes :

  1. Un manifeste de version : un petit fichier qui énumère la version exacte de chaque artefact d’une version du service. Le manifeste d’un navire énumère sa cargaison; celui-ci énumère le contenu de la version.
  2. Un identifiant de version sur chaque résultat. Le service lit son manifeste au démarrage et inscrit son identifiant à côté de chaque résultat d’IA qu’il produit.

Le chemin est alors court : réponse, identifiant de version, manifeste, chaque version.

La lignée est un élément central des MLOps et LLMOps, le travail nommé dans Faire tourner le service en production. Les grandes équipes utilisent souvent un registre de modèles, un service qui conserve les versions des modèles et leurs registres. Ce cours n’utilise aucun produit de registre. Les manifestes dans operations/releases/ jouent ce rôle, et vous pouvez les lire avec un éditeur de texte.

Un petit exemple : comment créer un identifiant de version

Section intitulée « Un petit exemple : comment créer un identifiant de version »

Un identifiant de version doit changer quand un élément du manifeste change. Il doit aussi rester identique si rien ne change, pour que deux personnes obtiennent le même identifiant pour la même version.

Une empreinte de hachage fait les deux. Vous l’avez vue dans Étiqueter et versionner : SHA-256 transforme n’importe quel texte en 64 caractères. Le même texte donne toujours les mêmes 64 caractères. Un changement d’un seul caractère donne un résultat complètement différent.

Prenez un manifeste contenant trois valeurs : la version du code, la requête et la version du modèle. Écrivez-le comme un seul texte, avec les clés dans un ordre fixe. Calculez son empreinte et gardez les 6 premiers caractères. Exécutez cet exemple :

Exécutez du Python dans votre navigateur

Créer un identifiant de version à partir de trois versions

L’encadré affiche le texte, son SHA-256 et l’identifiant de version 1.5.0-6a704e. Retirez le # devant manifest["prompt"] = "assistant-v3" et exécutez-le de nouveau. L’identifiant devient 1.5.0-9873bb. Une valeur a changé, donc l’identifiant entier a changé.

La sortie, avec toutes les valeurs :

{"code": "1.5.0", "model": "gpt-6-luna-2026-09-22", "prompt": "assistant-v2"}
6a704ee33487fba391ec1a958a4bd2d497debf13cbe78fa0a7efb749a45c6b82
release ID: 1.5.0-6a704e

Pourquoi trier les clés? Python écrit un dictionnaire dans l’ordre où vous l’avez créé. Deux personnes pourraient écrire le même manifeste dans un ordre différent et obtenir deux identifiants. Avec sort_keys=True, le texte dépend seulement des valeurs.

Pourquoi seulement 6 caractères? Une personne doit pouvoir lire l’identifiant dans un journal et le dire pendant un appel. Six caractères donnent environ 16 millions de valeurs, assez pour les versions d’un service.

Un flux de gauche à droite. Les sections du manifeste (code, base de données, assistant, modèle, récupération, données, paramètres) deviennent un seul texte JSON aux clés triées. Le SHA-256 de ce texte commence par 4fafd1 et compte 64 caractères. Les 6 premiers caractères donnent l'identifiant de version 1.5.0-4fafd1. En dessous, un chemin pointillé : changez une valeur, la requête assistant-v3, et les mêmes sections donnent un nouvel identifiant, 1.5.0-767b56.
Le vrai manifeste du projet fonctionne comme le petit exemple, avec sept sections plutôt que trois valeurs.
Description textuelle du diagramme

Le vrai manifeste compte sept sections : code, base de données, assistant, modèle, récupération, données et paramètres. Le projet les écrit comme un seul texte JSON aux clés triées et calcule son empreinte avec SHA-256. L’empreinte de la version du cours avec la requête v2 commence par 4fafd1, donc son identifiant est 1.5.0-4fafd1. Le même manifeste avec la requête assistant-v3 donne une autre empreinte, et son identifiant est 1.5.0-767b56.

Voici le manifeste de la version qui utilisait la requête v2 dans chaque scénario enregistré de ce cours. Il se trouve dans data/releases/1.5.0-4fafd1.toml, dans le dépôt des exercices. TOML est un format simple de paramètres : des lignes [section], puis des lignes name = value.

# A release manifest: every version that makes this release's answers.
# Written by python -m ops release build. Do not edit: a change makes a new release.
id = "1.5.0-4fafd1"
[code]
version = "1.5.0"
commit = "none (the project folder is not a Git repository)"
fingerprint = "c8ee0759e085"
image = "not built (the course runs the service with Python)"
[database]
migrations = 20
last_migration = "020_release_state.sql"
[assistant]
prompt = "assistant-v2"
prompt_fingerprint = "82a15031e521"
schema = "ticket_analysis"
schema_fingerprint = "f66acdf35fe1"
max_completion_tokens = 1000
[model]
deployment = "chat-small"
expected_version = "gpt-6-luna-2026-09-22"
embedding = "embed-small-384-v1"
[retrieval]
answer_prompt = "answer-v1"
search = "PostgreSQL full-text search, the 2 best documents"
index_version = "75cf862216c3"
[data]
evaluation_set = "d4c96eaa10c0"
evaluation_inputs = "3f90ab808275"
evidence = "baseline-v2-chat-small-r1-b6a2b9"
[settings]
BREAKER_FAILURES = "5"
INTAKE_MODE = "queue"
JOB_MAX_ATTEMPTS = "5"
PROVIDER_TIMEOUT = "10"
QUEUE_MAX = "5000"

Ce manifeste appartient au projet de fin de cours, donc il énumère 20 migrations et une version d’index. À cette étape, votre projet compte 16 migrations, et vous construisez son propre manifeste ci-dessous.

Trois colonnes. À gauche, l'origine de chaque partie : le commit Git et les fichiers de code; les migrations; le fichier de requête, la politique et le schéma; le déploiement et le modèle du fournisseur; l'index de recherche des réponses; le jeu d'évaluation et l'exécution d'évaluation enregistrée; les variables d'environnement qui changent le comportement. Chaque partie pointe vers sa section du manifeste au centre : code (version 1.5.0, commit, empreinte c8ee0759e085, empreinte d'image), database (20 migrations, dernière 020_release_state.sql), assistant (requête assistant-v2, empreinte 82a15031e521, schéma f66acdf35fe1, 1 000 jetons), model (déploiement chat-small, modèle attendu gpt-6-luna-2026-09-22), retrieval (answer-v1, index 75cf862216c3), data (jeu d4c96eaa10c0, preuves de l'exécution de référence v2), settings (INTAKE_MODE queue, PROVIDER_TIMEOUT 10 et 3 autres). En haut du manifeste figure son identifiant, 1.5.0-4fafd1. À droite, les destinations de l'identifiant : ai_runs.release_id, l'en-tête X-Release-ID, les segments et événements de télémétrie, les tableaux de bord. Un encadré en tirets, python -m ops trace TICKET, pointe d'une réponse vers le manifeste.
Le manifeste de version relie chaque partie du système. Son identifiant accompagne chaque résultat, donc toute réponse permet de le retrouver.
Description textuelle du diagramme

À gauche se trouvent les sources : le code et son commit Git, les migrations, les fichiers de requêtes et le déploiement du fournisseur. En dessous figurent l’index de recherche, le jeu d’évaluation avec son exécution enregistrée et les paramètres de comportement. Chaque source alimente une section du manifeste au centre. En haut du manifeste figure son identifiant, 1.5.0-4fafd1. À droite, l’identifiant va à quatre endroits. Ce sont chaque ligne de ai_runs, l’en-tête X-Release-ID, la télémétrie du module 3 et les tableaux de bord du module 5. Une flèche en tirets montre le retour : python -m ops trace part d’une réponse et arrive à ce manifeste.

Lisez les sections une à la fois :

  • [code] : l’empreinte est calculée à partir des fichiers Python dans ticket_api/ et simulator/. Elle détecte un fichier modifié sans nouveau commit (enregistrement des changements). Le dossier du projet du cours n’est pas un dépôt Git, donc commit l’indique.
  • [database] : le code et la base de données doivent correspondre. Une version qui attend la migration 016 ne peut pas fonctionner avec une base de données arrêtée à 015.
  • [assistant] et [model] : la requête, le schéma, le nom du déploiement et la version du modèle attendue derrière ce nom. Configuration propre aux LLM les examine de près.
  • [retrieval] : comment les réponses aux questions trouvent leurs documents. Le module 4 ajoute l’index.
  • [data] : le jeu d’évaluation et l’exécution enregistrée qui justifient cette version. C’est la lignée des données : les preuves accompagnent la version.
  • [settings] : les variables d’environnement qui changent ce que le service fait d’un billet. La construction les lit dans l’interpréteur de commandes, pas dans .env.

Les mots de passe, les clés et les adresses n’y figurent pas. Ils indiquent où la version s’exécute, pas ce qu’elle est.

L’instantané end-of-m02 contient les fichiers des trois leçons de ce module. Copiez-les, appliquez la migration et construisez votre premier manifeste.

  1. Dans un terminal, allez dans votre projet et activez l’environnement virtuel. Si data/telemetry manque, copiez la télémétrie enregistrée et les manifestes du cours depuis le dépôt des exercices.

    Fenêtre de terminal
    cd ~/projects/ticket-api
    source .venv/bin/activate
    ls data/telemetry || cp -R ../nextia-learning-labs/C25/data/telemetry ../nextia-learning-labs/C25/data/releases data/

    data/releases contient les deux manifestes du cours, 1.5.0-4fafd1.toml et 1.5.0-767b56.toml.

  2. Copiez les fichiers de ce module depuis l’instantané end-of-m02. Sept fichiers sont nouveaux et onze changent.

    Fenêtre de terminal
    S=../nextia-learning-labs/C25/snapshots/end-of-m02
    mkdir -p operations/experiments .github/workflows
    for f in migrations/016_release_ids.sql ticket_api/releases.py ticket_api/config.py \
    ticket_api/intake.py ticket_api/main.py ticket_api/repository.py ticket_api/worker.py \
    ops/cmd_release.py ops/cmd_trace.py ops/cmd_experiments.py ops/telemetry.py \
    operations/experiments/EXP-001-prompt-v3.toml tests/test_releases.py \
    .env.example Dockerfile .dockerignore .github/workflows/release.yml README.md; do
    cp "$S/$f" "$f"
    done
  3. Appliquez la nouvelle migration. Elle ajoute une colonne, ai_runs.release_id, et conserve vos données.

    Fenêtre de terminal
    python -m ticket_api.migrate
    applied 016_release_ids
    Database is up to date (16 migrations).
  4. Exécutez les tests. Attendez-vous à 193 passed, 1 deselected (193 tests réussis, 1 non sélectionné), soit 8 de plus qu’avant :

    Fenêtre de terminal
    python -m pytest
  5. Construisez le manifeste de votre projet avec la requête v2 et enregistrez-le. --evidence désigne l’exécution d’évaluation qui justifie cette requête : l’exécution de référence du cours sur l’évaluation.

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

    La commande affiche le manifeste, puis l’endroit où elle l’a enregistré. La dernière ligne :

    Saved operations/releases/1.5.0-99b6da.toml. Run the service with RELEASE_ID=1.5.0-99b6da

    Votre identifiant est 1.5.0-99b6da si vos fichiers sont exactement ceux de l’instantané. Si votre projet est un dépôt Git ou qu’un fichier diffère, votre identifiant diffère aussi. Cela inclut, par exemple, ses fins de ligne sous Windows. C’est correct : il s’agit d’une autre version.

  6. Ouvrez .env. À la fin, ajoutez la ligne affichée par la commande. Utilisez votre propre identifiant s’il est différent.

    Fenêtre de terminal
    RELEASE_ID=1.5.0-99b6da
Fichier Son rôle
ticket_api/releases.py Construit un manifeste, l’écrit en TOML, le lit et le vérifie par rapport aux fichiers. CURRENT contient l’identifiant de version de la requête ou de la tâche en cours.
ticket_api/config.py Avec RELEASE_ID défini, le service lit operations/releases/<ID>.toml au démarrage. Il prend la requête dans le manifeste. Il refuse de démarrer si la requête ou les migrations ne correspondent pas.
migrations/016_release_ids.sql La colonne ai_runs.release_id, avec un index. Les anciennes lignes gardent NULL.
ticket_api/intake.py, worker.py, main.py, repository.py Ajoutent l’identifiant de version à chaque résultat d’IA et l’en-tête X-Release-ID à chaque réponse de l’API.
ops/cmd_release.py python -m ops release build, list, show, diff et verify.
ops/cmd_trace.py python -m ops trace : remonte d’une réponse à ses versions et à son entrée.
ops/cmd_experiments.py, operations/experiments/ Les registres des expériences, pour Registre des expériences.
.github/workflows/release.yml Le flux de mise en production construit maintenant le manifeste avec l’empreinte d’image et le commit, puis le joint à la version GitHub. Ce cours ne l’exécute pas.
Dockerfile, .dockerignore L’image contient maintenant operations/, pour qu’un conteneur puisse lire son manifeste.

Démarrez les trois processus comme dans Faire tourner le service en production. Utilisez un terminal pour chacun, avec l’environnement virtuel actif :

Fenêtre de terminal
python -m simulator
fastapi dev
python -m ticket_api.worker

Dans un quatrième terminal, envoyez un billet et regardez les en-têtes. Sous Windows, tapez curl.exe plutôt que curl, et placez la commande sur une seule ligne sans le \.

Fenêtre de terminal
curl -i -X POST http://127.0.0.1:8000/v1/tickets -H "Content-Type: application/json" \
-d '{"customer_id": "C-0022", "subject": "Charged twice", "body": "Two payments for one order."}'

L’exécution de l’auteur a affiché ceci. Vos dates, heures, identifiants et numéro de billet seront différents :

HTTP/1.1 202 Accepted
date: Sun, 11 Oct 2026 07:56:27 GMT
server: uvicorn
content-length: 125
content-type: application/json
location: /v1/jobs/1
server-timing: rate_limit;dur=3.2, db;dur=8.4
x-request-id: 048459a68d5f
x-release-id: 1.5.0-99b6da
{"ticket_id":"T-500001","job_id":1,"state":"queued","status_url":"/v1/jobs/1","queued_ahead":0,"estimated_wait_seconds":null}

L’en-tête x-release-id indique la version. Tout client, toute ligne de journal et toute personne du soutien peuvent maintenant le citer.

Envoyez maintenant cinq billets d’exercice et regardez ce que le processus a enregistré :

Fenêtre de terminal
python -m scripts.practice --tickets 5 --rate 2
docker compose exec db psql -U tickets -c "SELECT ticket_id, task, prompt_version, finish_reason, release_id FROM ai_runs WHERE created_at > now() - interval '10 minutes' ORDER BY run_id"

Après quelques secondes, le processus a traité les six billets : votre billet curl et les cinq billets d’exercice. Chacun possède deux résultats d’IA, le triage et le plongement (embedding) :

ticket_id | task | prompt_version | finish_reason | release_id
-----------+--------+----------------+---------------+--------------
T-500001 | triage | assistant-v2 | stop | 1.5.0-99b6da
T-500001 | embed | | | 1.5.0-99b6da
T-500002 | triage | assistant-v2 | stop | 1.5.0-99b6da
T-500002 | embed | | | 1.5.0-99b6da
T-500003 | triage | assistant-v2 | stop | 1.5.0-99b6da
T-500004 | triage | assistant-v2 | stop | 1.5.0-99b6da
T-500004 | embed | | | 1.5.0-99b6da
T-500003 | embed | | | 1.5.0-99b6da
T-500006 | triage | assistant-v2 | stop | 1.5.0-99b6da
T-500006 | embed | | | 1.5.0-99b6da
T-500005 | triage | assistant-v2 | stop | 1.5.0-99b6da
T-500005 | embed | | | 1.5.0-99b6da
(12 rows)

Le processus exécute jusqu’à quatre tâches à la fois, et elles se terminent dans n’importe quel ordre. Vos lignes peuvent apparaître dans un autre ordre. Comptez maintenant toutes les lignes par version :

Fenêtre de terminal
docker compose exec db psql -U tickets -c "SELECT release_id, prompt_version, count(*) FROM ai_runs GROUP BY 1, 2 ORDER BY 1, 2"
release_id | prompt_version | count
--------------+----------------+-------
1.5.0-99b6da | assistant-v2 | 6
1.5.0-99b6da | | 6
| draft-v2 | 94
| | 200
(4 rows)

Chaque nouveau résultat d’IA porte 1.5.0-99b6da. Les 294 lignes du petit jeu de données, créées avant la définition de RELEASE_ID, ont un release_id vide. Avez-vous envoyé des billets dans le module 1 sans réinitialiser ensuite? Vous voyez alors aussi leurs lignes sans identifiant de version : une ligne avec assistant-v2 et d’autres lignes vides. Vous ne pouvez pas leur ajouter une lignée après coup. C’est pourquoi l’identifiant doit être en place avant le prochain changement, pas après.

Arrêtez l’API et le processus avec Ctrl+C. Gardez le simulateur en marche si vous passez à la prochaine leçon aujourd’hui.

La télémétrie enregistrée de la « semaine dernière » rejouée contient l’identifiant de version sur chaque billet. Le module 3 montre comment le service écrit la télémétrie; ici, vous la lisez seulement. Prenez le billet T-503354, un des billets de sécurité restés sans réponse :

Fenêtre de terminal
python -m ops trace T-503354 data/telemetry/release-full.jsonl.gz --releases data/releases
Ticket T-503354
input received +7.9 min, request 8b8ed4e114fc, channel web_form, 292 characters, language guess en
message fingerprint 3f8c9237238c5e1d = practice ticket T-65663 (made up for the evaluation course; split holdout, slice needs_person)
result no_answer after 9.201 s: team None, needs a person None, finish length, 1495 tokens in, 1000 out, US$0.000650
answered by gpt-6-luna-2026-09-22 (replayed), prompt assistant-v3, trace 62bdee6f5950708a65de0362c9584db4
release 1.5.0-767b56 (data/releases/1.5.0-767b56.toml)
code 1.5.0, commit none (the project folder is not a Git repository), fingerprint c8ee0759e085
image not built (the course runs the service with Python)
migrations 20, last 020_release_state.sql
prompt assistant-v3 (fingerprint e91df8e7a92a), schema ticket_analysis (f66acdf35fe1), at most 1000 tokens
model chat-small, expected version gpt-6-luna-2026-09-22, embeddings embed-small-384-v1
retrieval answer-v1, index 75cf862216c3
evaluation set d4c96eaa10c0 (inputs 3f90ab808275), evidence candidate-v3-chat-small-r1-31b45f

Lisez-le en trois blocs :

  • input (entrée) : la provenance de l’entrée, son origine. L’outil n’affiche jamais le texte du client. L’empreinte du message correspond au billet d’exercice T-65663 : la poêle brûlante et fissurée du cours sur l’évaluation.
  • result (résultat) : finish length signifie que le modèle a utilisé les 1 000 jetons sans écrire de réponse. Il n’a donc indiqué ni équipe ni besoin d’une personne.
  • release (version publiée) : chaque version ayant produit cette réponse. La preuve est candidate-v3-chat-small-r1-31b45f : l’exécution dont la décision était DO NOT SHIP (ne pas mettre en production).

La première question de Grace a maintenant une réponse exacte : chaque billet dont le résultat indique 1.5.0-767b56. La prochaine leçon répond aux deux autres à partir des manifestes.

Un flux. Le billet T-503354, sans réponse, avec finish length, pointe vers son résultat de triage avec release.id 1.5.0-767b56. Celui-ci pointe vers le manifeste de version 1.5.0-767b56.toml. Le manifeste pointe vers la requête assistant-v3 avec l'empreinte e91df8e7a92a, le modèle chat-small avec la version attendue gpt-6-luna-2026-09-22 et la preuve candidate-v3-chat-small-r1-31b45f. La preuve pointe vers le registre d'expérience EXP-001 avec la décision do not ship, entourée d'une bordure épaisse. Le billet pointe aussi vers son entrée : l'empreinte de message 3f8c9237238c5e1d, qui correspond au billet d'exercice T-65663.
La lignée d'une réponse. L'identifiant de version mène au manifeste. Le manifeste mène à la requête, au modèle et à la preuve indiquant de ne pas mettre en production.
Description textuelle du diagramme

Le billet T-503354 n’a reçu aucune réponse. Son résultat de triage porte l’identifiant de version 1.5.0-767b56. Cet identifiant ouvre le manifeste. Le manifeste nomme la requête assistant-v3 avec son empreinte, le modèle avec sa version attendue et la preuve. Cette preuve est l’exécution candidate du cours sur l’évaluation. Elle mène au registre d’expérience EXP-001, dont la décision était « ne pas mettre en production ». De l’autre côté, l’empreinte du message montre que l’entrée était le billet d’exercice T-65663.

L’identifiant de version permet aussi au tableau de bord de séparer chaque nombre par version. Le module 5 rejoue le même changement comme déploiement canari : la requête v3 pour 10 % des billets. Le tableau des versions de Grafana pour cet exercice montre les deux versions côte à côte :

Un tableau Grafana intitulé Releases over the time range (versions durant la période). Deux lignes. Version 1.5.0-4fafd1 : 2 384 billets, sans réponse 0,1 %, transmis à une personne 25,9 %, $ US par 1 000 : 0,341, délai avant une ébauche p95 : 6,795 s. Version 1.5.0-767b56 : 25 billets, sans réponse 12,0 %, transmis à une personne 27,3 %, $ US par 1 000 : 0,449, délai avant une ébauche p95 : 9,643 s.
Le déploiement canari d'exercice du module 5 dans Grafana : chaque ligne correspond à un identifiant de version. Sans l'identifiant sur chaque résultat, ce tableau ne pourrait pas exister. L’image est en anglais.

Chaque résultat porte un identifiant de version, donc le tableau de bord les regroupe par identifiant. Seulement 25 billets de la version 1.5.0-767b56 ont suffi pour montrer 12,0 % sans réponse, contre 0,1 % pour 1.5.0-4fafd1.

Sam demande : « On a déjà Git. Le commit ne suffit pas? »

Amira répond : « Le commit identifie le code. Il n’identifie pas la version du modèle que le fournisseur exécute, la base de données ou le réglage du serveur. Il n’identifie pas non plus l’évaluation qui l’a approuvé. Le changement de la semaine dernière était un réglage, sans aucun commit. »

Utilisez un manifeste pour tout service dont le comportement dépend d’autre chose que son code : modèle, requête, jeu de données ou index. Un outil l’écrit à la mise en production, jamais une personne à la main. Ajoutez son identifiant à chaque résultat sur lequel quelqu’un pourrait poser des questions plus tard.

Vous n’en avez peut-être pas besoin pour un petit script exécuté une seule fois, ou un prototype dont personne ne dépend. Dans ce cas, un commit (enregistrement des changements) Git dans une ligne de journal suffit.

Ce qu’il coûte :

  • Une colonne, un en-tête et 12 caractères dans chaque ligne de journal.
  • De la discipline. Chaque changement à un artefact répertorié exige un nouveau manifeste et un nouvel identifiant. Une correction rapide « juste sur le serveur » enfreint la règle. C’est le but, mais les gens trouvent cela contraignant.
  • Un manifeste vaut ce que vaut sa liste. Si le service dépend d’un élément absent du manifeste, la lignée s’arrête là. Révisez la liste quand vous ajoutez une dépendance.

Erreur courante

Le processus s'arrête immédiatement : aucun manifeste de version

Symptôme : après avoir défini RELEASE_ID, le processus s’arrête avec une erreur comme celle-ci. L’API ne démarre pas non plus :

Settings error: RELEASE_ID: no release manifest operations/releases/1.5.0-abcdef.toml

Cause : RELEASE_ID nomme un manifeste absent de operations/releases/. Vous avez fait une faute de frappe ou créé le manifeste sans --write.

Diagnostic : python -m ops release list montre les manifestes existants.

Correction : copiez exactement l’identifiant fourni par ops release list, ou recréez le manifeste avec --write. Pour exécuter sans version, laissez RELEASE_ID= vide. Les nouvelles lignes n’auront alors aucun identifiant de version.

Erreur courante

ops trace ne trouve pas le manifeste

Symptôme : python -m ops trace T-503354 data/telemetry/release-full.jsonl.gz affiche l’entrée et le résultat, puis s’arrête :

ops trace: no release manifest operations/releases/1.5.0-767b56.toml

Cause : sans --releases, l’outil cherche dans le dossier operations/releases/ de votre projet. Les manifestes du cours sont dans data/releases/.

Correction : ajoutez --releases data/releases. Dans un vrai projet, conservez chaque manifeste ayant servi en production. Supprimer un manifeste rompt la lignée de chaque réponse qu’il a produite.

Réinitialisation. Si votre projet ne fonctionne plus, copiez l’instantané end-of-m02, conservez votre .env et exécutez python -m scripts.load --reset. Suivez les indications du README des instantanés.

Vérifiez votre compréhension

La semaine dernière, ai_runs contenait déjà prompt_version = 'assistant-v3'. Nommez deux questions auxquelles cette colonne ne pouvait pas répondre. Dites ce que le manifeste ajoute pour chacune.

Afficher la réponse

Premièrement : « Est-ce bien la requête qui a été testée? » La colonne contient un nom de fichier. N’importe qui peut modifier le fichier en gardant son nom. Le manifeste ajoute l’empreinte de la requête, un hachage du texte envoyé. Deuxièmement : « Qu’est-ce qui a changé d’autre? » La colonne ne dit rien sur le code, les migrations ou la version du modèle. Le manifeste les nomme tous. Une troisième bonne réponse : « Est-ce que cela a été approuvé? » La ligne de preuve du manifeste renvoie à l’exécution d’évaluation, et donc à sa décision.

Vérifiez votre compréhension

Prédisez : dans votre interpréteur de commandes, vous définissez PROVIDER_TIMEOUT=12 et recréez le manifeste. L'identifiant de version change-t-il? Pourquoi est-ce important?

Afficher la réponse

Oui. PROVIDER_TIMEOUT fait partie des réglages de comportement que l’outil de création lit dans l’interpréteur de commandes. La section [settings] change, donc le hachage et l’identifiant changent aussi. C’est important, car un délai d’expiration change ce que les clients reçoivent. Dans la reprise, une réponse v3 a pris 12,1 s. Avec un délai d’expiration de 10 s, ce billet est devenu un message non traité. Deux versions aux comportements différents doivent avoir deux identifiants.

Vérifiez votre compréhension

Vérification pratique : montrez que votre service ajoute l'identifiant de version à ses résultats. Quelles sorties le prouvent?

Afficher la réponse

python -m pytest affiche 193 passed (193 tests réussis). La création avec --write enregistre operations/releases/1.5.0-99b6da.toml, ou votre propre identifiant. Avec RELEASE_ID dans .env, curl -i montre x-release-id: 1.5.0-99b6da. Les nouvelles lignes de ai_runs ont ce release_id. Les lignes créées avant n’en ont aucun.

Récapitulatif

  • Un artefact est un élément versionné dont dépend le comportement du service : code, image, migrations, requêtes, modèle, index, données d’évaluation. La lignée est le chemin qui relie un résultat à tous ces éléments et à son entrée.
  • Un manifeste de version liste la version exacte de chaque artefact. Son identifiant de version combine la version du code et les 6 premiers caractères d’un hachage du manifeste. Tout changement produit donc un nouvel identifiant.
  • Le service lit son manifeste au démarrage (RELEASE_ID). L’identifiant figure sur chaque résultat d’IA et chaque réponse de l’API.
  • python -m ops trace remonte d’une réponse à ses versions et à la provenance de son entrée. Pour le billet T-503354 rejoué, il aboutit à la preuve indiquant de ne pas mettre en production.
  • Votre projet crée son propre manifeste, 1.5.0-99b6da, et python -m pytest affiche 193 passed.

Ensuite, vous examinez la partie IA du manifeste. Pourquoi le nom d’une requête n’est-il pas sa version? Et que peut changer le fournisseur sans vous prévenir?

Leçon suivante : Configuration propre aux LLM