Conserver les métadonnées

Ce que vous saurez faire

Donnez à chaque segment un ID qui reste le même pour un même passage. Ajoutez les renseignements qui mènent à sa source : document, version, dates, étiquette d’accès, section, page et caractères. Construisez ensuite l’index du projet sur disque. Retracez chaque segment jusqu’à son emplacement exact dans la source.

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

Ce que vous devez savoir

• Les trois méthodes de découpage et les segments de la politique de garantie, présentés dans Découper de façon réfléchie.
• Les positions des blocs dans le texte analysé, présentées dans Analyser et normaliser.
• SQLite, présenté dans SQL et préparation des données pour l’IA. L’index est un seul fichier SQLite.

Ce qu’il vous faut sur votre ordinateur

• Le projet avec parse.py, chunk.py et metadata.py, présenté dans Découper de façon réfléchie : exercice guidé. python -m pytest affiche 24 passed (24 tests réussis).
• Un terminal dans ~/projects/policy-assistant, avec .venv actif.

Testé avec Python 3.12.13 sur macOS (Apple silicon). Les commandes Windows ne sont pas testées.

Une cote sur le dos d’un livre

Dans une bibliothèque, chaque livre porte une cote sur son dos, comme « 641.5 LAR ». Cette cote appartient au livre. Quand la bibliothèque achète des livres ou en donne, « 641.5 LAR » mène toujours au même livre. Personne n’utilise « le 132e livre sur la troisième tablette » : ajoutez un livre, et le 132e n’est plus le même.

La fiche du catalogue en dit plus : le titre, l’édition, l’année, la tablette et la possibilité d’emprunter le livre. Avec seulement la cote, une personne peut trouver le livre, vérifier l’édition et savoir si elle peut l’emporter chez elle.

Le problème : une citation qui pointe vers le mauvais passage

Les réponses de ce cours citent les segments par leur ID. Les agents de Grace liront une réponse, cliqueront sur l’ID et vérifieront le passage. L’ID doit donc mener au même passage demain, après une modification de la collection.

L’ID le plus simple est un compteur : segment 0, segment 1, segment 2, dans l’ordre de lecture des fichiers à l’ingestion. Amira l’a testé. Elle a numéroté les 185 segments découpés selon la structure. Elle a ensuite exclu un document, account-and-security.md, comme si Grace l’avait retiré. Puis elle a numéroté les segments de nouveau.

Un document quitte la collection. Le compteur 132 désigne maintenant un autre passage; l'ID par hachage 7839ded2d52b désigne toujours le délai de retour. Calculé avec le code du projet; le retrait du document est un cas construit.

Description textuelle du diagramme

Deux petits tableaux. Avant : 36 documents et 185 segments. Le compteur 132 correspond au segment dont l’ID par hachage est 7839ded2d52b, politique de retour version 3, section Délai de retour. Le compteur 133 correspond à beb2688295be, section État des articles retournés. Une ancienne réponse cite [132] et 7839ded2d52b, qui désignent tous deux le délai de retour de 30 jours. Après le retrait d’un document : 179 segments. Le compteur 132 correspond maintenant à b7711c885517, section Échanges, en orange. Le délai de retour porte maintenant le compteur 126, et son ID par hachage reste 7839ded2d52b. Ainsi, [132] dans l’ancienne réponse pointe maintenant vers le mauvais passage, tandis que l’ID par hachage pointe toujours vers le bon.

Les 179 segments restants ont tous changé de compteur. Aucun ne l’a conservé. Une ancienne réponse qui citait « [132] » pour le délai de retour de 30 jours pointe maintenant vers la section Échanges. Rien ne cesse de fonctionner, et aucune erreur ne s’affiche. La citation est simplement fausse. Les ID par hachage des 179 segments sont restés les mêmes.

Il y a un deuxième piège. Les versions 3 et 4 de la politique de retour ont une section Échanges dont le texte est identique. Si l’ID provenait seulement du texte, les deux versions auraient le même ID. Une réponse ne pourrait pas indiquer la version utilisée. Pour un retour, c’est important : la date de livraison détermine laquelle des deux versions s’applique.

L’idée : un ID stable et les métadonnées du segment

