Rilevare il testo nei file

Il servizio di riconoscimento ottico dei caratteri (OCR) di Vertex AI in Google Distributed Cloud (GDC) con air gap rileva ed estrae il testo dai file PDF e TIFF. Puoi inviare file locali in richieste in linea al metodo API BatchAnnotateFiles o elaborare i file archiviati nei bucket in modo asincrono con il metodo API AsyncBatchAnnotateFiles. Il metodo API BatchAnnotateFiles supporta una singola richiesta per chiamata batch.

Prima di iniziare

Per rilevare il testo nei file, contatta l'amministratore IAM del progetto per richiedere il ruolo AI OCR Developer (ai-ocr-developer) nello spazio dei nomi del progetto.

Per saperne di più su questo ruolo, consulta Prepara le autorizzazioni IAM.

Prima di poter iniziare a utilizzare l'API OCR, devi avere un progetto con l'API OCR abilitata e le credenziali appropriate. Puoi anche installare librerie client per facilitare le chiamate all'API. Per saperne di più, consulta Configura un progetto di riconoscimento dei caratteri.

Rileva il testo con richieste in linea

Il metodo BatchAnnotateFiles rileva il testo da un gruppo di file PDF o TIFF. Invia il file da cui vuoi rilevare il testo direttamente come contenuto nella richiesta API. Il sistema restituisce il testo rilevato risultante in formato JSON nella risposta dell'API.

Devi specificare i valori per i campi nel corpo JSON della richiesta API. La tabella seguente contiene una descrizione dei campi del corpo della richiesta che devi fornire quando utilizzi il metodo API BatchAnnotateFiles per le tue richieste di rilevamento del testo:

Campi del corpo della richiesta	Descrizione del campo
content	I file con il testo da rilevare. Fornisci la rappresentazione Base64 (stringa ASCII) dei contenuti del file binario. Nota: puoi elaborare solo i file archiviati localmente nel tuo ambiente Distributed Cloud.
mime_type	Il tipo di file di origine. Devi impostarlo su uno dei seguenti valori: application/pdf per i file PDF image/tiff per i file TIFF
type	Il tipo di rilevamento del testo di cui hai bisogno dal file. Specifica una delle due funzionalità di annotazione: TEXT_DETECTION rileva ed estrae il testo da qualsiasi file. La risposta JSON include la stringa estratta, le singole parole e i relativi riquadri di delimitazione. DOCUMENT_TEXT_DETECTION estrae anche il testo da un file, ma il servizio ottimizza la risposta per testi e documenti densi. Il file JSON include informazioni su pagina, blocco, paragrafo, parola e interruzione. Per saperne di più su queste funzionalità di annotazione, consulta Funzionalità di riconoscimento ottico dei caratteri.
language_hints	Facoltativo. Elenco delle lingue da utilizzare per il rilevamento del testo. Il sistema interpreta un valore vuoto per questo campo come rilevamento automatico della lingua. Non è necessario impostare il campo language_hints per le lingue basate sull'alfabeto latino. Se conosci la lingua del testo nel file, l'impostazione di un suggerimento migliora i risultati. Come funzionano i suggerimenti per la lingua? Il formato language_hints utilizza le seguenti linee guida per la formattazione dei tag di lingua BCP 47: language ["-" script] ["-" region] *("-" variant) *("-" extension) ["-" privateuse]. Ad esempio, il suggerimento per la lingua "en-t-i0-handwrit" specifica la lingua inglese (en), il singleton dell'estensione di trasformazione (t), il codice dell'estensione di trasformazione del motore del metodo di immissione (i0) e il codice di trasformazione della scrittura a mano libera (handwrit). In sostanza, indica che la lingua è "inglese trasformato dalla scrittura a mano libera". Non è necessario specificare un codice di scrittura perché la lingua "en" implica Latn. Per un elenco delle lingue supportate, consulta Lingue supportate.
pages	Facoltativo. Il numero di pagine del file da elaborare per il rilevamento del testo. Il numero massimo di pagine che puoi specificare è cinque. Se non specifichi il numero di pagine, il servizio elabora le prime cinque pagine del file.

Per informazioni sulla rappresentazione JSON completa, consulta AnnotateFileRequest.

Effettua una richiesta API in linea

Invia una richiesta all'API preaddestrata OCR utilizzando il metodo API REST. In alternativa, interagisci con l'API OCR preaddestrata da uno script Python per rilevare il testo dai file PDF o TIFF.

