Extracteurs de documents

Les extracteurs de documents extraient le contenu d'un objet File vers un objet Document qui peut être traité ultérieurement. Les différents types de fichiers nécessitent des logiques d'extraction différentes : les fichiers PDF peuvent être extraits par OCR, tandis que les fichiers Excel nécessitent une extraction tabulaire.

Tous les extracteurs intégrés définissent l'ID du document à file.id.

Extracteurs de documents disponibles

Extracteur	Types de fichiers
Extracteur OCR Mistral	PDF, DOCX, PPTX, ODT
Extracteur de transcription audio Mistral	MP3, WAV, M4A, FLAC, OGG
Extracteur de texte brut	TXT, MD, CSV, JS, PY (et autres fichiers texte/code)
Extracteur HTML	HTML, HTM
Extracteur de feuilles de calcul	XLS, XLSX, XLSM, XLSB, ODS, ODF
Extracteur d’e-mails	EML, MSG
Extracteur Numbers	NUMBERS
Extracteur Office hérité	DOC, PPT, HWP, HWPX
Extracteurs personnalisés	Toute source

Extracteur OCR Mistral

MistralOCRExtractor utilise l'API OCR de Mistral pour extraire du texte structuré et des images depuis des fichiers PDF, DOCX, PPTX et ODT. C'est l'extracteur recommandé pour les documents scannés et riches en images.

Exigences :

Une clé API Mistral

Installation : Bibliothèque de base (aucune dépendance supplémentaire requise)

Exemple :

import os

from mistralai.client import Mistral
from mistralai.search.toolkit.ingestion.extractors import MistralOCRExtractor

mistral_client = Mistral(
    api_key=os.environ.get("MISTRAL_API_KEY", "your-api-key"),
    server_url=os.environ.get("MISTRAL_SERVER_URL"),  # Optional
)
extractor = MistralOCRExtractor(
    client=mistral_client,
    include_image_base64=True,      # Include image data
    include_image_annotation=True,  # Add image annotations
)
document = await extractor.extract(file)

import os

from mistralai.client import Mistral
from mistralai.search.toolkit.ingestion.extractors import MistralOCRExtractor

mistral_client = Mistral(
    api_key=os.environ.get("MISTRAL_API_KEY", "your-api-key"),
    server_url=os.environ.get("MISTRAL_SERVER_URL"),  # Optional
)
extractor = MistralOCRExtractor(
    client=mistral_client,
    include_image_base64=True,      # Include image data
    include_image_annotation=True,  # Add image annotations
)
document = await extractor.extract(file)

Paramètres :

Paramètre	Type	Par défaut	Description
`client`	`Mistral`	(obligatoire)	Instance client Mistral
`model_name`	`str`	`"mistral-ocr-latest"`	Nom du modèle OCR
`timeout_seconds`	`int`	`900`	Délai d'exécution de la requête en secondes
`strip_page_markdown`	`bool`	`True`	Supprimer les espaces en début/fin de ligne dans le markdown de page
`populate_content`	`bool`	`True`	Remplir le champ `content` du document
`include_image_base64`	`bool`	`False`	Inclure les données des images en base64 dans le document
`include_image_annotation`	`bool`	`False`	Ajouter des annotations d'images au markdown de page
`max_file_size_bytes`	`int \| None`	`None`	Taille maximale de fichier avant division en parties
`pages_split_size`	`int \| None`	`None`	Nombre de pages par division lorsque le fichier dépasse `max_file_size_bytes`
`pages_group_size`	`int \| None`	`None`	Nombre de pages par requête API
`http_headers`	`Mapping[str, str] \| None`	`None`	En-têtes HTTP personnalisés transmise à l'API OCR
`image_limit`	`int \| None`	`None`	Nombre maximal d'images à inclure par page
`pages`	`Sequence[int] \| None`	`None`	Numéros de pages spécifiques à extraire (basé sur 1)
`table_format`	`"markdown" \| "html" \| None`	`None`	Format de sortie des tableaux

Fonctionnalités :

OCR pour les documents scannés et les images
Sortie en markdown avec préservation de la structure
Suivi des références d'images avec encodage base64 optionnel
Extraction configurable des pages (pages spécifiques ou plages de pages)
Personnalisation du format de tableau (markdown ou HTML)
Gestion des gros fichiers avec division automatique