Les métadonnées sont des données sur les données : les renseignements sur un segment autres que son texte. Un ID de segment stable est un ID que le même segment reçoit à chaque ingestion, et qu’aucun autre segment ne reçoit.

Le projet construit l’ID à partir de quatre valeurs : l’ID du document, la version, le début et la fin du segment dans le texte analysé. Il les joint avec |, calcule le SHA-256 de ce texte et garde les 12 premiers caractères. SHA-256 est une fonction de hachage : elle transforme tout texte en une empreinte de 64 caractères hexadécimaux. Le même texte donne toujours la même empreinte, et toute modification en donne une différente.

Chacune des quatre valeurs a un rôle.

• L’ID du document indique de quel document il s’agit. Un autre document ne peut jamais le déplacer. En exclure un ne change donc aucun autre ID.
• La version donne de nouveaux ID à une nouvelle version, même si son texte reste identique. Une réponse ne cite jamais la version 4 avec un ID de la version 3.
• Le début et la fin indiquent la partie du document. Deux segments d’un même document ne partagent jamais ces deux valeurs.

Le numéro du segment dans son document (position, no 3) est aussi conservé pour l’ordre de lecture. Il ne fait toutefois pas partie de l’ID.

Un petit exemple détaillé : un ID, à la main

Prenez le segment no 3 de la politique de garantie, découpé selon la structure, dans Ce qui n’est pas couvert. Il couvre les caractères 1 517 à 1 967 de la version 5. Calculez son ID deux fois : avec la fonction du projet, puis à la main avec hashlib de Python.

Python session, in ~/projects/policy-assistant

import hashlib
from policy_assistant.metadata import chunk_id
chunk_id("warranty-policy", "5", 1517, 1967)
hashlib.sha256("warranty-policy|5|1517|1967".encode()).hexdigest()

'a4dc9ec49818'
'a4dc9ec498189eea06b752305cc84105636c67ea6767e348552973c7a6bc0cea'

Les 12 premiers caractères de l’empreinte forment l’ID. Douze caractères hexadécimaux permettent environ 281 millions de millions d’ID différents. Il est donc très improbable que deux des 185 segments de Larkfield partagent un ID par hasard. Relancez le calcul demain, sur un autre ordinateur : vous obtenez encore a4dc9ec49818. Remplacez la version par "6", et vous obtenez un ID différent.

L’ID permet de trouver le segment. Le reste de l’enregistrement indique sa provenance et qui peut le voir :

Un vrai segment et la provenance de chaque valeur de ses métadonnées. Toutes les valeurs sont dans l'index; le texte du segment y est aussi conservé.

Description textuelle du diagramme

L’enregistrement du segment a4dc9ec49818, segment no 3 de la politique de garantie, découpé selon la structure. Chaque champ a une flèche vers sa source. chunk_id (ID du segment) a4dc9ec49818 : les 12 premiers caractères du SHA-256 de « warranty-policy|5|1517|1967 ». doc_id (ID du document) et version, warranty-policy et 5 : les métadonnées du PDF (son champ Keywords) et l’inventaire. effective_from (date d’entrée en vigueur) 2026-01-01, sans effective_to (date de fin d’application) : les métadonnées du PDF. access (accès) public : les métadonnées du PDF; une étiquette absente devient staff. source documents/warranty-policy.pdf : le fichier lu à l’ingestion. sections Ce qui n’est pas couvert : le bloc de titre au-dessus du texte. pages 1 : la page où chaque bloc commence. start (début) et end (fin), 1517 et 1967 : les caractères dans le texte analysé; le texte analysé de 1 517 à 1 967 est le texte source du segment.

Deux champs méritent une précision. L’étiquette d’accès indique qui peut voir un segment : public (clients et agents) ou staff (personnel, agents seulement). Un document sans étiquette reçoit staff. Si quelqu’un oublie l’étiquette, le passage reste caché aux clients; il n’est jamais affiché par erreur. Les dates d’application indiquent quand une version s’applique. La version 3 de la politique de retour est en vigueur jusqu’au 31 octobre 2026, et la version 4 dès le 1er novembre 2026. Le module 3 filtre selon ces deux critères avant de retenir les 5 premiers résultats.

L’index sur disque

Jusqu’ici, les segments existaient seulement dans une session Python. Le fichier store.py du projet les conserve dans un fichier SQLite, index.sqlite, avec quatre tables :