Nota: il metodo API BatchAnnotateFiles supporta una sola richiesta per chiamata batch.

I seguenti esempi mostrano come rilevare il testo in un file utilizzando l'OCR:

REST

Segui questi passaggi per rilevare il testo nei file utilizzando il metodo dell'API REST:

1. Salva il seguente file request.json per il corpo della richiesta:

   cat <<- EOF > request.json
   {
     "requests": [
       {
         "input_config": {
           "content": BASE64_ENCODED_FILE,
           "mime_type": "application/pdf"
         },
         "features": [
           {
             "type": "FEATURE_TYPE"
           }
         ],
         "image_context": {
           "language_hints": [
             "LANGUAGE_HINT_1",
             "LANGUAGE_HINT_2",
             ...
           ]
         },
         "pages": []
       }
     ]
   }
   EOF
   

   Sostituisci quanto segue:

   • BASE64_ENCODED_FILE: la rappresentazione Base64 (stringa ASCII) dei contenuti del file binario. Questa stringa inizia con caratteri simili a /9j/4QAYRXhpZgAA...9tAVx/zDQDlGxn//2Q==.
   • FEATURE_TYPE: il tipo di rilevamento del testo che ti serve dal file. I valori consentiti sono TEXT_DETECTION o DOCUMENT_TEXT_DETECTION.
   • LANGUAGE_HINT: i tag di lingua BCP 47 da utilizzare come suggerimenti di lingua per il rilevamento del testo, ad esempio en-t-i0-handwrit. Questo campo è facoltativo e il sistema interpreta un valore vuoto come rilevamento automatico della lingua.

2. Ottieni un token di autenticazione.

3. Effettua la richiesta:

   curl

   curl -X POST \
     -H "Authorization: Bearer TOKEN" \
     -H "x-goog-user-project: projects/PROJECT_ID" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     https://ENDPOINT/v1/files:annotate
   

   Sostituisci quanto segue:

   • TOKEN: il token di autenticazione che hai ottenuto.
   • PROJECT_ID: il tuo ID progetto.
   • ENDPOINT: l'endpoint OCR che utilizzi per la tua organizzazione. Per saperne di più, visualizza lo stato del servizio e gli endpoint.

   PowerShell

   $headers = @{
     "Authorization" = "Bearer TOKEN"
     "x-goog-user-project" = "projects/PROJECT_ID"
   }
   
   Invoke-WebRequest
     -Method POST
     -Headers $headers
     -ContentType: "application/json; charset=utf-8"
     -InFile request.json
     -Uri "ENDPOINT/v1/files:annotate" | Select-Object -Expand Content
   

   Sostituisci quanto segue:

   • TOKEN: il token di autenticazione che hai ottenuto.
   • ENDPOINT: l'endpoint OCR che utilizzi per la tua organizzazione. Per saperne di più, visualizza lo stato del servizio e gli endpoint.

Python

Segui questi passaggi per utilizzare il servizio OCR da uno script Python per rilevare il testo in un file:

1. Installa l'ultima versione della libreria client OCR.

2. Imposta le variabili di ambiente richieste in uno script Python.

3. Autentica la richiesta API.

4. Aggiungi il seguente codice allo script Python che hai creato:

   from google.cloud import vision
   import google.auth
   from google.auth.transport import requests
   from google.api_core.client_options import ClientOptions
   
   audience = "https://ENDPOINT:443"
   api_endpoint="ENDPOINT:443"
   
   def vision_client(creds):
     opts = ClientOptions(api_endpoint=api_endpoint)
     return vision.ImageAnnotatorClient(credentials=creds, client_options=opts)
   
   def main():
     creds = None
     try:
       creds, project_id = google.auth.default()
       creds = creds.with_gdch_audience(audience)
       req = requests.Request()
       creds.refresh(req)
     except Exception as e:
       print("Caught exception" + str(e))
       raise e
     return creds
   
   def vision_func(creds):
     vc = vision_client(creds)
     input_config = {"content": "BASE64_ENCODED_FILE"}
     features = [{"type_": vision.Feature.Type.FEATURE_TYPE}]
     # Each requests element corresponds to a single file. To annotate more
     # files, create a request element for each file and add it to
     # the array of requests
     req = {"input_config": input_config, "features": features}
   
     metadata = [("x-goog-user-project", "projects/PROJECT_ID")]
   
     resp = vc.annotate_file(req,metadata=metadata)
   
     print(resp)
   
   if __name__=="__main__":
     creds = main()
     vision_func(creds)
   

   Sostituisci quanto segue:

   • ENDPOINT: l'endpoint OCR che utilizzi per la tua organizzazione. Per saperne di più, visualizza lo stato del servizio e gli endpoint.
   • BASE64_ENCODED_FILE: la rappresentazione Base64 (stringa ASCII) dei contenuti del file. Questa stringa inizia con caratteri simili a /9j/4QAYRXhpZgAA...9tAVx/zDQDlGxn//2Q==.
   • FEATURE_TYPE: il tipo di rilevamento del testo che ti serve dal file. I valori consentiti sono TEXT_DETECTION o DOCUMENT_TEXT_DETECTION.
   • PROJECT_ID: il tuo ID progetto.