Extracteur de transcription audio Mistral

MistralAudioTranscriptionExtractor utilise l'API de transcription audio de Mistral pour convertir les fichiers audio en texte. Prise en charge de la diarisation des locuteurs et des granularités d'horodatage.

Exigences :

Une clé API Mistral

Installation : Bibliothèque de base (aucune dépendance supplémentaire requise)

Exemple :

import os

from mistralai.client import Mistral
from mistralai.search.toolkit.ingestion.extractors import MistralAudioTranscriptionExtractor

extractor = MistralAudioTranscriptionExtractor(
    client=Mistral(api_key=os.environ.get("MISTRAL_API_KEY", "your-api-key")),
    model_name="voxtral-mini-latest",  # Default model
    language="en",          # Optional language hint
    diarize=True,           # Enable speaker diarization
    timeout_seconds=900,    # Transcription timeout (default)
)
document = await extractor.extract(file)

import os

from mistralai.client import Mistral
from mistralai.search.toolkit.ingestion.extractors import MistralAudioTranscriptionExtractor

extractor = MistralAudioTranscriptionExtractor(
    client=Mistral(api_key=os.environ.get("MISTRAL_API_KEY", "your-api-key")),
    model_name="voxtral-mini-latest",  # Default model
    language="en",          # Optional language hint
    diarize=True,           # Enable speaker diarization
    timeout_seconds=900,    # Transcription timeout (default)
)
document = await extractor.extract(file)

Paramètres :

Paramètre	Type	Par défaut	Description
`client`	`Mistral`	(obligatoire)	Instance client Mistral
`model_name`	`str`	`"voxtral-mini-latest"`	Nom du modèle de transcription
`language`	`str \| None`	`None`	Indice de langue cible pour la transcription
`diarize`	`bool`	`False`	Activer la diarisation des locuteurs
`timestamp_granularities`	`list[str] \| None`	`None`	Granularités des horodatages (par ex. `["word", "segment"]`)
`timeout_seconds`	`int`	`900`	Délai d'exécution de la requête en secondes
`populate_content`	`bool`	`True`	Remplir le champ `content` du document
`http_headers`	`Mapping[str, str] \| None`	`None`	En-têtes HTTP personnalisés transmis à l'API de transcription

Fonctionnalités :

Transcription audio avec prise en charge de la diarisation des locuteurs
Granularités des horodatages pour une précision au niveau des mots et des segments
Indice de langue pour une meilleure précision
Prise en charge des téléchargements de fichiers bruts et des sources URL distantes
Délai d'exécution personnalisable pour les fichiers audio longs

Extracteur de texte brut

Extracteur pour les documents de type texte brut (txt, md, code, csv, etc.).

Installation : Bibliothèque de base (aucune dépendance supplémentaire requise)

Exemple :

from mistralai.search.toolkit.ingestion.extractors import PlainTextExtractor

extractor = PlainTextExtractor(
    page_size=2000,    # Characters per page (default)
    encoding="utf-8",  # Default encoding
)
document = await extractor.extract(file)

from mistralai.search.toolkit.ingestion.extractors import PlainTextExtractor

extractor = PlainTextExtractor(
    page_size=2000,    # Characters per page (default)
    encoding="utf-8",  # Default encoding
)
document = await extractor.extract(file)

Options de configuration :

Option	Type	Par défaut	Objectif
`page_size`	int	2000	Caractères par page (divise les gros fichiers en pages logiques)
`encoding`	str	"utf-8"	Encodage des caractères pour la lecture des fichiers
`skip_encoding_detection`	bool	False	Ignorer la détection automatique de l'encodage (utiliser uniquement l'encodage spécifié)

Comportement :

Les fichiers plus grands que page_size sont divisés en plusieurs pages
Chaque page devient une page de document avec des métadonnées page_number
L'intégralité du contenu du fichier est préservée dans document.content
La détection de l'encodage essaie UTF-8 en premier, puis bascule sur d'autres encodages si activé

Extracteur HTML

HTMLExtractor analyse les fichiers HTML et HTM et les convertit en markdown propre pour un découpage et une récupération en aval. Par défaut, il supprime les éléments de structure (navigation, pieds de page, scripts).

Installation :

Pour une conversion markdown par défaut :

uv add "mistralai-search-toolkit[html-converter-markdownify]"