• documents : une ligne par version de document, avec ses métadonnées, son fichier et le SHA-256 des octets du fichier;
• chunks : une ligne par segment, avec l’enregistrement ci-dessus et son texte;
• keyword_index : le texte des segments dans l’index de recherche plein texte de SQLite, pour BM25;
• meta : la façon dont l’index a été construit, pour l’instant seulement la méthode de découpage.

La commande ingest lit chaque fichier dans corpus/documents/, l’analyse, le découpe et l’écrit. Pour l’instant, elle supprime tout et reconstruit l’index à chaque fois. C’est simple et toujours correct, et cela prend bien moins d’une seconde pour 36 documents. Le module 6 lui fera mettre à jour seulement ce qui a changé. Un document sans ID de document ou sans version arrête ingest avec une erreur : un segment sans ces valeurs serait impossible à citer.

L’index de Larkfield : retracer un segment jusqu’à sa source

Après l’ingestion, la commande chunks énumère les segments d’un document avec leurs métadonnées :

python -m policy_assistant chunks warranty-policy

144a40851685 v5 #0 chars 27-369 pages 1 | 60 words | What the warranty covers
d9a5bd8ea531 v5 #1 chars 371-1453 pages 1 | 200 words | Warranty periods by product category
b47ef9ac1993 v5 #2 chars 1455-1515 pages 1 | 18 words | Warranty periods by product category
a4dc9ec49818 v5 #3 chars 1517-1967 pages 1 | 80 words | What is not covered
3f7023270716 v5 #4 chars 1969-2276 pages 2 | 64 words | How to make a claim
ae23e5ca9b13 v5 #5 chars 2278-2409 pages 2 | 27 words | Proof of purchase
66cd6ab97679 v5 #6 chars 2411-2579 pages 2 | 30 words | Customers in Quebec
86d27b0a52ac v5 #7 chars 2581-2744 pages 2 | 31 words | Safety problems
8 chunks (structure) from documents/warranty-policy.pdf

Ce sont les ID de l’explorateur présenté dans Découper de façon réfléchie. Pour retracer un segment, remontez son enregistrement. Prenez d9a5bd8ea531, le segment du tableau. Sa source est documents/warranty-policy.pdf, version 5. Analysez ce fichier : les caractères 371 à 1 453 du texte sont le titre et le tableau entier. Ils se trouvent dans la section Périodes de garantie par catégorie de produits, à la page 1 du PDF. Grace peut ouvrir la politique imprimée à la page 1 et trouver le même tableau. C’est une trace : d’un ID vers un fichier, une version, une section, une page et les caractères exacts.

Erreur courante

Un numéro de page à moitié correct

Symptôme : Grace retrace le segment a4dc9ec49818 dans la politique imprimée. L’index indique pages 1 (page 1). La page 1 contient les quatre premiers éléments de la liste Ce qui n’est pas couvert, mais le segment en contient sept. Les trois derniers, à partir de « Dommages causés par un carburant, une tension ou des produits chimiques inadéquats. », sont à la page 2. Vous les avez vus en haut de la page 2 dans le texte brut de Analyser et normaliser.

Cause : l’analyseur joint les éléments d’une liste en un seul bloc. Un bloc a une seule page : celle où il commence. Un segment prend les pages de ses blocs. Cette liste s’étend sur deux pages, donc le segment indique seulement sa première page. Dans l’explorateur de segments, la ligne de page en pointillés se trouve à l’intérieur de ce segment.

Correction : sachez ce que chaque champ signifie, et fiez-vous au plus précis. Dans ce projet, pages signifie « les pages où les blocs du segment commencent ». Les caractères 1 517 à 1 967 sont exacts et mènent toujours au texte complet. Lorsque vous citez un PDF pour une personne, donnez la section. Ajoutez « page 1, suite à la page 2 » si le texte continue. Pour aller plus loin, vous pouvez aussi donner une dernière page à Block et faire utiliser les deux par make_chunk. Cela ne change aucun texte ni aucun ID de segment.

Pour un vrai assistant : chaque champ de métadonnées a une définition, et vous devriez la consigner. Un numéro de page qui signifie « où cela commence » est utile. Si quelqu’un le comprend comme « où tout se trouve », il l’envoie à la mauvaise page.