5. Salva lo script Python.

6. Esegui lo script Python per rilevare il testo nel file:

   python SCRIPT_NAME
   

   Sostituisci SCRIPT_NAME con il nome che hai assegnato allo script Python, ad esempio vision.py.

Rileva il testo con richieste offline

Il metodo AsyncBatchAnnotateFiles rileva il testo da un batch di file PDF o TIFF eseguendo una richiesta offline (asincrona). I file potrebbero contenere più pagine e più immagini per pagina. I file di origine devono trovarsi in un bucket di archiviazione del tuo progetto Distributed Cloud. Il sistema salva il testo rilevato risultante in formato JSON in un bucket di archiviazione.

Il servizio OCR avvia l'elaborazione offline e restituisce l'ID del processo a lunga esecuzione che esegue il rilevamento del testo sul file. Puoi utilizzare l'ID restituito per monitorare lo stato dell'elaborazione offline. Se sono in corso troppe operazioni, l'elaborazione offline potrebbe non avviarsi immediatamente.

Devi specificare i valori per i campi nel corpo JSON della richiesta API. La tabella seguente contiene una descrizione dei campi del corpo della richiesta che devi fornire quando utilizzi il metodo API AsyncBatchAnnotateFiles per le tue richieste di rilevamento del testo:

Campi del corpo della richiesta	Descrizione del campo
gcs_source.uri	Il percorso URI di un file di origine valido (PDF o TIFF) in un bucket di archiviazione del tuo progetto Distributed Cloud. Questo file contiene il testo che vuoi rilevare. L'utente o il account di servizio richiedente deve disporre almeno dei privilegi di lettura per il file.
mime_type	Il tipo di file di origine. Devi impostarlo su uno dei seguenti valori: application/pdf per i file PDF image/tiff per i file TIFF
type	Il tipo di rilevamento del testo di cui hai bisogno dal file. Specifica una delle due funzionalità di annotazione: TEXT_DETECTION rileva ed estrae il testo da qualsiasi file. La risposta JSON include la stringa estratta, le singole parole e i relativi riquadri di delimitazione. DOCUMENT_TEXT_DETECTION estrae anche il testo da un file, ma il servizio ottimizza la risposta per testi e documenti densi. Il file JSON include informazioni su pagina, blocco, paragrafo, parola e interruzione. Per saperne di più su queste funzionalità di annotazione, consulta Funzionalità di riconoscimento ottico dei caratteri.
gcs_destination.uri	Il percorso URI di un bucket di archiviazione del tuo progetto Distributed Cloud in cui salvare i file di output. Questa è la località in cui vuoi archiviare i risultati del rilevamento. L'utente o il account di servizio richiedente deve disporre dell'autorizzazione in scrittura per il bucket.

Archivia il file di origine in un bucket di archiviazione

Prima di inviare una richiesta, devi assicurarti che il account di servizio OCR disponga delle autorizzazioni in lettura per il bucket di input e delle autorizzazioni in scrittura per il bucket di output.

I bucket di input e output possono essere diversi e trovarsi in spazi dei nomi di progetti diversi. Ti consigliamo di utilizzare gli stessi bucket di input e output per evitare errori, ad esempio l'archiviazione dei risultati in bucket errati.

Segui questi passaggi per archiviare il file da cui vuoi rilevare il testo in un bucket di archiviazione:

1. Configura la CLI gdcloud per l'archiviazione di oggetti.

