Questa pagina è stata tradotta dall'API Cloud Translation.

Rilevare il testo nei file

Il servizio di riconoscimento ottico dei caratteri (OCR) di Vertex AI su Google Distributed Cloud (GDC) air-gapped rileva il testo nei file PDF e TIFF utilizzando i due metodi API seguenti:

BatchAnnotateFiles: Rileva testo con richieste inline.
AsyncBatchAnnotateFiles: Rileva il testo con richieste offline (asincrone).

Questa pagina mostra come rilevare il testo nei file utilizzando l'API OCR su Distributed Cloud.

Prima di iniziare

Prima di poter iniziare a utilizzare l'API OCR, devi disporre di un progetto con l'API OCR abilitata e delle credenziali appropriate. Puoi anche installare librerie client per facilitare le chiamate all'API. Per maggiori informazioni, consulta Configurare un progetto di riconoscimento dei caratteri.

Rilevare il testo con le richieste inline

Il metodo BatchAnnotateFiles rileva il testo da un batch di file PDF o TIFF. Invii 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 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 che ti serve 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 rettangoli di selezione. `DOCUMENT_TEXT_DETECTION` estrae anche il testo da un file, ma il servizio ottimizza la risposta per testi e documenti densi. Il formato 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 del 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`), l'estensione di trasformazione singleton (`t`), il codice dell'estensione di trasformazione del motore del metodo di input (`i0`) e il codice di trasformazione della scrittura a mano (`handwrit`). In sostanza, la lingua è "inglese trasformato dalla scrittura a mano". Non è necessario specificare un codice script 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.

Eseguire una richiesta API inline

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

Gli esempi riportati di seguito 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:

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 per la 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.
Ottenere un token di autenticazione.

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:

Installa l'ultima versione della libreria client OCR.
Imposta le variabili di ambiente richieste in uno script Python.
Autentica la richiesta API.

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)
    print("Got token: ")
    print(creds.token)
  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 e gli endpoint del servizio.
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.

Salva lo script Python.
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.

Rilevare il testo con le 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 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 nel 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 richieste di rilevamento del testo:

Campi del corpo della richiesta	Descrizione del campo
`s3_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 che effettua la richiesta 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 che ti serve 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 rettangoli di selezione. `DOCUMENT_TEXT_DETECTION` estrae anche il testo da un file, ma il servizio ottimizza la risposta per testi e documenti densi. Il formato 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.
`s3_destination.uri`	Il percorso URI di un bucket di archiviazione del tuo progetto Distributed Cloud in cui salvare i file di output. Questa posizione è quella in cui vuoi archiviare i risultati del rilevamento. L'utente o il account di servizio richiedente deve disporre dell'autorizzazione di scrittura per il bucket.

Archivia il file di origine in un bucket di archiviazione

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

I bucket di input e output possono essere diversi e 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.

Per archiviare il file da cui vuoi rilevare il testo in un bucket di archiviazione:

Configura gcloud CLI per l'archiviazione degli oggetti.

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

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 di ruolo utilizzando risorse personalizzate:

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

Crea l'associazione di ruolo 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

Carica il file nel bucket di archiviazione che hai creato. Per ulteriori informazioni, vedi Caricare e scaricare oggetti di archiviazione nei progetti.

Eseguire una richiesta API offline

Gli esempi riportati di seguito 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:

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

cat <<- EOF > request.json
{
  "parent": PROJECT_ID,
  "requests":[
    {
      "input_config": {
        "s3_source": {
          "uri": "SOURCE_FILE"
        },
        "mime_type": "application/pdf"
      },
      "features": [
        {
          "type": "FEATURE_TYPE"
        }
      ],
      "output_config": {
        "s3_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 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.

Ottenere un token di autenticazione.

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:

Installa l'ultima versione della libreria client OCR.
Imposta le variabili di ambiente richieste in uno script Python.
Autentica la richiesta API.

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_func_async(creds):
  vc = vision_client(creds)
  features = [{"type_": vision.Feature.Type.FEATURE_TYPE}]
  input_config = {"s3_source":{"uri":SOURCE_FILE},"mime_type": "application/pdf"}
  output_config = {"s3_destination": {"uri": DESTINATION_BUKET}}
  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)
    print("Got token: ")
    print(creds.token)
  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 e gli endpoint del servizio.
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 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.

Salva lo script Python.
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 controllare lo stato dell'operazione.

Recuperare 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"

Rilevare il testo nei file Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Prima di iniziare

Rilevare il testo con le richieste inline

Eseguire una richiesta API inline

REST

curl

PowerShell

Python

Rilevare il testo con le richieste offline

Archivia il file di origine in un bucket di archiviazione

Eseguire una richiesta API offline

REST

curl

PowerShell

Python

Recuperare lo stato dell'operazione

Elenca operazioni

Rilevare il testo nei file