uv add "mistralai-search-toolkit[html-converter-markdownify]"

Ou utilisez uniquement la bibliothèque de base si vous fournissez un convertisseur personnalisé.

Exemple :

from mistralai.search.toolkit.ingestion.extractors import HTMLExtractor

extractor = HTMLExtractor()
document = await extractor.extract(file)

from mistralai.search.toolkit.ingestion.extractors import HTMLExtractor

extractor = HTMLExtractor()
document = await extractor.extract(file)

Le convertisseur par défaut est MarkdownifyConverter, basé sur la bibliothèque markdownify (MIT). Il est configuré pour produire un markdown propre avec des titres ATX, des styles de puces cohérents, une détection des langages dans les blocs de code et une suppression complète des sous-arborescences pour les balises de structure.

Configuration du convertisseur par défaut :

MarkdownifyConverter accepte plusieurs options pour personnaliser son comportement :

from mistralai.search.toolkit.ingestion.extractors import HTMLExtractor, MarkdownifyConverter

# Use default settings
converter = MarkdownifyConverter()

# Or customize: only strip <script> and <style>, disable id/class filtering
converter = MarkdownifyConverter(
    ignore_tags=["script", "style"],
    ignore_ids=[],
    ignore_classes=[],
)

extractor = HTMLExtractor(converter=converter)
document = await extractor.extract(file)

from mistralai.search.toolkit.ingestion.extractors import HTMLExtractor, MarkdownifyConverter

# Use default settings
converter = MarkdownifyConverter()

# Or customize: only strip <script> and <style>, disable id/class filtering
converter = MarkdownifyConverter(
    ignore_tags=["script", "style"],
    ignore_ids=[],
    ignore_classes=[],
)

extractor = HTMLExtractor(converter=converter)
document = await extractor.extract(file)

Options MarkdownifyConverter :

Option	Type	Par défaut	Description
`ignore_tags`	`list[str] \| None`	`DEFAULT_IGNORE_TAGS`	Balises HTML à supprimer entièrement, y compris tous leurs enfants. Si `None`, utilise la liste par défaut.
`ignore_ids`	`list[str] \| None`	`DEFAULT_IGNORE_IDS`	Valeurs d'attribut `id` d'élément à supprimer (correspondance littérale). L'intégralité du sous-arbre est supprimée. Si `None`, utilise la liste par défaut.
`ignore_classes`	`list[str] \| None`	`DEFAULT_IGNORE_CLASSES`	Expressions régulières comparées à chaque classe CSS d'un élément. Lorsque qu'une classe correspond, l'intégralité du sous-arbre est supprimée. Si `None`, utilise la liste par défaut.
`escape_misc`	`bool`	`True`	Échapper les caractères markdown divers (par ex. `\|` dans les cellules de tableau).

Balises ignorées par défaut : head, header, script, style, title, footer, form, button, nav, iframe.

IDs ignorés par défaut : footer, sidebar, cookie, metadata.

Motifs de classes ignorées par défaut : footer, ^ad-, ^ad_, ^menu$, ^newsletter$, ^metadata$, ^muted$, vot(e|ing).

Convertisseur personnalisé :

Vous pouvez injecter n'importe quel objet qui implémente le protocole HtmlToMarkdownConverter :

from mistralai.search.toolkit.ingestion.extractors import HTMLExtractor, HtmlToMarkdownConverter

class MyConverter(HtmlToMarkdownConverter):
    def convert(self, html: str) -> str:
        return html  # your conversion logic

extractor = HTMLExtractor(converter=MyConverter())
document = await extractor.extract(file)

from mistralai.search.toolkit.ingestion.extractors import HTMLExtractor, HtmlToMarkdownConverter

class MyConverter(HtmlToMarkdownConverter):
    def convert(self, html: str) -> str:
        return html  # your conversion logic

extractor = HTMLExtractor(converter=MyConverter())
document = await extractor.extract(file)

Paramètres :

Paramètre	Type	Par défaut	Description
`encoding`	`str`	`"utf-8"`	Encodage du fichier HTML
`decode_errors`	`str`	`"strict"`	Gestion des erreurs de décodage (`"strict"`, `"ignore"`, `"replace"`)
`converter`	`HtmlToMarkdownConverter \| None`	`None`	Instance de convertisseur personnalisée. Si `None`, le `MarkdownifyConverter` par défaut est utilisé

