Flux de données et d'identité
- Leçon 6
- 55 min
- Module 2 : Concevoir l'architecture de bout en bout
Où nous en sommes
Dans la leçon précédente, nous avons divisé l'assistant en huit parties et nous les avons dessinées sur un diagramme. Mais les données circulent entre ces parties, et une partie qui oublie le locataire peut mélanger les données de deux boutiques sans aucun message d'erreur. Dans cette leçon, nous suivons le locataire, le rôle et la version du document dans chaque requête et chaque tâche en arrière-plan, comme l'étiquette d'une valise à l'aéroport.
Leçon 6 sur 19 · Conception de systèmes d'IA et maîtrise des coûtsFlux de données et d'identité
1. Commencer par les besoins
2. Concevoir l'architecture de bout en bout
3. Estimer les ressources et le coût
4. Optimiser avec des compromis mesurés
5. Concevoir pour les défaillances et la croissance
6. Présenter la proposition
Ce que vous saurez faire
Suivez le locataire, le rôle de la personne, la version du document et la réponse dans chaque requête et tâche en arrière-plan. Une partie de la conception qui les oublie peut mélanger les données de deux commerces sans aucun message d’erreur.
Avant de commencerCe qu’il faut savoir et avoir sous la main
Ce que vous devez savoir
- Les huit parties de la conception et le diagramme de conteneurs, vus dans Limites des services.
- La sécurité au niveau des lignes : la base de données refuse les lignes d’un autre locataire. Voir Requêtes sûres pour chaque locataire dans Authentification, autorisations et applications multilocataires.
- Une tâche qui enregistre qui l’a demandée et pour quel locataire. Voir Contexte d’identité des tâches dans le même cours.
- Les étiquettes d’accès (
publicpour le public oustaffpour le personnel) sur chaque segment. Voir Autorisations et isolation dans RAG : créer une IA qui utilise vos données. - Une clé de cache qui contient tout ce qui change la réponse. Voir Clés et invalidation dans Mettre à l’échelle les API et les charges de travail d’IA.
Ce qu’il vous faut sur votre ordinateur
- Votre dossier de la dernière leçon :
python -m pytest -qaffiche2 failed, 14 passed(2 échecs, 14 réussites). - Un moyen de voir un diagramme Mermaid. GitHub affiche les blocs Mermaid dans les fichiers Markdown. mermaid.live dessine un bloc collé dans le navigateur, sans compte. Dans VS Code, une extension d’aperçu Mermaid convient aussi.
Une étiquette sur chaque valise
Section intitulée « Une étiquette sur chaque valise »À l’aéroport, vous enregistrez une valise. Le comptoir y appose une étiquette avec votre nom, votre vol et votre destination. La valise voyage ensuite seule, sur des convoyeurs, dans des scanners et sur des chariots. Personne sur son trajet ne vous connaît. Ces personnes lisent l’étiquette.
L’étiquette doit suivre la valise tout le long du trajet. Une valise sans étiquette s’arrête au premier convoyeur. Une valise avec la mauvaise étiquette arrive dans la mauvaise ville. Personne ne le remarque avant que vous l’ouvriez. La compagnie aérienne garde aussi une trace : quelle valise a pris quel vol, pour répondre aux questions plus tard.
Le problème : le locataire se perd en chemin
Section intitulée « Le problème : le locataire se perd en chemin »Le diagramme de conteneurs montre quelles parties communiquent entre elles. Il ne montre pas ce que chaque message transporte. Voici deux façons dont l’assistant partagé peut perdre son étiquette. Ce sont deux cas construits pour montrer la défaillance, et non des exécutions du projet.
Le cache sans locataire. Tomás propose un cache de réponses simple : la clé est la question. À 10 h, un agent de Larkfield demande : « Combien de jours ai-je pour retourner un article? » L’assistant répond à partir de la politique de retour de Larkfield, avec des citations, puis enregistre la réponse. À 10 h 20, une cliente de Bramble Books pose exactement la même question. La clé correspond. Le cache renvoie la réponse de Larkfield, avec les citations de Larkfield. C’est rapide : le cours sur la mise à l’échelle a mesuré un accès réussi au cache d’environ 0,014 s, avec Valkey. Il n’y a aucune erreur ni aucune ligne suspecte dans les journaux. La cible de qualité Q3 est enfreinte en silence : « aucun locataire ne voit jamais un document ou une réponse d’un autre locataire ».
La réponse sans ses versions. Ines modifie les conditions des fournisseurs de Bramble Books : la version 5 remplace la version 4. Une semaine plus tard, un fournisseur conteste une réponse qu’un agent a donnée avant le changement. Le texte et les citations de la réponse ont été enregistrés, mais pas la version de chaque document cité. Ines ne peut pas prouver quelles conditions l’assistant a lues. Cela enfreint Q5 : « chaque réponse conservée pendant 1 an avec la question, les citations, les versions des documents, le locataire et l’utilisateur ».
Aucune de ces défaillances ne vient d’une partie défectueuse. Chaque partie a fait son travail. Les données ont perdu leur étiquette entre deux parties.
L’idée : les flux de données et d’identité
Section intitulée « L’idée : les flux de données et d’identité »Le contexte d’identité d’une requête est son étiquette. Il contient trois faits : qui pose la question (l’utilisateur), où (le locataire) et à quel titre (le rôle). Le rôle détermine le public visé : staff ou public. L’outil de soutien ne peut pas inventer ce contexte. Il provient d’un jeton vérifié, et chaque partie suivante le lit à partir de cette source.
Un flux de données et d’identité décrit le trajet de chaque élément de données dans la conception, avec son étiquette. Pour chaque élément, il indique son point de départ et son lieu de conservation. Il nomme aussi sa clé de locataire, sa version et les personnes autorisées à le lire. Vous le dessinez une fois, sous forme de diagramme et de tableau, puis vérifiez chaque flèche selon quatre règles :
- Chaque requête et chaque tâche transporte le locataire, à partir d’une source vérifiée : le jeton pour une requête, la ligne de tâche pour une tâche.
- Chaque ligne stockée conserve son locataire, et la base de données refuse les lignes des autres locataires, même si le code oublie un filtre. C’est la sécurité au niveau des lignes, vue dans le cours sur l’authentification.
- Chaque clé qui trouve des données inclut le locataire et le public visé : clé de cache, chemin de fichier ou filtre de recherche.
- Chaque réponse conserve les versions qu’elle a utilisées, pour qu’on puisse encore expliquer une ancienne réponse après la modification des documents.
Le nom décrit ce que vous dessinez : les données et l’identité qui les accompagne.
Un petit exemple : une question, chaque valeur
Section intitulée « Un petit exemple : une question, chaque valeur »Grace pose une question comme agente de Larkfield. Une cliente de Bramble Books pose exactement la même question. Voici chaque étape, avec la valeur de l’étiquette à ce moment. Les identifiants d’utilisateur et les numéros de version sont construits pour l’exemple.
| Étape | Grace (agente de Larkfield) | La cliente (site Web de Bramble Books) |
|---|---|---|
| Jeton après la connexion | utilisateur usr-grace, locataire larkfield, rôle agent (agent) |
utilisateur cust-1093, locataire bramble, rôle customer (client) |
| Public visé selon le rôle | staff |
public |
| Session de base de données | SET app.tenant = 'larkfield' |
SET app.tenant = 'bramble' |
| Version des documents (augmente à chaque changement) | 41 | 7 |
| Clé de cache | larkfield · staff · 41 · « combien de jours ai-je pour retourner un article » |
bramble · public · 7 · « combien de jours ai-je pour retourner un article » |
| Filtre de recherche | Segments de Larkfield, pour le personnel et le public | Segments de Bramble, publics seulement |
| Éléments enregistrés avec la réponse | locataire, utilisateur, question, citations, returns-policy v2 |
locataire, utilisateur, question, citations, returns-policy v4 |
La question est identique, mais les deux clés diffèrent à trois endroits. La deuxième requête ne peut donc pas réutiliser la première réponse. Le filtre de recherche répète la règle. La sécurité au niveau des lignes la répète une troisième fois dans la base de données. Si un endroit oublie le locataire, le suivant l’applique encore. Chaque réponse enregistrée nomme aussi les versions exactes qu’elle a lues.
Description textuelle du diagramme
Une personne se connecte et reçoit un jeton avec l’utilisateur, le locataire et le rôle. L’API de l’assistant lit le jeton. Elle définit le locataire pour chaque transaction de base de données, afin d’appliquer la sécurité au niveau des lignes. Elle place le locataire dans la clé de cache et dans la ligne de tâche. Elle envoie au fournisseur du modèle seulement les passages de ce locataire. Le processus d’ingestion prend une tâche et définit le locataire à partir de la ligne de tâche, sans autre source. Il écrit les fichiers dans le dossier propre au locataire. Chaque réponse est enregistrée avec les versions des documents utilisées, pour le journal d’audit. La version pour téléphone montre seulement le jeton, la base de données et la tâche.
Les flux de Larkfield
Section intitulée « Les flux de Larkfield »Kwame dessine deux schémas pour la proposition. Le premier est le diagramme ci-dessus. Le deuxième est le flux de requête du parcours principal, J1 : un agent pose une question. Il montre les mêmes parties que le diagramme de conteneurs, dans l’ordre chronologique.
Description textuelle du diagramme
L’outil de soutien envoie la question et le jeton. L’API vérifie le jeton et définit le locataire pour la transaction avant toute requête SQL. Elle cherche dans le cache de réponses avec le locataire, le public visé, la version des documents et la question. Si elle trouve une réponse, elle renvoie la réponse enregistrée. Sinon, elle crée le plongement de la question (environ 0,34 s). Elle cherche les segments de ce locataire et les reclasse (environ 0,32 s). Elle demande ensuite à chat-small une réponse avec citations (environ 1,52 s). Elle vérifie que chaque citation pointe vers un passage envoyé. Elle enregistre la réponse avec le locataire, l’utilisateur et les versions, puis répond. Les durées sont des médianes mesurées. Celle du modèle de reclassement vient du cours sur le RAG, sur un ordinateur portable.
Le diagramme transforme les règles en étapes. L’étape 3, qui définit le locataire pour la transaction, précède l’étape 4, la première requête SQL. Aucune requête SQL ne s’exécute donc sans lui. Les passages de l’étape 9 reviennent avec leurs versions de documents, et l’étape 13 les enregistre. Le flux nomme une autre vérification : l’API vérifie que chaque citation pointe vers un passage qu’elle a réellement envoyé. Il devient alors impossible d’enregistrer une citation vers un document d’un autre locataire.
Kwame écrit ensuite le tableau qui va sous le diagramme. Chaque type de données reçoit une ligne :
| Données | Emplacement | Clé de locataire | Version | Qui peut les lire |
|---|---|---|---|---|
| Fichier de document | Stockage de fichiers | dossier tenant/<id>/ |
un fichier par version | le processus; le personnel de ce locataire |
| Segments et vecteurs | PostgreSQL | tenant_id + sécurité au niveau des lignes |
document_version |
l’API pour ce locataire (documents publics pour les clients) |
| Réponse | PostgreSQL | tenant_id |
les versions des documents cités | le personnel et le propriétaire de ce locataire |
| Entrée de cache | PostgreSQL | dans la clé | version des documents dans la clé | l’API pour ce locataire et ce public visé |
| Tâche | PostgreSQL | tenant_id |
la version du document | le processus |
Le tableau révèle les lacunes que le diagramme cache. Chaque ligne a besoin d’une clé de locataire. Si une cellule est vide, il manque une règle. Mei vérifie la colonne « Version » par rapport à J3 et J4 : les anciennes versions restent, et les réponses nomment les versions utilisées.
Combien coûte cette protection? Le cours sur l’authentification a mesuré la sécurité au niveau des lignes pour une requête. Sans elle : 4,3 ms. Avec elle : 4,4 ms. La différence est d’environ 0,1 ms. Une réponse prend environ 2,18 s. La règle du locataire coûte moins d’un dixième de pour cent du temps. Personne n’a donc besoin d’en débattre.
La tâche en arrière-plan transporte sa propre étiquette
Section intitulée « La tâche en arrière-plan transporte sa propre étiquette »Le processus n’a pas de jeton : personne ne se connecte à une tâche. Prenons le téléversement par Ines de la version 5 de la politique de retour de Bramble Books. La requête de téléversement écrit l’étiquette dans la ligne de tâche, à partir du jeton vérifié. Elle y inscrit le locataire bramble et la version 5 du document. Le processus lit le locataire dans cette ligne et le définit pour sa propre transaction. Il ne prend jamais le locataire dans le nom du fichier ni dans son texte, car un éditeur contrôle les deux.
Les versions suivent le même trajet. Le processus enregistre les segments de la version 5. Puis, dans une seule transaction, il marque la version 5 comme active et la version 4 comme remplacée. La version des documents de Bramble Books augmente, de 7 à 8 dans l’exemple. Toutes les clés de cache avec 7 cessent de correspondre. Aucun client ne reçoit donc de réponse provenant de la version 4 après le changement. Les anciennes réponses nomment encore la version 4, ce qui permet à Ines de les expliquer plus tard. L’exercice du module dans Simplicité et évolution dessine cette tâche étape par étape.
Exercice guidé : écrire les deux fichiers de flux
Section intitulée « Exercice guidé : écrire les deux fichiers de flux »Vous écrivez deux fichiers Markdown dans architecture/. Chacun contient un diagramme Mermaid sous forme de texte. Mermaid dessine un diagramme à partir de quelques lignes de texte. Le diagramme reste donc dans Git, à côté du code, et se modifie dans une demande de tirage.
-
Créez le fichier
architecture/data-and-identity-flow.md. Commencez par un titre et une phrase :# Data and identity flow: where the tenant travelsEvery request and every job carries the tenant. The database refuses a row of another tenant even when the code forgets a filter (row-level security, as in the authentication course). -
En dessous, ajoutez un bloc Mermaid. Commencez par les deux premières flèches du diagramme ci-dessus :
```mermaidflowchart LRU[Person signs in] -->|token: user, tenant, role| A[Assistant API]A -->|SET app.tenant for the transaction| DB[(PostgreSQL<br/>row-level security)]``` -
Ajoutez les autres flèches dans le bloc. Copiez-les du diagramme ci-dessus, de la clé de cache jusqu’au journal d’audit. Collez le bloc dans mermaid.live et vérifiez que l’image correspond au diagramme ci-dessus.
-
Sous le bloc, ajoutez le tableau des cinq types de données présenté dans les flux de Larkfield ci-dessus.
-
Exécutez les tests :
Fenêtre de terminal python -m pytest -qFAILED tests/test_components.py::test_the_sequences_name_the_parts_of_the_diagram1 failed, 15 passed in 0.03sLe test du locataire réussit maintenant. Il vérifie que votre fichier nomme les quatre endroits où le locataire voyage :
cache key(clé de cache),job row(ligne de tâche),row-level security(sécurité au niveau des lignes) ettenant/(dossier du locataire). -
Créez
architecture/request-flow.mdavec le flux de requête de J1. Utilisez unsequenceDiagram(diagramme de séquence) Mermaid avec quatre participants : l’outil de soutien, l’API de l’assistant, PostgreSQL et le fournisseur du modèle. Écrivez une flèche par étape du diagramme ci-dessus. -
Comparez les deux fichiers avec ceux de l’instantané
end-of-m02. Exécutez les tests de nouveau. Ils affichent encore1 failed, 15 passed(1 échec, 15 réussites). Le dernier test en échec exige la séquence d’ingestion, que vous dessinez dans l’exercice du module.
Quand tracer les flux, et combien cela coûte
Section intitulée « Quand tracer les flux, et combien cela coûte »Tracez-les dès que plusieurs locataires ou plusieurs publics visés partagent une partie. Cela couvre toute conception multilocataire et toute conception avec des utilisateurs du public et du personnel. Tracez-les de nouveau quand vous ajoutez un stockage, un cache ou une tâche en arrière-plan. Chacun est un nouvel endroit où l’étiquette peut se perdre.
Ne tracez pas chaque champ. L’étiquette (locataire, utilisateur, public visé) et la version sont les faits qui causent des défaillances silencieuses. Les autres champs relèvent de la conception de la base de données.
Le coût est surtout du temps humain : une heure de dessin, puis une révision avec le responsable de chaque stockage. Dans le système en fonctionnement, le coût est faible. Comptez environ 0,1 ms par requête pour la sécurité au niveau des lignes, et quelques caractères supplémentaires par clé de cache. Les coûts augmentent seulement si un stockage ne peut pas appliquer la règle du locataire. Par exemple, un deuxième stockage pour les vecteurs aurait besoin de sa propre copie de la règle, testée séparément. C’est une des raisons pour lesquelles la conception conserve tous les enregistrements dans PostgreSQL.
Erreurs courantes
Section intitulée « Erreurs courantes »Erreur courante
La ligne de tâche manque dans le flux
Symptôme : après une modification, le test du locataire échoue de nouveau :
E AssertionError: assert 'job row' in '# Data and identity flow: where the tenant travels\n\nEvery request and every job carries the tenant. The database re...\nMeasured: row-level security added about 0.1 ms to a request in the authentication course (4.3 ms off, 4.4 ms on).\n'FAILED tests/test_components.py::test_the_tenant_travels_with_every_flow - As...Cause : la flèche A -->|tenant in the job row| Q (locataire dans la ligne de tâche) a été supprimée. Le schéma semble encore complet, mais le processus n’a plus de source pour le locataire. Dans un vrai système, ce processus prendrait le locataire ailleurs, par exemple dans le nom du fichier.
Correction : remettez la flèche. La seule source du locataire pour le processus est la ligne de tâche, écrite à partir du jeton vérifié.
Erreur courante
Une clé de cache sans public visé
Symptôme : une cliente sur le site Web reçoit une réponse qui cite le rabais du personnel. Rien ne semble anormal dans les journaux : la réponse venait du cache.
Cause : la clé de cache contient le locataire, mais pas le public visé. Un agent a posé la question en premier, avec les documents du personnel. La requête de la cliente a trouvé cette entrée.
Correction : la clé de cache contient chaque entrée qui change la réponse : locataire, public visé, version des documents et question. Écrivez la clé dans le tableau des flux. Ajoutez un test avec une question du personnel, puis la même question posée par le public.
À vous de jouer : un document est supprimé
Section intitulée « À vous de jouer : un document est supprimé »Changez une condition. Ines supprime l’ancien document « gift cards » (cartes-cadeaux) de Bramble Books, car la boutique n’en vend plus. Suivez la suppression dans le tableau des flux de Larkfield. Que faut-il changer dans chaque endroit où le document est conservé? Qu’est-ce qui doit rester inchangé?
Afficher une réponse possible
- Stockage des fichiers : les fichiers de chaque version sous
tenant/bramble/gift-cards/sont supprimés, ou conservés seulement selon la règle de conservation. - Segments et vecteurs : le processus les supprime dans une seule transaction. Il définit le locataire à partir de la tâche, comme pour un téléversement. La recherche ne peut plus les trouver.
- Version des documents : elle augmente, donc aucune réponse en cache pour Bramble Books ne correspond plus. Aucun client ne reçoit de réponse en cache sur les cartes-cadeaux.
- Réponses enregistrées : elles ne changent pas. Elles indiquent toujours le document sur les cartes-cadeaux et sa version, car J4 et Q5 conservent les réponses pendant un an. La réponse reste explicable, même si la source n’existe plus.
- La tâche : elle contient le locataire
brambleet le document, comme une tâche de téléversement.
La leçon Mises à jour et suppressions du cours RAG : créer une IA qui utilise vos données montre la suppression en code. Ici, l’important est le suivi : une suppression est aussi un flux, et elle doit atteindre chaque lieu de stockage.
Vérification des connaissances
Section intitulée « Vérification des connaissances »Vérifiez votre compréhension
Pourquoi le filtrage par locataire de chaque requête SQL dans l'API ne suffit-il pas si la base applique aussi la sécurité au niveau des lignes? Ou, à l'inverse : pourquoi avoir les deux?
Afficher la réponse
Chacun couvre une erreur que l’autre peut manquer. Le filtre dans le code indique ce que veut la requête HTTP. La sécurité au niveau des lignes bloque une requête SQL sans filtre, ou une nouvelle requête écrite pendant une journée chargée. Sans filtre, le code dépend d’un seul paramètre de la base de données. Sans sécurité au niveau des lignes, un seul WHERE (clause de filtrage) oublié mélange les données de deux boutiques. Ensemble, ils coûtent environ 0,1 ms par requête, selon les mesures du cours Authentification, autorisations et applications multilocataires. Une réponse prend environ 2,18 s.
Votre réponse contient-elle les points principaux de la nôtre ?
Connectez-vous et inscrivez-vous au cours pour enregistrer vos réponses. Chaque vérification compte pour le certificat.
Vérifiez votre compréhension
Faites une prédiction : Ines téléverse la version 5 de la politique de retour. Dix secondes après la fin du processus, un client pose une question qu'un client a posée hier. Reçoit-il la réponse d'hier en cache? Expliquez à l'aide de la clé de cache.
Afficher la réponse
Non. Le processus a augmenté la version des documents de Bramble Books lorsqu’il a activé la version 5, par exemple de 7 à 8. L’entrée d’hier contient 7 dans sa clé; la requête d’aujourd’hui crée une clé avec 8. La clé ne correspond pas, donc l’API relance la recherche et répond à partir de la version 5. La réponse enregistrée hier existe toujours, avec la version 4 dans ses citations, pour les audits.
Votre réponse contient-elle les points principaux de la nôtre ?
Connectez-vous et inscrivez-vous au cours pour enregistrer vos réponses. Chaque vérification compte pour le certificat.
Vérifiez votre compréhension
Vérification pratique : pour une ligne de votre tableau des flux, expliquez d'où vient le locataire et où il est stocké. Qu'est-ce qui empêche un autre locataire de lire ces données?
Afficher la réponse
Par exemple, pour la tâche : le locataire vient du jeton vérifié de la requête de téléversement. Il ne vient jamais du nom du fichier ni du corps de la requête. L’API le stocke dans le champ tenant_id de la ligne de la tâche, dans la même transaction que la version du document. Le processus le lit dans la ligne et définit app.tenant pour sa transaction. La sécurité au niveau des lignes s’applique donc à chaque requête SQL. La transaction du processus d’un autre locataire ne peut pas voir la ligne. Les segments qu’il écrit portent le même tenant_id.
Votre réponse contient-elle les points principaux de la nôtre ?
Connectez-vous et inscrivez-vous au cours pour enregistrer vos réponses. Chaque vérification compte pour le certificat.
Récapitulatif
- Le contexte d’identité est l’étiquette de chaque requête : qui demande, pour quel locataire et avec quel rôle. Il vient d’un jeton vérifié, ou de la ligne de la tâche pour le travail en arrière-plan.
- Un flux de données et d’identité suit chaque élément de données avec son étiquette. Il montre où les données sont conservées, leur clé de locataire, leur version et qui peut les lire.
- Quatre règles : les requêtes et les tâches contiennent le locataire; les lignes le conservent, avec la sécurité au niveau des lignes; les clés incluent le locataire et l’audience; les réponses conservent leurs versions.
- Une clé de cache sans locataire donne une réponse rapide, mais incorrecte, à la mauvaise boutique, sans signaler d’erreur. La clé contient le locataire, l’audience, la version des documents et la question.
- La sécurité au niveau des lignes coûte environ 0,1 ms par requête, selon les mesures du cours Authentification, autorisations et applications multilocataires. Une réponse prend environ 2,18 s.
- Votre dossier contient
data-and-identity-flow.mdetrequest-flow.md. Les tests affichent1 failed, 15 passed(1 échec, 15 réussites) jusqu’à l’exercice pratique du module.
Ensuite, vous décidez si ces parties doivent former une seule application ou plusieurs services.
Leçon suivante : Simplicité et évolution