Quand les métadonnées valent la peine, et ce qu’elles coûtent

Les métadonnées coûtent peu à stocker : quelques champs courts par segment. Elles demandent de la discipline. Chaque source doit fournir un ID de document, une version, ses dates et une étiquette d’accès. Quelqu’un doit les tenir à jour. Chez Larkfield, l’inventaire de Grace et les métadonnées dans chaque fichier remplissent ce rôle.

Les ID stables ont un autre coût : quand un document change, ses segments reçoivent de nouveaux ID. C’est voulu. Une ancienne réponse cite toujours le segment de l’ancienne version, et l’indique. Le module 6 retire les anciens segments de l’index lorsqu’une version est retirée.

Conservez toutes ces données lorsque les réponses doivent être vérifiées, filtrées par date ou limitées selon l’accès. Cela concerne tout assistant qui utilise les documents d’une entreprise. Un champ de recherche pour vos propres notes en demande moins.

Exercice guidé : construire l’index

1. Copiez l’index, l’interface en ligne de commande complète et deux tests depuis l’instantané. Sur macOS et Linux :

   cp ../nextia-learning-labs/C09/snapshots/end-of-m02/policy_assistant/store.py policy_assistant/
   cp ../nextia-learning-labs/C09/snapshots/end-of-m02/policy_assistant/__main__.py policy_assistant/
   cp ../nextia-learning-labs/C09/snapshots/end-of-m02/tests/test_metadata.py tests/
   cp ../nextia-learning-labs/C09/snapshots/end-of-m02/tests/test_store.py tests/

   Sur Windows, dans PowerShell :

   Copy-Item ..\nextia-learning-labs\C09\snapshots\end-of-m02\policy_assistant\store.py policy_assistant\
   Copy-Item ..\nextia-learning-labs\C09\snapshots\end-of-m02\policy_assistant\__main__.py policy_assistant\
   Copy-Item ..\nextia-learning-labs\C09\snapshots\end-of-m02\tests\test_metadata.py tests\
   Copy-Item ..\nextia-learning-labs\C09\snapshots\end-of-m02\tests\test_store.py tests\

   Le nouveau __main__.py remplace le vôtre. Il conserve votre commande parse, ajoute ingest et chunks, et fait utiliser l’index par search et eval.

2. Ouvrez policy_assistant/metadata.py. Trouvez chunk_id et l’enregistrement Chunk, puis associez ses champs à l’illustration ci-dessus.

3. Lancez les tests. Vous voyez 31 passed (31 tests réussis) :

   python -m pytest

   test_metadata.py vérifie qu’une nouvelle version reçoit de nouveaux ID, et que les ID ne dépendent pas des autres documents.

4. Construisez l’index :

   python -m policy_assistant ingest

   36 documents, 185 chunks (rebuilt from scratch)
   index index.sqlite: 36 documents, 185 chunks | chunker structure

5. Énumérez les segments de la politique de garantie, comme ci-dessus :

   python -m policy_assistant chunks warranty-policy

6. Mesurez de nouveau la recherche, maintenant sur les 36 documents :

   python -m policy_assistant eval

   BM25 over structure chunks, top 5: hit@5 0.797 (59 questions with relevant passages)
     answerable       18 questions, hit@5 0.778
     contradiction     4 questions, hit@5 1.000
     exact-code       11 questions, hit@5 1.000
     injection-bait    3 questions, hit@5 0.333
     staff-only        7 questions, hit@5 1.000
     table             8 questions, hit@5 0.625
     version           8 questions, hit@5 0.625
   missed: Q05, Q12, Q13, Q26, Q28, Q29, Q32, Q34, Q37, Q56, Q57, Q63

   La référence de base était de 0,695. Les questions sur les tableaux sont passées de 0,125 à 0,625 : le tableau du PDF est maintenant dans l’index.

7. Posez la question qui avait échoué dans le module 1 :

   python -m policy_assistant search "Which pump kit fits the PW-2200?"

   Le premier résultat est maintenant le tableau des pièces du PW-2200 lui-même, tiré du PDF :

   1.  19.6787  [f80f7e98f870] product-care-pw2200 v2 | Parts and part numbers | public
      Parts and part numbers Part | Part number | Notes Pump kit | PK-2200-07 | fits the PW-2200 only Noz…