Fonctionnalités :

Convertit le HTML en markdown propre avec suppression personnalisable
Préserve la structure (titres, listes, tableaux)
Suppression des éléments de structure (navigation, pieds de page, publicités, etc.)
Prise en charge des convertisseurs personnalisés pour des implémentations alternatives HTML vers markdown

Extracteur de feuilles de calcul

Extracteur pour les documents de type tableur (XLSX/XLS/ODS), produisant un CSV par feuille.

Installation :

uv add "mistralai-search-toolkit[extractor-spreadsheet]"

uv add "mistralai-search-toolkit[extractor-spreadsheet]"

Exemple :

from mistralai.search.toolkit.ingestion.extractors import SpreadsheetExtractor

extractor = SpreadsheetExtractor(
    include_sheet_name=True,  # Include sheet name in output
    row_limit=None,           # Optional row limit per sheet
    col_limit=None,           # Optional column limit per sheet
)
document = await extractor.extract(file)

from mistralai.search.toolkit.ingestion.extractors import SpreadsheetExtractor

extractor = SpreadsheetExtractor(
    include_sheet_name=True,  # Include sheet name in output
    row_limit=None,           # Optional row limit per sheet
    col_limit=None,           # Optional column limit per sheet
)
document = await extractor.extract(file)

Options de configuration :

Option	Type	Par défaut	Objectif
`include_sheet_name`	bool	True	Ajouter le nom de la feuille au début de chaque bloc CSV
`row_limit`	int \| None	None	Nombre maximal de lignes par feuille (None = aucune limite)
`col_limit`	int \| None	Aucune	Nombre maximum de colonnes par feuille (Aucune = aucune limite)
`skip_empty_sheets`	bool	True	Ignorer les feuilles sans données
`preserve_formula_values`	bool	True	Utiliser les résultats des formules, pas leur texte

Comportement :

Chaque feuille devient un bloc CSV distinct dans le document
Les cellules fusionnées sont étendues avec les valeurs répétées
Les formules sont évaluées (sauf si preserve_formula_values=False)
Les en-têtes sont déduits de la première ligne

Extracteur d’e-mails

Extrait les fichiers d’e-mails (.eml et .msg) dans un unique document en Markdown avec l’objet, l’expéditeur, les destinataires, la date et le corps. Les corps au format HTML sont convertis en Markdown lorsqu’ils sont disponibles.

Installation :

uv add "mistralai-search-toolkit[extractor-email]"

uv add "mistralai-search-toolkit[extractor-email]"

Ajoute les dépendances eml-parser et extract-msg.

Exemple :

from mistralai.search.toolkit.ingestion.extractors import EmailExtractor

extractor = EmailExtractor()
document = await extractor.extract(file)

from mistralai.search.toolkit.ingestion.extractors import EmailExtractor

extractor = EmailExtractor()
document = await extractor.extract(file)

Fonctionnalités :

Analyse les formats EML (RFC 822) et MSG d’Outlook
Génère un Markdown structuré (objet, expéditeur, destinataire, CC, date, corps)
Préfère le corps en texte brut ; utilise le HTML converti en Markdown en solution de repli

Pièces jointes : utilisez extract_email_attachments (ou extract_eml_attachments / extract_msg_attachments) pour traiter les pièces jointes du même fichier d’e-mail. Elles renvoyent une liste de EmailAttachment (nom de fichier, type de contenu, données, extension) que vous pouvez transmettre à d’autres extracteurs :

from mistralai.search.toolkit.ingestion.extractors import (
    EmailExtractor,
    EmailAttachment,
    extract_email_attachments,
)

document = await EmailExtractor().extract(file)
attachments = extract_email_attachments(file.raw, extension="eml")
for att in attachments:
    # Build a File from att.data and run through the right extractor
    ...

from mistralai.search.toolkit.ingestion.extractors import (
    EmailExtractor,
    EmailAttachment,
    extract_email_attachments,
)

document = await EmailExtractor().extract(file)
attachments = extract_email_attachments(file.raw, extension="eml")
for att in attachments:
    # Build a File from att.data and run through the right extractor
    ...

Extracteur Numbers

Extracteur pour les documents Apple Numbers (.numbers), générant un CSV par tableau/feuille.

Installation :

