Modèle de document

Search Toolkit représente chaque source ingérée avec un modèle de document unique et unifié. Deux classes transportent les données tout au long du pipeline :

• Document : la sortie complète d’un extracteur pour une source.
• DocumentChunk : une portion récupérable de ce document, qui peut aussi porter un embedding.

Les deux sont reliés par une identité déterministe dérivée d’un source_id et d’un locator. La même identité est répliquée côté récupération par SearchResultChunk, ce qui permet à un fragment de conserver le même identifiant de l’ingestion jusqu’à la recherche.

Un Document correspond à ce qu’un extracteur produit pour une seule source. Son id est calculé automatiquement à partir de source_id, vous avez donc rarement à le définir à la main.

class Document:
    id: str                       # deterministic, computed from source_id
    source_id: str                # stable identifier of the source
    content: str                  # full extracted text
    chunks: list[DocumentChunk]   # the document's chunks
    metadata: DocumentMetadata    # extensible, immutable metadata

class Document:
    id: str                       # deterministic, computed from source_id
    source_id: str                # stable identifier of the source
    content: str                  # full extracted text
    chunks: list[DocumentChunk]   # the document's chunks
    metadata: DocumentMetadata    # extensible, immutable metadata

Un DocumentChunk est l’unité indexée et récupérée. Son id est calculé à partir de source_id + locator, et parent_ref pointe vers l’id du Document auquel il appartient.

class DocumentChunk:
    id: str                          # deterministic, computed from source_id + locator
    source_id: str                   # same source_id as the parent document
    locator: str                     # semantic position within the source
    start_offset: int                # inclusive character offset
    end_offset: int                  # exclusive character offset
    parent_ref: str | None           # id of the parent Document
    chunk_type: ChunkType            # content, image_annotation, or summary
    content: str                     # the chunk text
    metadata: DocumentChunkMetadata  # extensible, immutable metadata
    embedding: list[float] | None    # populated once embedded

class DocumentChunk:
    id: str                          # deterministic, computed from source_id + locator
    source_id: str                   # same source_id as the parent document
    locator: str                     # semantic position within the source
    start_offset: int                # inclusive character offset
    end_offset: int                  # exclusive character offset
    parent_ref: str | None           # id of the parent Document
    chunk_type: ChunkType            # content, image_annotation, or summary
    content: str                     # the chunk text
    metadata: DocumentChunkMetadata  # extensible, immutable metadata
    embedding: list[float] | None    # populated once embedded

source_id est l’identifiant stable du document source, par exemple un chemin de fichier, une URL ou un schéma personnalisé comme arxiv:1706.03762. Il est défini sur File.source_id et reporté par les extracteurs sur le document obtenu et sur chacun de ses fragments. Par défaut, source_id correspond au chemin ou au nom du fichier.

Définissez explicitement source_id pour dissocier l’identité du document de son emplacement de stockage. Le déplacement d’un fichier conserve ses identifiants uniquement si son source_id reste inchangé.

locator décrit la position sémantique d’un fragment dans sa source. Les formats intégrés sont :

• char:{start}-{end} : une plage de caractères.
• page:{n}:char:{start}-{end} : une plage de caractères sur une page connue, pour les sources paginées.

Quand un fragment n’est pas du contenu brut, son type préfixe le locator, par exemple summary:char:0-512 ou image_annotation:page:2:char:0-128.

Les identifiants sont des hachages UUID5 dérivés des champs d’identité, et non des valeurs aléatoires :

• Document.id = hachage de source_id
• DocumentChunk.id = hachage de source_id + locator
• parent_ref = hachage de source_id (un fragment résout donc toujours vers son document)

Comme les identifiants sont dérivés, réingérer le même source_id avec les mêmes locators écrase les mêmes enregistrements au lieu de créer des doublons. Ce comportement rend l’indexation idempotente.

chunk_type distingue les types de fragments qu’un document peut contenir :

DocumentMetadata et DocumentChunkMetadata sont immuables après leur création, et vous pouvez ajouter vos propres clés. Le toolkit fournit des sous-types typés pour les cas courants, comme DocumentFileMetadata (filename, filepath) et PagedDocumentChunkMetadata (page_number).

Une clé de métadonnées ne doit pas entrer en collision avec le nom d’un champ du modèle (par exemple, vous ne pouvez pas placer source_id dans les métadonnées), car cela serait ambigu lorsque le fragment est persisté.

Côté récupération, SearchResultChunk porte le même contrat d’identité : id, source_id, locator, parent_ref et chunk_type. Chaque résultat renvoie directement au fragment ingéré.

• Ingestion : comment les documents et les fragments sont produits.
• Récupération : comment les fragments sont recherchés et renvoyés.
• Index de recherche : comment les fragments sont persistés.