Si l’étape 5 affiche No index at … (aucun index à cet emplacement), l’étape 4 n’a pas été exécutée dans le dossier du projet. Allez dans ~/projects/policy-assistant et refaites l’étape 4. index.sqlite est recréé à chaque ingest, donc vous pouvez le supprimer à tout moment.

Exercice du module : examiner les segments d’une politique contenant un tableau

Faites d’abord cet exercice avec la politique de garantie, puis seul avec la politique de livraison. Les deux ont plusieurs titres et un tableau; la politique de livraison est une page HTML.

1. Reconstruisez l’index avec des segments fixes, puis énumérez les segments de la politique de garantie :

   python -m policy_assistant ingest --chunker fixed
   python -m policy_assistant chunks warranty-policy

   521ff4295be4 v5 #0 chars 0-613 pages 1 | 100 words | What the warranty covers / Warranty periods by product category
   7ac8fe213b88 v5 #1 chars 614-1159 pages 1 | 100 words | Warranty periods by product category
   957c935ee2fa v5 #2 chars 1160-1708 pages 1 | 100 words | Warranty periods by product category / What is not covered
   174d797eb4bd v5 #3 chars 1709-2252 pages 1,2 | 100 words | What is not covered / How to make a claim
   0131e6fb8ee6 v5 #4 chars 2253-2744 pages 2 | 84 words | How to make a claim / Proof of purchase / Customers in Quebec / Safety problems
   5 chunks (fixed) from documents/warranty-policy.pdf

   Notez les sections et les pages de chaque segment. Quels segments contiennent une partie du tableau (caractères 409 à 1 453)?

2. Lancez eval. Reconstruisez ensuite avec --chunker overlap, puis relancez eval. Vous obtenez un hit@5 de 0,864 et de 0,881, comme dans Découper de façon réfléchie.

3. Reconstruisez avec la méthode de découpage par défaut, pour que le prochain module parte de celle-ci :

   python -m policy_assistant ingest

4. À vous : lancez python -m policy_assistant parse corpus/documents/delivery-policy.html pour trouver son tableau. Comparez ensuite chunks delivery-policy avec des segments découpés selon la structure et avec des segments fixes. Pour chaque segment, notez son emplacement dans la source. Quelle méthode garde le tableau de livraison entier?

Afficher les réponses

Politique de garantie, segments fixes : les nos 0, 1 et 2 contiennent des parties du tableau (409 à 1 453). Le no 0 commence avant, et le no 2 finit après. Le no 3 est le seul segment sur deux pages. Chaque segment fixe, sauf le no 1, mélange deux sections ou plus.

Politique de livraison : son tableau est le bloc aux caractères 480 à 1 193, dans Délais et frais de livraison. Le segment découpé selon la structure 617a6fe666fc (caractères 274 à 1 245, 167 mots) contient toute la section et tout le tableau. Les segments fixes a577c4f431c0 (0 à 606), 30cff6982b67 (607 à 1 177) et 886ece394acc (1 178 à 1 746) le coupent en trois. Le HTML n’a pas de pages, donc chaque segment indique pages - (aucune page). Son emplacement est le fichier, la version (4), la section et les caractères.

Vérification du module

La vérification de fin de module : retracer chaque segment jusqu’à un emplacement précis dans sa source. Vous l’avez fait à la main ci-dessus pour un segment. Pour tous les segments, demandez au code. Pour chaque segment de l’index, il analyse le fichier source et vérifie que les caractères du segment se trouvent dans son texte.

Python session, in ~/projects/policy-assistant

from policy_assistant.store import Store
from policy_assistant.parse import parse
from policy_assistant.documents import CORPUS
store = Store("index.sqlite")
chunks = store.chunks()
bad = [c.chunk_id for c in chunks if parse(CORPUS / c.source).text[c.start:c.end] not in c.text]
print(len(chunks), "chunks,", len(bad), "not traceable")

185 chunks, 0 not traceable

Chaque segment mène à un fichier, à une version et aux caractères exacts de sa source, puis à sa section et à sa page. Répondez ensuite à ces questions :

