Document AI en Python
Document AI s'appelle avec google-cloud-documentai (module documentai, qui pointe sur documentai_v1). On n'appelle pas un modèle mais un processeur créé à l'avance dans un projet et une location (us ou eu pour la plupart), identifié par projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID. Le client doit viser l'endpoint de cette même location. La réponse est toujours un objet Document : texte intégral, pages, entités, et coordonnées de chaque élément. Le principal qui appelle a besoin de roles/documentai.apiUser ; en lot, le processeur lit et écrit dans Cloud Storage. Les exemples suivent google-cloud-documentai 3.15 et google-cloud-documentai-toolbox 0.17.
Choisir le processeur
| Processeur (type dans l'API) | Ce qu'il renvoie | Pages en ligne / en lot | Usage |
|---|---|---|---|
Enterprise Document OCR (OCR_PROCESSOR) |
Texte, blocs, lignes, jetons, langues, qualité du scan | 15 / 500 | Numériser, rendre cherchable |
Form Parser (FORM_PARSER_PROCESSOR) |
OCR, paires clé/valeur (form_fields), cases à cocher, tableaux |
15 / 100 | Formulaires génériques |
Layout Parser (LAYOUT_PARSER_PROCESSOR) |
document_layout (titres, paragraphes, listes, tableaux) et chunked_document |
15 / 500 | Préparer un corpus pour du RAG ; PDF, HTML, DOCX, PPTX, XLSX |
Custom Extractor (CUSTOM_EXTRACTION_PROCESSOR) |
entities selon un schéma défini par l'utilisateur |
15 / 200 | Champs métier ; génératif (Gemini) ou modèle entraîné |
| Custom Classifier, Custom Splitter | Type de document, découpage d'un lot en documents | 15 / 200, 15 / 1 000 | Trier un flux hétérogène avant extraction |
| Spécialisés : Invoice, Expense, Bank Statement, Pay Slip, W2, pièces d'identité | Entités normalisées (normalized_value) |
de 2 à 15 / de 2 à 200 | Documents normalisés, sans entraînement |
En ligne, imageless_mode=True porte la limite à 30 pages, à condition de traiter les pages à la suite depuis la première. Un fichier en ligne pèse 40 Mo au plus (20 Mo pour le Layout Parser) ; un lot compte 5 000 fichiers et 1 Go par fichier au plus.
Versions. Chaque processeur a une version par défaut, et on peut viser une version précise par .../processors/PROCESSOR_ID/processorVersions/VERSION_ID (par exemple pretrained-ocr-v2.1-2024-08-07). Figer la version en production évite qu'un changement de version par défaut modifie les résultats. list_processor_versions et set_default_processor_version gèrent ce choix.
Traitement en ligne
from google.api_core.client_options import ClientOptions
from google.cloud import documentai
LOCATION = "eu"
client = documentai.DocumentProcessorServiceClient(
client_options=ClientOptions(api_endpoint=f"{LOCATION}-documentai.googleapis.com"),
)
nom = client.processor_path("PROJECT_ID", LOCATION, "PROCESSOR_ID")
with open("facture.pdf", "rb") as f:
brut = documentai.RawDocument(content=f.read(), mime_type="application/pdf")
resultat = client.process_document(
request=documentai.ProcessRequest(
name=nom,
raw_document=brut, # ou gcs_document=documentai.GcsDocument(gcs_uri="gs://BUCKET/f.pdf", mime_type="application/pdf")
imageless_mode=True, # 30 pages au lieu de 15, sans les images des pages dans la réponse
process_options=documentai.ProcessOptions(from_start=5), # ou individual_page_selector, from_end
)
)
doc = resultat.document
Lire l'objet Document
Les éléments ne contiennent pas leur texte : ils pointent dans doc.text par un text_anchor, liste de segments start_index/end_index. Un élément peut avoir plusieurs segments (une valeur coupée par un saut de ligne), et un start_index à zéro est omis dans le JSON.
def texte(ancre: documentai.Document.TextAnchor, doc: documentai.Document) -> str:
return "".join(doc.text[s.start_index:s.end_index] for s in ancre.text_segments).strip()
for page in doc.pages:
for champ in page.form_fields: # Form Parser
print(texte(champ.field_name.text_anchor, doc), "=", texte(champ.field_value.text_anchor, doc))
for tableau in page.tables:
entete = [texte(c.layout.text_anchor, doc) for c in tableau.header_rows[0].cells]
for e in doc.entities: # Custom Extractor, processeurs spécialisés
print(e.type_, e.mention_text, e.normalized_value.text, round(e.confidence, 2))
| Champ | Contenu |
|---|---|
text |
Texte intégral dans l'ordre de lecture |
pages[].blocks, paragraphs, lines, tokens |
Mise en page ; layout.bounding_poly.normalized_vertices donne les coordonnées de 0 à 1 |
pages[].form_fields, tables |
Paires clé/valeur, tableaux (header_rows, body_rows, cells) |
entities |
Champs typés : type_, mention_text, normalized_value, confidence, properties (sous-champs), page_anchor |
document_layout, chunked_document |
Structure et fragments du Layout Parser |
shard_info, error |
Position dans un résultat de lot découpé, erreur de traitement |
Traitement par lots
operation = client.batch_process_documents(
request=documentai.BatchProcessRequest(
name=nom,
input_documents=documentai.BatchDocumentsInputConfig(
gcs_prefix=documentai.GcsPrefix(gcs_uri_prefix="gs://BUCKET/entree/"),
),
document_output_config=documentai.DocumentOutputConfig(
gcs_output_config=documentai.DocumentOutputConfig.GcsOutputConfig(
gcs_uri="gs://BUCKET/sortie/",
field_mask="text,entities,pages.pageNumber", # n'écrire que ce qui sert
),
),
)
)
operation.result(timeout=6 * 3600)
metadata = documentai.BatchProcessMetadata(operation.metadata)
for statut in metadata.individual_process_statuses:
print(statut.input_gcs_source, statut.status.code, statut.output_gcs_destination)
Chaque fichier source produit un dossier gs://BUCKET/sortie/OPERATION_ID/INDEX/ qui peut contenir plusieurs JSON (shards), un par tranche de pages ; sharding_config en règle la taille. Lire ces fichiers un par un demande de recoller le texte. La bibliothèque Document AI Toolbox préversion (pip install google-cloud-documentai-toolbox) le fait, et simplifie la lecture :
from google.cloud.documentai_toolbox import document
for d in document.Document.from_batch_process_metadata(metadata): # shards regroupés
for page in d.search_pages(pattern=r"Total\s+TTC"):
for tableau in page.tables:
df = tableau.to_dataframe() # pandas
d.entities_to_bigquery(dataset_name="DATASET", table_name="entites", project_id="PROJECT_ID")
fusion = d.to_merged_documentai_document() # un seul Document
Toolbox charge aussi un résultat par from_gcs(gcs_bucket_name, gcs_prefix), from_document_path ou from_documentai_document, exporte en hOCR, découpe un PDF d'après la sortie d'un Custom Splitter (split_pdf) et convertit vers le format de réponse de Vision AI. Sans code Python, un modèle distant BigQuery appelle le processeur par ML.PROCESS_DOCUMENT sur une table d'objets (voir la fiche Document AI).
Fragments pour le RAG
Le Layout Parser découpe le document en fragments qui respectent les titres et les tableaux ; c'est l'entrée d'un index vectoriel (RAG).
nom_layout = client.processor_path("PROJECT_ID", LOCATION, "LAYOUT_PROCESSOR_ID")
gcs_doc = documentai.GcsDocument(gcs_uri="gs://BUCKET/guide.pdf", mime_type="application/pdf")
options = documentai.ProcessOptions(
layout_config=documentai.ProcessOptions.LayoutConfig(
chunking_config=documentai.ProcessOptions.LayoutConfig.ChunkingConfig(
chunk_size=1024, # en jetons
include_ancestor_headings=True, # jusqu'à deux niveaux de titres ajoutés au fragment
),
),
)
resultat = client.process_document(
request=documentai.ProcessRequest(name=nom_layout, gcs_document=gcs_doc, process_options=options)
)
for fragment in resultat.document.chunked_document.chunks:
print(fragment.chunk_id, fragment.page_span.page_start, fragment.content[:80])
Document AI ou Gemini
Un appel à Gemini avec le PDF et un schéma JSON (Appeler Gemini) suffit pour quelques dizaines de documents, un schéma qui change souvent, ou une question ouverte sur le document ; aucun processeur n'est à créer. Document AI reste le bon choix pour les coordonnées de chaque champ (surlignage, contrôle humain), les tableaux et cases à cocher fidèles, des lots de milliers de fichiers à tarif fixe par page, et les processeurs prêts à l'emploi. Le Custom Extractor génératif est lui-même bâti sur Gemini : il en apporte la souplesse dans ce cadre. La frontière générale est dans Choisir une approche ML.
Pièges
- Endpoint et location différents. Le client vise
us(documentai.googleapis.com) par défaut. Un processeur créé eneus'appelle avecapi_endpoint="eu-documentai.googleapis.com"; appelé par l'endpoint par défaut, la requête échoue. - Limite de pages dépassée. 15 pages en ligne pour la plupart des processeurs, parfois 2 ou 10 : au-delà, erreur
INVALID_ARGUMENT. Passer en lot, activerimageless_mode, ou découper le PDF en amont. - Coût à la page. De 1,50 $ (OCR) à 30 $ (Form Parser, Custom Extractor) les 1 000 pages : faire passer tout un fonds par un extracteur alors qu'une page sur dix porte l'information coûte cher. Classer ou sélectionner les pages d'abord (
individual_page_selector, Custom Classifier). Un processeur personnalisé déployé se facture aussi à l'heure, sans trafic. - Résidence non garantie par certaines versions. Les versions génératives les plus récentes (par exemple
pretrained-layout-parser-v1.6-2026-01-13) passent par l'endpoint global de Gemini, même appelées eneu. Vérifier la version avant de promettre une résidence européenne. - Custom Extractor génératif et langue. Seul l'anglais y est officiellement pris en charge ; tester sur ses propres documents en français avant de s'y fier.
- Lecture d'un seul JSON de lot. Un gros document est découpé en plusieurs fichiers : ne lire que le premier donne un texte tronqué, et les
text_anchorde chaque shard pointent dans son propretext. Toolbox oushard_info.text_offsetpour recoller. - Lot trop long. Un lot aboutit en général en 12 à 24 heures et est annulé au-delà de 24 heures : ce n'est pas un chemin pour du temps réel. Seules les requêtes terminées sont facturées.
Alternatives en logiciel libre
Les équivalents libres — Tesseract et OCRmyPDF, PaddleOCR, Docling et unstructured pour le découpage — sont décrits sur la fiche Document AI.