1. Aperçu
Qu'est-ce que Document AI ?
Document AI est une solution de compréhension de documents qui utilise des données non structurées (documents, e-mails, factures, formulaires, etc.) et facilite leur compréhension, leur analyse et leur consommation. L'API fournit une structure via la classification de contenu, l'extraction d'entités, la recherche avancée, etc.
Dans cet atelier, vous allez apprendre à reconnaître des caractères optiques à l'aide de l'API Document AI avec Python.
Nous utiliserons un fichier PDF du roman classique "Winnie the Pooh" d'AA Milne, qui a récemment été intégré au domaine public aux États-Unis. Ce fichier a été scanné et numérisé par Google Livres.
Points abordés
- Activer l'API Document AI
- Authentifier les requêtes API
- Installer la bibliothèque cliente pour Python
- Comment analyser du texte à partir d'un fichier PDF
- Effectuer des requêtes asynchrones à l'aide de Google Cloud Storage
Prérequis
- Un projet Google Cloud
- Un navigateur (Chrome ou Firefox, par exemple)
- Des connaissances de base sur Python (3.7+)
Enquête
Comment allez-vous utiliser ce tutoriel ?
Quel est votre niveau d'expérience avec Python ?
Quel est votre niveau d'expérience avec les services Google Cloud ?
2. Prérequis
Accédez à https://gcpcredits.com/io2022 et cliquez sur le bouton "Cliquez ici pour accéder à vos crédits" :
Dans la boîte de dialogue qui s'affiche, acceptez les conditions d'utilisation en cliquant sur le bouton "Accepter et continuer" :
Après avoir accepté les conditions d'utilisation, vous serez redirigé vers une page récapitulative de facturation comprenant un panneau semblable à celui-ci situé dans l'angle inférieur droit:
Enfin, lorsque vous créez votre premier projet, une boîte de dialogue vous permet d'attribuer un compte de facturation à celui-ci. Sélectionnez le compte de facturation associé à vos crédits gratuits, puis cliquez sur le bouton "Créer" :
En résumé, vous disposez à présent d'un compte de facturation et d'un projet, qui sont associés, de sorte que toutes les activités effectuées dans l'atelier de programmation d'aujourd'hui seront financées par vos crédits gratuits**.**
Configuration de l'environnement au rythme de chacun
- Connectez-vous à Cloud Console, puis créez un projet ou réutilisez un projet existant. Si vous ne possédez pas encore de compte Gmail ou Google Workspace, vous devez en créer un.
Mémorisez l'ID du projet, un nom unique parmi tous les projets Google Cloud. (L'ID de projet ci-dessus a déjà été utilisé et ne fonctionnera pas pour vous.) Vous devrez indiquer cet ID ultérieurement en tant que PROJECT_ID.
- Vous devez ensuite activer la facturation dans Cloud Console pour pouvoir utiliser les ressources Google Cloud.
Veillez à suivre les instructions figurant dans la section "Effectuer un nettoyage". Cette section vous indique comment arrêter les ressources afin d'éviter qu'elles ne vous soient facturées au-delà de ce tutoriel. Les nouveaux utilisateurs de Google Cloud peuvent participer au programme d'essai gratuit pour bénéficier d'un crédit de 300 $.
Démarrer Cloud Shell
Bien que vous puissiez exécuter Google Cloud à distance depuis votre ordinateur portable, vous allez utiliser Google Cloud Shell, un environnement de ligne de commande exécuté dans le cloud, lors de cet atelier de programmation.
Activer Cloud Shell
- Dans Cloud Console, cliquez sur Activer Cloud Shell .
Si vous n'avez jamais démarré Cloud Shell auparavant, un écran intermédiaire s'affiche en dessous de la ligne de flottaison, décrivant de quoi il s'agit. Si tel est le cas, cliquez sur Continuer. Cet écran ne s'affiche qu'une seule fois. Voici à quoi il ressemble :
Le provisionnement et la connexion à Cloud Shell ne devraient prendre que quelques instants.
Cloud Shell vous permet d'accéder au terminal d'une machine virtuelle hébergée dans le cloud. La machine virtuelle contient tous les outils de développement nécessaires. Elle intègre un répertoire d'accueil persistant de 5 Go et s'exécute sur Google Cloud, ce qui améliore nettement les performances réseau et l'authentification. Vous pouvez travailler dans la plupart des cas avec un simple navigateur.
En principe, une fois que vous êtes connecté à Cloud Shell, vous êtes authentifié, et le projet est défini sur votre ID de projet.
- Exécutez la commande suivante dans Cloud Shell pour vérifier que vous êtes authentifié :
gcloud auth list
Résultat de la commande
Credentialed Accounts
ACTIVE ACCOUNT
* <my_account>@<my_domain.com>
To set the active account, run:
$ gcloud config set account `ACCOUNT`
gcloud config list project
Résultat de la commande
[core] project = <PROJECT_ID>
Si vous obtenez un résultat différent, exécutez cette commande :
gcloud config set project <PROJECT_ID>
Résultat de la commande
Updated property [core/project].
3. Activer l'API Document AI
Avant de pouvoir utiliser Document AI, vous devez activer l'API. Ouvrez Cloud Console dans votre navigateur.
- Dans la barre de recherche située en haut de la console, recherchez "API Document AI", puis cliquez sur Activer pour utiliser l'API dans votre projet Google Cloud.
- Vous pouvez également activer l'API à l'aide de la commande
gcloudsuivante.
gcloud services enable documentai.googleapis.com
Ce type de message s'affiche :
Operation "operations/..." finished successfully.
Vous pouvez désormais utiliser Document AI !
4. Créer et tester un outil de traitement
Vous devez d'abord créer une instance du processeur de reconnaissance optique des caractères pour les documents qui effectuera l'extraction. Pour cela, utilisez Cloud Console ou l'API Processor Management.
Cloud Console
- Dans la console, accédez à la page de présentation de la plate-forme Document AI.
- Cliquez sur Créer un processeur, puis sélectionnez ROC du document
. - Spécifiez un nom de processeur, puis sélectionnez votre région dans la liste.
- Cliquez sur Créer pour créer le processeur.
- Copiez votre ID de processeur. Vous devrez l'utiliser dans votre code plus tard.
Vous pouvez tester votre outil de traitement dans la console en important un document. Cliquez sur Importer un document de test et sélectionnez un document à analyser.
Vous pouvez télécharger le fichier PDF ci-dessous, qui contient les trois premières pages de notre roman.
Votre résultat doit se présenter comme suit : 
Bibliothèque cliente Python
Suivez cet atelier de programmation pour découvrir comment gérer les processeurs IA de Document avec la bibliothèque cliente Python:
Gérer des processeurs Document AI avec Python – Atelier de programmation
5. Authentifier les requêtes API
Pour envoyer des requêtes à l'API Document AI, vous devez utiliser un compte de service. Un compte de service appartient à votre projet et permet à la bibliothèque cliente Python d'effectuer des requêtes API. Comme tout autre compte utilisateur, un compte de service est représenté par une adresse e-mail. Dans cette section, vous allez utiliser le SDK Cloud pour créer un compte de service, puis créer les identifiants nécessaires pour vous authentifier en tant que compte de service.
Commencez par définir une variable d'environnement avec votre PROJECT_ID, que vous utiliserez tout au long de cet atelier de programmation :
export GOOGLE_CLOUD_PROJECT=$(gcloud config get-value core/project)
Créez ensuite un compte de service pour accéder à l'API Document AI à l'aide de la commande suivante :
gcloud iam service-accounts create my-docai-sa \
--display-name "my-docai-service-account"
Créez ensuite des identifiants permettant à votre code Python de se connecter avec ce nouveau compte de service, et enregistrez-les dans un fichier JSON ~/key.json à l'aide de la commande suivante :
gcloud iam service-accounts keys create ~/key.json \
--iam-account my-docai-sa@${GOOGLE_CLOUD_PROJECT}.iam.gserviceaccount.com
Enfin, définissez la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS, qui permet à la bibliothèque de rechercher vos identifiants. Pour en savoir plus sur l'authentification de ce formulaire, consultez ce guide. La variable d'environnement doit être définie sur le chemin d'accès complet au fichier JSON d'identifiants que vous avez créé, à l'aide de la commande suivante :
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/key.json"
6. Installer la bibliothèque cliente
Installez les bibliothèques clientes:
pip3 install --upgrade google-cloud-documentai
pip3 install --upgrade google-cloud-storage
Ce type de message s'affiche :
... Installing collected packages: google-cloud-documentai Successfully installed google-cloud-documentai-1.2.0 . . Installing collected packages: google-cloud-storage Successfully installed google-cloud-storage-1.43.0
Vous êtes maintenant prêt à utiliser l'API Document AI !
Démarrer Python en mode interactif
Dans ce tutoriel, vous allez utiliser un interpréteur Python interactif, appelé IPython. Démarrez une session en exécutant ipython dans Cloud Shell. Cette commande exécute l'interpréteur Python dans une session interactive.
ipython
Ce type de message s'affiche :
Python 3.7.3 (default, Jul 25 2020, 13:03:44) Type 'copyright', 'credits' or 'license' for more information IPython 7.30.1 -- An enhanced Interactive Python. Type '?' for help. In [1]:
7. Télécharger l'exemple de PDF
Nous disposons d'un exemple de document contenant les trois premières pages du roman.
Vous pouvez télécharger le fichier PDF via le lien suivant. Importez-le ensuite dans l'instance Cloud Shell.
Vous pouvez également le télécharger depuis notre bucket Google Cloud Storage public à l'aide de gsutil.
gsutil cp gs://cloud-samples-data/documentai/codelabs/ocr/Winnie_the_Pooh_3_Pages.pdf .
8. Envoyer une requête de traitement de document synchrone
Au cours de cette étape, vous allez traiter les trois premières pages du roman à l'aide du point de terminaison synchrone. Cette méthode est particulièrement adaptée aux documents de petite taille qui sont stockés localement. Consultez la liste complète des outils de traitement pour connaître le nombre maximal de pages et la taille de fichier pour chaque type d'outil de traitement.
Copiez le code suivant dans votre session iPython :
from google.cloud import documentai_v1 as documentai
def process_document(project_id: str, location: str,
processor_id: str, file_path: str,
mime_type: str) -> documentai.Document:
"""
Processes a document using the Document AI API.
"""
# Instantiates a client
documentai_client = documentai.DocumentProcessorServiceClient()
# The full resource name of the processor, e.g.:
# projects/project-id/locations/location/processor/processor-id
# You must create new processors in the Cloud Console first
resource_name = documentai_client.processor_path(
project_id, location, processor_id)
# Read the file into memory
with open(file_path, "rb") as image:
image_content = image.read()
# Load Binary Data into Document AI RawDocument Object
raw_document = documentai.RawDocument(
content=image_content, mime_type=mime_type)
# Configure the process request
request = documentai.ProcessRequest(
name=resource_name, raw_document=raw_document)
# Use the Document AI client to process the sample form
result = documentai_client.process_document(request=request)
return result.document
def main():
"""
Run the codelab.
"""
project_id = 'YOUR_PROJECT_ID'
location = 'YOUR_PROJECT_LOCATION' # Format is 'us' or 'eu'
processor_id = 'YOUR_PROCESSOR_ID' # Create processor in Cloud Console
file_path = 'Winnie_the_Pooh_3_Pages.pdf' # The local file in your current working directory
# Refer to https://cloud.google.com/document-ai/docs/processors-list for the supported file types
mime_type = 'application/pdf'
document = process_document(project_id=project_id, location=location,
processor_id=processor_id, file_path=file_path,
mime_type=mime_type)
print("Document processing complete.")
print(f"Text: {document.text}")
Appelez la fonction principale. Le texte devrait être extrait et imprimé dans la console.
main()
Si vous utilisez notre exemple de document, vous devriez obtenir le résultat suivant :
Document processing complete. Text: CHAPTER I IN WHICH We Are Introduced to Winnie-the-Pooh and Some Bees, and the Stories Begin Here is Edward Bear, coming downstairs now, bump, bump, bump, on the back of his head, behind Christopher Robin. It is, as far as he knows, the only way of coming downstairs, but sometimes he feels that there really is another way, if only he could stop bumping for a moment and think of it. And then he feels that perhaps there isn't. Anyhow, here he is at the bottom, and ready to be introduced to you. Winnie-the-Pooh. When I first heard his name, I said, just as you are going to say, "But I thought he was a boy?" "So did I," said Christopher Robin. "Then you can't call him Winnie?" "I don't." "But you said " ... Digitized by Google
9. Envoyer une requête de processus asynchrone
Supposons maintenant que vous souhaitiez lire le texte du roman dans son intégralité.
- La méthode
process_documents()limite le nombre de pages et la taille de fichier pouvant être envoyées. Elle ne permet d'utiliser qu'un fichier de document par appel d'API. - La méthode
batch_process_documents()permet le traitement asynchrone de fichiers plus volumineux et le traitement par lot de plusieurs fichiers.
Au cours de cette étape, nous allons traiter l'intégralité du roman "Winnie l'ourson" avec l'API Document AI Asynchrone et générer le texte dans un bucket Google Cloud Storage.
Importer un fichier PDF dans Cloud Storage
La méthode batch_process_documents() accepte actuellement les fichiers provenant de Google Cloud Storage. Pour en savoir plus sur la structure des objets, consultez la section documentai_v1.types.BatchProcessRequest.
Dans cet exemple, vous pouvez copier le fichier à partir de notre exemple de bucket de données...
gsutil cp gs://cloud-samples-data/documentai/codelabs/ocr/Winnie_the_Pooh.pdf gs://YOUR_BUCKET_NAME/
Vous pouvez également télécharger l'exemple de fichier du roman à l'aide du lien ci-dessous et l'importer dans votre propre bucket.
Vous aurez également besoin d'un bucket GCS pour stocker la sortie de l'API.
Utiliser la méthode batch_process_documents()
Copiez le code suivant dans votre session iPython :
import re
from google.api_core.operation import Operation
from google.cloud import documentai_v1 as documentai
from google.cloud import storage
def batch_process_documents(
project_id: str,
location: str,
processor_id: str,
gcs_input_uri: str,
input_mime_type: str,
gcs_output_uri: str,
) -> Operation:
"""
Constructs a request to process a document using the Document AI
Asynchronous API.
"""
# You must set the api_endpoint if you use a location other than 'us', e.g.:
opts = {}
if location == "eu":
opts = {"api_endpoint": "eu-documentai.googleapis.com"}
# Instantiates a client
documentai_client = documentai.DocumentProcessorServiceClient(client_options=opts)
# The full resource name of the processor, e.g.:
# projects/project-id/locations/location/processor/processor-id
# You must create new processors in the Cloud Console first
resource_name = documentai_client.processor_path(project_id, location, processor_id)
# Cloud Storage URI for the Input Document
input_document = documentai.GcsDocument(
gcs_uri=gcs_input_uri, mime_type=input_mime_type
)
# Load GCS Input URI into a List of document files
input_config = documentai.BatchDocumentsInputConfig(
gcs_documents=documentai.GcsDocuments(documents=[input_document])
)
# Cloud Storage URI for Output directory
gcs_output_config = documentai.DocumentOutputConfig.GcsOutputConfig(
gcs_uri=gcs_output_uri
)
# Load GCS Output URI into OutputConfig object
output_config = documentai.DocumentOutputConfig(gcs_output_config=gcs_output_config)
# Configure Process Request
request = documentai.BatchProcessRequest(
name=resource_name,
input_documents=input_config,
document_output_config=output_config,
)
# Future for long-running operations returned from Google Cloud APIs.
operation = documentai_client.batch_process_documents(request)
return operation
def get_documents_from_gcs(
gcs_output_uri: str, operation_name: str
) -> [documentai.Document]:
"""
Download the document output from GCS.
"""
# The GCS API requires the bucket name and URI prefix separately
match = re.match(r"gs://([^/]+)/(.+)", gcs_output_uri)
output_bucket = match.group(1)
prefix = match.group(2)
# The output files will be in a new subdirectory with the Operation ID as the name
operation_id = re.search("operations\/(\d+)", operation_name, re.IGNORECASE).group(1)
output_directory = f"{prefix}/{operation_id}"
storage_client = storage.Client()
# List of all of the files in the directory `gs://gcs_output_uri/operation_id`
blob_list = list(storage_client.list_blobs(output_bucket, prefix=output_directory))
output_documents = []
for blob in blob_list:
# Document AI should only output JSON files to GCS
if ".json" in blob.name:
document = documentai.types.Document.from_json(blob.download_as_bytes())
output_documents.append(document)
else:
print(f"Skipping non-supported file type {blob.name}")
return output_documents
def main():
"""
Run the codelab.
"""
project_id = 'YOUR_PROJECT_ID'
location = 'YOUR_PROJECT_LOCATION' # Format is 'us' or 'eu'
processor_id = 'YOUR_PROCESSOR_ID' # Create processor in Cloud Console
# Format 'gs://input_bucket/directory/file.pdf'
gcs_input_uri = "INPUT_BUCKET_URI"
input_mime_type = "application/pdf"
# Format 'gs://output_bucket/directory'
gcs_output_uri = "YOUR_OUTPUT_BUCKET_URI"
# Batch Process returns a Long Running Operation (LRO)
operation = batch_process_documents(
project_id=project_id,
location=location,
processor_id=processor_id,
gcs_input_uri=gcs_input_uri,
input_mime_type=input_mime_type,
gcs_output_uri=gcs_output_uri,
)
# Format: projects/PROJECT_NUMBER/locations/LOCATION/operations/OPERATION_ID
operation_name = operation.operation.name
# Continually polls the operation until it is complete.
# This could take some time for larger files
print(f"Waiting for operation {operation_name} to complete...")
result = operation.result(timeout=300)
# NOTE: Can also use callbacks for asynchronous processing
#
# def my_callback(future):
# result = future.result()
#
# operation.add_done_callback(my_callback)
print("Document processing complete.")
# Get the Document Objects from the Output Bucket
document_list = get_documents_from_gcs(
gcs_output_uri=gcs_output_uri, operation_name=operation_name
)
for document in document_list:
print(document.text)
Appelez la fonction principale. Vous devriez obtenir en texte complet le roman extrait et imprimé dans la console.
main()
Cela peut prendre un certain temps, car le fichier est beaucoup plus volumineux que l'exemple précédent. (D'accord...)
Cependant, avec l'API asynchrone, vous recevez un ID d'opération qui peut être utilisé pour obtenir le résultat de GCS une fois la tâche terminée.
This is a reproduction of a library book that was digitized by Google as part of an ongoing effort to preserve the information in books and make it universally accessible. TM Google books https://books.google.com ..... He nodded and went out ... and in a moment I heard Winnie-the-Pooh -bump, bump, bump-go-ing up the stairs behind him. Digitized by Google
10. Félicitations
Vous avez utilisé Document AI pour extraire du texte d'un roman à l'aide des API synchrones et asynchrones.
Nous vous encourageons à tester d'autres documents et à explorer les autres outils de traitement disponibles sur la plate-forme.
Effectuer un nettoyage
Pour éviter que les ressources utilisées dans ce tutoriel soient facturées sur votre compte Google Cloud, procédez comme suit :
- Dans Cloud Console, accédez à la page Gérer les ressources.
- Dans la liste des projets, sélectionnez votre projet, puis cliquez sur "Supprimer".
- Dans la boîte de dialogue, saisissez l'ID du projet, puis cliquez sur "Arrêter" pour supprimer le projet.
En savoir plus
- Documentation Document AI
- Bibliothèque cliente Python Document AI
- Exemples de code Document AI pour Python
Licence
Ce document est publié sous une licence Creative Commons Attribution 2.0 Generic.