De bout en boutRépondre à partir de règlements versionnésÉtude de cas

L’étude de cas sur les règlements conserve les dates d’entrée en vigueur de chaque version. Ainsi, une question avec une date trouve la version en vigueur.

Vérifiez votre compréhension

Pourquoi construire l'identifiant d'un segment à partir de l'identifiant du document, de sa version et des positions de ses caractères, plutôt qu'à partir d'un compteur ou de son texte seul?

Afficher la réponse

Un compteur dépend de tous les segments qui le précèdent. Quand un document a quitté la collection de Larkfield, les 179 segments restants ont tous reçu un nouveau numéro. L’ancienne citation [132] pointait alors vers Exchanges (échanges) plutôt que vers le délai de retour. Le texte seul ne suffit pas non plus. Les versions 3 et 4 de la politique de retour ont le même texte dans Exchanges. Elles doivent avoir des identifiants différents pour que la réponse indique la version utilisée. L’identifiant du document, la version et la position désignent exactement un passage. Ils ne changent pas quand d’autres documents changent.

Vérifiez votre compréhension

Retracez le segment 3f7023270716 : quels fichier, version, section, page et caractères? Utilisez seulement la sortie de `chunks warranty-policy`.

Afficher la réponse

3f7023270716 v5 #4 chars 1969-2276 pages 2 | 64 words | How to make a claim. Le fichier est documents/warranty-policy.pdf (la dernière ligne de la sortie), version 5. La section est How to make a claim (comment faire une réclamation), à la page 2. Le texte source correspond aux caractères 1 969 à 2 276 du document analysé. Dans la sortie de l’analyse du PDF, ce sont le titre How to make a claim et ses trois paragraphes.

Vérifiez votre compréhension

Un nouveau document arrive sans étiquette d'accès. Que fait le projet, et pourquoi est-ce le choix sûr?

Afficher la réponse

make_chunk donne à ses segments l’étiquette staff (personnel). Une étiquette manquante cache donc le passage à l’assistant public. Une personne le remarque ensuite et ajoute la bonne étiquette. L’autre choix, public (public), montrerait par erreur aux clients une procédure réservée au personnel. Personne ne le remarquerait avant que cela se produise.

Vérifiez votre compréhension

Prédisez : Grace publie la version 6 de la politique de garantie en modifiant une phrase dans Safety problems. Qu'arrive-t-il aux identifiants des segments de garantie et aux anciennes réponses qui citaient la version 5?

Afficher la réponse

Chaque segment de la version 6 reçoit un nouvel identifiant, car la version fait partie de l’identifiant. Cela vaut même pour les sections dont le texte reste identique. Les segments de la version 5 conservent leurs identifiants. Les anciennes réponses pointent donc toujours vers les passages de la version 5 utilisés et indiquent cette version. Retirer la version 5 de l’index pour l’exclure des recherches est une étape distincte : le module 6 s’en charge.

Récapitulatif

• Les métadonnées décrivent un segment : identifiant du document, version, dates d’entrée en vigueur, étiquette d’accès, langue, type, fichier source, sections, pages et caractères.
• Un identifiant de segment stable correspond aux 12 premiers caractères du SHA-256 de « identifiant du document | version | début | fin ». Le même passage reçoit le même identifiant à chaque ingestion; une nouvelle version reçoit de nouveaux identifiants. Les autres documents ne peuvent pas le déplacer. Tous les identifiants issus du compteur se sont décalés quand un document a quitté la collection.
• Une étiquette d’accès manquante devient staff. Ainsi, une erreur cache un passage au lieu de le montrer.
• ingest construit index.sqlite (documents, segments, index de mots-clés, métadonnées) à partir des 36 documents : 185 segments. hit@5 est passé de 0,695 à 0,797. La question sur le PW-2200 trouve maintenant son propre tableau de pièces en premier.
• Chaque segment mène à un fichier, à une version, à une section, à une page et aux caractères exacts. Dans ce projet, pages désigne les pages où commencent les blocs du segment.

Votre projet correspond maintenant à l’instantané end-of-m02. Au module 3, la recherche apprend le sens des mots, pas seulement les mots eux-mêmes. Elle filtre aussi par date et par étiquette d’accès.

Leçon suivante : Les plongements pour la recherche