2. Crea un bucket di archiviazione nello spazio dei nomi del progetto.Utilizza una classe di archiviazione Standard.

   Puoi creare il bucket di archiviazione eseguendo il deployment di una risorsa Bucket nello spazio dei nomi del progetto:

   apiVersion: object.gdc.goog/v1
   kind: Bucket
   metadata:
     name: ocr-async-bucket
     namespace: PROJECT_NAMESPACE
   spec:
     description: bucket for async ocr
     storageClass: Standard
     bucketPolicy:
       lockingPolicy:
         defaultObjectRetentionDays: 90
   

3. Concedi le autorizzazioni read e write sul bucket al account di servizio (g-vai-ocr-sie-sa) utilizzato dal servizio OCR.

   Per creare il ruolo e l'associazione dei ruoli utilizzando risorse personalizzate, segui questi passaggi:

   1. Crea il ruolo eseguendo il deployment di una risorsa Role nello spazio dei nomi del progetto:

        apiVersion: rbac.authorization.k8s.io/v1
        kind: Role
        metadata:
          name: ocr-async-reader-writer
          namespace: PROJECT_NAMESPACE
        rules:
          -
            apiGroups:
              - object.gdc.goog
            resources:
              - buckets
            verbs:
              - read-object
              - write-object
      

   2. Crea l'associazione dei ruoli eseguendo il deployment di una risorsa RoleBinding nello spazio dei nomi del progetto:

        apiVersion: rbac.authorization.k8s.io/v1
        kind: RoleBinding
      
        metadata:
          name: ocr-async-reader-writer-rolebinding
          namespace: PROJECT_NAMESPACE
        roleRef:
          apiGroup: rbac.authorization.k8s.io
          kind: Role
          name: ocr-async-reader-writer
        subjects:
          -
            kind: ServiceAccount
            name: g-vai-ocr-sie-sa
            namespace: g-vai-ocr-sie
      

4. Carica il file nel bucket di archiviazione che hai creato. Per saperne di più, consulta Carica e scarica oggetti di archiviazione nei progetti.

Effettua una richiesta API offline

Invia una richiesta all'API preaddestrata OCR utilizzando il metodo API REST. In alternativa, interagisci con l'API OCR preaddestrata da uno script Python per rilevare il testo dai file PDF o TIFF.

I seguenti esempi mostrano come rilevare il testo in un file utilizzando l'OCR:

REST

Segui questi passaggi per rilevare il testo nei file utilizzando il metodo dell'API REST:

1. Salva il seguente file request.json per il corpo della richiesta:

   cat <<- EOF > request.json
   {
     "parent": PROJECT_ID,
     "requests":[
       {
         "input_config": {
           "gcs_source": {
             "uri": "SOURCE_FILE"
           },
           "mime_type": "application/pdf"
         },
         "features": [
           {
             "type": "FEATURE_TYPE"
           }
         ],
         "output_config": {
           "gcs_destination": {
             "uri": "DESTINATION_BUCKET"
           }
         }
       }
     ]
   }
   EOF
   

   Sostituisci quanto segue:

   • PROJECT_ID: il tuo ID progetto.
   • SOURCE_FILE: il percorso URI di un file di origine valido (PDF o TIFF) in un bucket di archiviazione del tuo progetto cloud Distributed Cloud.
   • FEATURE_TYPE: il tipo di rilevamento del testo che ti serve dal file. I valori consentiti sono TEXT_DETECTION o DOCUMENT_TEXT_DETECTION.
   • DESTINATION_BUCKET: il percorso URI di un bucket di archiviazione del tuo progetto Distributed Cloud in cui salvare i file di output.

2. Ottieni un token di autenticazione.

3. Effettua la richiesta:

   curl

   curl -X POST \
     -H "Authorization: Bearer TOKEN" \
     -H "x-goog-user-project: projects/PROJECT_ID" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     https://ENDPOINT/v1/files:asyncBatchAnnotate
   

   Sostituisci quanto segue:

   • TOKEN: il token di autenticazione che hai ottenuto.
   • PROJECT_ID: il tuo ID progetto.
   • ENDPOINT: l'endpoint OCR che utilizzi per la tua organizzazione. Per saperne di più, visualizza lo stato del servizio e gli endpoint.

   PowerShell

   $headers = @{
     "Authorization" = "Bearer TOKEN"
     "x-goog-user-project" = "projects/PROJECT_ID"
   }
   
   Invoke-WebRequest
     -Method POST
     -Headers $headers
     -ContentType: "application/json; charset=utf-8"
     -InFile request.json
     -Uri "ENDPOINT/v1/files:asyncBatchAnnotate" | Select-Object -Expand Content
   

   Sostituisci quanto segue:

   • TOKEN: il token di autenticazione che hai ottenuto.
   • ENDPOINT: l'endpoint OCR che utilizzi per la tua organizzazione. Per saperne di più, visualizza lo stato del servizio e gli endpoint.