uv add "mistralai-search-toolkit[extractor-spreadsheet]"

uv add "mistralai-search-toolkit[extractor-spreadsheet]"

Exemple :

from mistralai.search.toolkit.ingestion.extractors import NumbersExtractor, NumbersOptions

extractor = NumbersExtractor(
    row_limit=1000,           # Cap rows per table
    col_limit=50,             # Cap columns per table
    include_sheet_name=True,  # Prefix each block with sheet/table name
)
document = await extractor.extract(file)

from mistralai.search.toolkit.ingestion.extractors import NumbersExtractor, NumbersOptions

extractor = NumbersExtractor(
    row_limit=1000,           # Cap rows per table
    col_limit=50,             # Cap columns per table
    include_sheet_name=True,  # Prefix each block with sheet/table name
)
document = await extractor.extract(file)

Utilisez iter_csv_pages(blob, options=...) pour itérer sur des chaînes CSV sans construire un Document complet.

Extracteur Legacy Office

Extrait les anciens formats Office (.doc, .ppt, .hwp, .hwpx) en les convertissant en PDF avec PyMuPDF Pro, puis en lançant Mistral OCR. Ne gère pas les fichiers .xls — utilisez SpreadsheetExtractor pour cela.

Installation :

uv add "mistralai-search-toolkit[extractor-pymupdf]"

uv add "mistralai-search-toolkit[extractor-pymupdf]"

Nécessite une licence PyMuPDF Pro pour la prise en charge complète des formats.

Exemple :

from mistralai.client import Mistral
from mistralai.search.toolkit.ingestion.extractors import LegacyOfficeExtractor, MistralOCRExtractor

ocr_extractor = MistralOCRExtractor(
    client=Mistral(api_key="your-api-key")
)
extractor = LegacyOfficeExtractor(
    ocr_extractor,
    pymupdf_license_key="your-license-key",  # Optional
)
document = await extractor.extract(
    file,
    include_image_base64=True,
    include_image_annotation=True,
)

from mistralai.client import Mistral
from mistralai.search.toolkit.ingestion.extractors import LegacyOfficeExtractor, MistralOCRExtractor

ocr_extractor = MistralOCRExtractor(
    client=Mistral(api_key="your-api-key")
)
extractor = LegacyOfficeExtractor(
    ocr_extractor,
    pymupdf_license_key="your-license-key",  # Optional
)
document = await extractor.extract(
    file,
    include_image_base64=True,
    include_image_annotation=True,
)

Fonctionnalités :

Convertit le document au format hérité en PDF en mémoire, puis délègue à MistralOCRExtractor
Prend en charge les mêmes options OCR que Mistral OCR (par exemple, http_headers, image_limit)

Créer des extracteurs personnalisés

Implémentez le protocole DocumentExtractor :

import base64
from mistralai.search.toolkit.ingestion.extractors import DocumentExtractor
from mistralai.search.toolkit.document import Document, Page
from mistralai.search.toolkit.ingestion import File

class Base64FileExtractor(DocumentExtractor):
    """Extract content from base64-encoded text files."""

    async def extract(self, file: File, **kwargs) -> Document:
        decoded_content = base64.b64decode(file.raw).decode("utf-8")

        return Document(
            id=file.id,
            extractor_type="text",
            content=decoded_content,
            pages=[Page(page_number=1, markdown=decoded_content, ref_to_images={})],
            metadata={"encoding": "base64"},
            filename=file.name,
            filepath=file.path,
        )

extractor = Base64FileExtractor()
document = await extractor.extract(b64_file)

import base64
from mistralai.search.toolkit.ingestion.extractors import DocumentExtractor
from mistralai.search.toolkit.document import Document, Page
from mistralai.search.toolkit.ingestion import File

class Base64FileExtractor(DocumentExtractor):
    """Extract content from base64-encoded text files."""

    async def extract(self, file: File, **kwargs) -> Document:
        decoded_content = base64.b64decode(file.raw).decode("utf-8")

        return Document(
            id=file.id,
            extractor_type="text",
            content=decoded_content,
            pages=[Page(page_number=1, markdown=decoded_content, ref_to_images={})],
            metadata={"encoding": "base64"},
            filename=file.name,
            filepath=file.path,
        )

extractor = Base64FileExtractor()
document = await extractor.extract(b64_file)