Python

Segui questi passaggi per utilizzare il servizio OCR da uno script Python per rilevare il testo in un file:

1. Installa l'ultima versione della libreria client OCR.

2. Imposta le variabili di ambiente richieste in uno script Python.

3. Autentica la richiesta API.

4. Aggiungi il seguente codice allo script Python che hai creato:

   from google.cloud import vision
   import google.auth
   from google.auth.transport import requests
   from google.api_core.client_options import ClientOptions
   
   audience = "https://ENDPOINT:443"
   api_endpoint="ENDPOINT:443"
   
   def vision_client(creds):
     opts = ClientOptions(api_endpoint=api_endpoint)
     return vision.ImageAnnotatorClient(credentials=creds, client_options=opts)
   
   def vision_func_async(creds):
     vc = vision_client(creds)
     features = [{"type_": vision.Feature.Type.FEATURE_TYPE}]
     input_config = {"gcs_source":{"uri":"SOURCE_FILE"},"mime_type": "application/pdf"}
     output_config = {"gcs_destination": {"uri": "DESTINATION_BUCKET"}}
     req = {"input_config": input_config, "output_config": output_config, "features":features}
     reqs = {"requests":[req],"parent":"PROJECT_ID"}
   
     metadata = [("x-goog-user-project", "projects/PROJECT_ID")]
   
     operation = vc.async_batch_annotate_files(request=reqs, metadata=metadata)
     lro = operation.operation
     resp = operation.result()
   
   def main():
     creds = None
     try:
       creds, project_id = google.auth.default()
       creds = creds.with_gdch_audience(audience)
       req = requests.Request()
       creds.refresh(req)
     except Exception as e:
       print("Caught exception" + str(e))
       raise e
     return creds
   
   if __name__=="__main__":
     creds = main()
     vision_func_async(creds)
   

   Sostituisci quanto segue:

   • ENDPOINT: l'endpoint OCR che utilizzi per la tua organizzazione. Per saperne di più, visualizza lo stato del servizio e gli endpoint.
   • FEATURE_TYPE: il tipo di rilevamento del testo che ti serve dal file. I valori consentiti sono TEXT_DETECTION o DOCUMENT_TEXT_DETECTION.
   • SOURCE_FILE: il percorso URI di un file di origine valido (PDF o TIFF) in un bucket di archiviazione del tuo progetto cloud Distributed Cloud.
   • DESTINATION_BUCKET: il percorso URI di un bucket di archiviazione del tuo progetto Distributed Cloud in cui salvare i file di output.
   • PROJECT_ID: il tuo ID progetto.

5. Salva lo script Python.

6. Esegui lo script Python per rilevare il testo nel file:

   python SCRIPT_NAME
   

   Sostituisci SCRIPT_NAME con il nome che hai assegnato allo script Python, ad esempio vision.py.

Puoi utilizzare il nome dell'operazione restituito dal metodo AsyncBatchAnnotateFiles per verificare lo stato dell'operazione.

Ottieni lo stato dell'operazione

Il metodo get restituisce l'ultimo stato di un'operazione a lunga esecuzione, ad esempio la richiesta offline per il rilevamento del testo. Utilizza questo metodo per controllare lo stato dell'operazione, come nell'esempio seguente:

curl -X GET "http://ENDPOINT/v1/OPERATION_NAME"

Sostituisci OPERATION_NAME con il nome dell'operazione restituito dal metodo AsyncBatchAnnotateFiles quando hai effettuato la richiesta offline.

Elenca operazioni

Il metodo list restituisce un elenco delle operazioni che corrispondono a un filtro specificato nella richiesta. Il metodo può restituire operazioni da un progetto specifico. Per chiamare il metodo list, specifica l'ID progetto e l'endpoint OCR come nell'esempio seguente:

curl -X GET "http://ENDPOINT/v1/PROJECT_ID?page_size=10"