Condividi tramite

Analisi batch di Intelligence sui documenti

  • Articolo

L'API di analisi batch consente di elaborare in blocco più documenti usando una richiesta asincrona. Invece di dover inviare documenti singolarmente e tenere traccia di più ID richiesta, è possibile analizzare una raccolta di documenti come fatture, una serie di documenti di prestito o un gruppo di documenti personalizzati contemporaneamente. L'API batch supporta la lettura dei documenti dall'archivio BLOB di Azure e la scrittura dei risultati nell'archivio BLOB.

  • Per usare l'analisi batch, è necessario un account di archiviazione BLOB di Azure con contenitori specifici sia per i documenti di origine che per gli output elaborati.
  • Al termine, il risultato dell'operazione batch elenca tutti i singoli documenti elaborati con il relativo stato, ad esempio succeeded, skipped o failed.
  • La versione di anteprima dell'API Batch è disponibile tramite prezzi con pagamento in base al consumo.

Linee guida per l'analisi batch

  • Il numero massimo di documenti elaborati per singola richiesta di analisi batch (inclusi i documenti ignorati) è 10.000.

  • I risultati dell'operazione vengono conservati per 24 ore dopo il completamento. I documenti e i risultati si trovano nell'account di archiviazione specificato, ma lo stato dell'operazione non è più disponibile 24 ore dopo il completamento.

Pronti per iniziare?

Prerequisiti

  • È necessaria una sottoscrizione di Azure attiva. Se non si possiede una sottoscrizione di Azure, è possibile crearne una gratuitamente.

  • Dopo aver creato la sottoscrizione di Azure un'istanza di Informazioni sui documenti nel portale di Azure. Per provare il servizio, è possibile usare il piano tariffario gratuito (F0).

  • Dopo la distribuzione della risorsa, selezionare Vai alla risorsa e recuperare la chiave e l'endpoint.

    • Sono necessari la chiave e l'endpoint dalla risorsa per connettere l'applicazione al servizio Informazioni sui documenti. La chiave e l'endpoint verranno incollati nel codice più avanti nell'avvio rapido. È possibile trovare questi valori nella pagina Chiavi ed endpoint del portale di Azure.

  • Un account di Archiviazione BLOB di Azure. Si creeranno contenitori nell'account di Archiviazione BLOB di Azure per i file di origine e di risultato:

    • Contenitore di origine. Questo contenitore consente di caricare i file per l'analisi (obbligatorio).
    • Contenitore di risultato. Questo contenitore è la posizione in cui vengono archiviati i file elaborati (facoltativo).

È possibile designare lo stesso contenitore di Archiviazione BLOB di Azure per i documenti di origine ed elaborati. Tuttavia, per ridurre al minimo le potenziali probabilità di sovrascrivere accidentalmente i dati, è consigliabile scegliere contenitori separati.

Autorizzazione del contenitore di archiviazione

È possibile scegliere una delle opzioni seguenti per autorizzare l'accesso alla risorsa Documento.

✔️ Identità gestita. Un'identità gestita è un'entità servizio che crea un'identità Microsoft Entra e autorizzazioni specifiche per una risorsa gestita di Azure. Le identità gestite consentono di eseguire l'applicazione Informazioni sui documenti senza dover incorporare le credenziali nel codice. Le identità gestite sono un modo più sicuro per concedere l'accesso ai dati di archiviazione e sostituire il requisito per includere i token di firma di accesso condiviso con gli URL di origine e di risultato.

Per altre informazioni, vedereIdentità gestite per Informazioni sui documenti.

Screenshot del flusso di identità gestita (controllo degli accessi in base al ruolo).

Importante

  • Quando si usano identità gestite, non includere un URL del token di firma di accesso condiviso con le richieste HTTP, altrimenti le richieste avranno esito negativo. L'uso di identità gestite non richiede l'inclusione dei token di firma di accesso condiviso.

✔️ Firma di accesso condiviso (SAS). Una firma di accesso condiviso è un URL che concede l'accesso limitato per un periodo di tempo specificato al servizio Informazioni sui documenti. Per usare questo metodo, è necessario creare token di firma di accesso condiviso per i contenitori di origine e di risultato. I contenitori di origine e risultato devono includere un token di firma di accesso condiviso (SAS), aggiunto come stringa di query. Il token può essere assegnato al contenitore o a BLOB specifici.

Screenshot dell'URI di archiviazione con il token di firma di accesso condiviso aggiunto.

  • Il contenitore o il BLOB di origine deve designare l'accesso in lettura, scrittura, elenco, ed eliminazione.
  • Il contenitore o il BLOB di risultato deve designare l'accesso di scrittura, elenco ed eliminazione.

Per altre informazioni, vedereCreare token di firma di accesso condiviso.

Chiamata dell'API di analisi batch

  • Specificare l'URL del contenitore di Archiviazione BLOB di Azure per il documento di origine impostato all'interno degli oggetti azureBlobSource o azureBlobFileListSource.

Specificare i file di input

L'API batch supporta due opzioni per specificare i file da elaborare. Se sono necessari tutti i file in un contenitore o in una cartella elaborata e il numero di file è inferiore al limite di 10000 per una singola richiesta batch, usare il azureBlobSource contenitore.

Se sono presenti file specifici nel contenitore o nella cartella da elaborare o il numero di file da elaborare supera il limite massimo per un singolo batch, usare .azureBlobFileListSource Suddividere il set di dati in più batch e aggiungere un file con l'elenco di file da elaborare in un formato JSONL nella cartella radice del contenitore. Un esempio del formato dell'elenco di file è.

{"file": "Adatum Corporation.pdf"}
{"file": "Best For You Organics Company.pdf"}

Specificare il percorso dei risultati

Specificare l'URL del contenitore di Archiviazione BLOB di Azure per i risultati dell'analisi batch usando resultContainerUrl. Per evitare la sovrascrittura accidentale, è consigliabile usare contenitori separati per i documenti di origine ed elaborati.

Impostare la overwriteExisting proprietà booleana su false se non si vogliono risultati esistenti con gli stessi nomi di file sovrascritti. Questa impostazione non influisce sulla fatturazione e impedisce solo la sovrascrittura dei risultati dopo l'elaborazione del file di input.

Impostare su resultPrefix spazio dei nomi i risultati di questa esecuzione dell'API batch.

  • Se si prevede di usare lo stesso contenitore sia per l'input che per l'output, impostare resultContainerUrl e resultPrefix in modo che corrisponda all'input azureBlobSource.
  • Quando si usa lo stesso contenitore, è possibile includere il campo overwriteExisting per decidere se sovrascrivere eventuali file con i file dei risultati dell'analisi.

Compilare ed eseguire la richiesta POST

Prima di eseguire la richiesta POST, sostituire {your-source-container-SAS-URL} e {your-result-container-SAS-URL} con i valori delle istanze del contenitore di archiviazione BLOB di Azure.

L'esempio seguente illustra come aggiungere la azureBlobSource proprietà alla richiesta:

Consentire un solo azureBlobSource o azureBlobFileListSource.

POST /documentModels/{modelId}:analyzeBatch

{
  "azureBlobSource": {
    "containerUrl": "https://myStorageAccount.blob.core.windows.net/myContainer?mySasToken",
    "prefix": "trainingDocs/"
  },
  "resultContainerUrl": "https://myStorageAccount.blob.core.windows.net/myOutputContainer?mySasToken",
  "resultPrefix": "layoutresult/",
  "overwriteExisting": true
}

L'esempio seguente illustra come aggiungere la azureBlobFileListSource proprietà alla richiesta:

POST /documentModels/{modelId}:analyzeBatch

{
   "azureBlobFileListSource": {
      "containerUrl": "https://myStorageAccount.blob.core.windows.net/myContainer?mySasToken",
      "fileList": "myFileList.jsonl"
    },
  "resultContainerUrl": "https://myStorageAccount.blob.core.windows.net/myOutputContainer?mySasToken",
  "resultPrefix": "customresult/",
  "overwriteExisting": true
}

Risposta con esito positivo

202 Accepted
Operation-Location: /documentModels/{modelId}/analyzeBatchResults/{resultId}

Recuperare i risultati dell'API di analisi batch

Dopo l'esecuzione dell'operazione API Batch, è possibile recuperare i risultati dell'analisi batch usando l'operazione GET. Questa operazione recupera le informazioni sullo stato dell'operazione, la percentuale di completamento dell'operazione e la data/ora di creazione e aggiornamento.

GET /documentModels/{modelId}/analyzeBatchResults/{resultId}
200 OK

{
  "status": "running",      // notStarted, running, completed, failed
  "percentCompleted": 67,   // Estimated based on the number of processed documents
  "createdDateTime": "2021-09-24T13:00:46Z",
  "lastUpdatedDateTime": "2021-09-24T13:00:49Z"
...
}

Interpretazione dei messaggi di stato

A ogni documento viene assegnato uno stato, succeeded, failed o skipped. Per ogni documento sono disponibili due URL per convalidare i risultati: sourceUrl, ovvero il contenitore di archiviazione BLOB di origine per il documento di input completato e resultUrl, costruito combinando resultContainerUrl e resultPrefix per creare il percorso relativo per il file di origine e .ocr.json.

  • Stato notStarted o running. L'operazione di analisi batch non viene avviata o non viene completata. Attendere il completamento dell'operazione per tutti i documenti.

  • Stato completed. L'operazione di analisi batch è stata completata.

  • Stato failed. Operazione batch non riuscita. Questa risposta si verifica in genere se si riscontrano problemi generali con la richiesta. Gli errori nei singoli file vengono restituiti nella risposta al report batch, anche se tutti i file hanno avuto esito negativo. Ad esempio, gli errori di archiviazione non interrompono l'operazione batch nel suo complesso, in modo da poter accedere ai risultati parziali tramite la risposta del report batch.

Solo i file con stato succeeded hanno la proprietà resultUrl generata nella risposta. In questo modo il training del modello consente di rilevare i nomi di file che terminano con .ocr.json e di identificarli come gli unici file che possono essere usati per il training.

Esempio di risposta di stato succeeded:

[
  "result": {
    "succeededCount": 0,
    "failedCount": 2,
    "skippedCount": 2,
    "details": [
      {
        "sourceUrl": "https://{your-source-container}/myContainer/trainingDocs/file2.jpg",
        "status": "failed",
        "error": {
          "code": "InvalidArgument",
          "message": "Invalid argument.",
          "innererror": {
            "code": "InvalidSasToken",
            "message": "The shared access signature (SAS) is invalid: {details}"
                   }
               }
          }
      ]
   }
]
...

Esempio di risposta di stato failed:

  • Questo errore viene restituito solo se sono presenti errori nella richiesta batch complessiva.
  • Dopo l'avvio dell'operazione di analisi batch, lo stato delle singole operazioni di documento non influisce sullo stato del processo batch complessivo, anche se tutti i file hanno lo stato failed.
[
    "result": {
    "succeededCount": 0,
    "failedCount": 2,
    "skippedCount": 2,
    "details": [
        "sourceUrl": "https://{your-source-container}/myContainer/trainingDocs/file2.jpg",
        "status": "failed",
        "error": {
            "code": "InvalidArgument",
            "message": "Invalid argument.",
            "innererror": {
              "code": "InvalidSasToken",
              "message": "The shared access signature (SAS) is invalid: {details}"
                }
            }
        ]
    }
]
...

Esempio di risposta di stato skipped:

[
    "result": {
    "succeededCount": 3,
    "failedCount": 0,
    "skippedCount": 2,
    "details": [
        ...
        "sourceUrl": "https://myStorageAccount.blob.core.windows.net/myContainer/trainingDocs/file4.jpg",
        "status": "skipped",
        "error": {
            "code": "OutputExists",
            "message": "Analysis skipped because result file {path} already exists."
             }
        ]
    }
]
...

I risultati dell'analisi batch consentono di identificare quali file vengono analizzati correttamente e di convalidare i risultati dell'analisi confrontando il file in resultUrl con il file di output in resultContainerUrl.

Nota

I risultati dell'analisi non vengono restituiti per singoli file fino al completamento dell'analisi batch dell'intero set di documenti. Per tenere traccia dello stato di avanzamento dettagliato oltre percentCompleted, è possibile monitorare i file *.ocr.json mentre vengono scritti in resultContainerUrl.

Passaggi successivi

Visualizzare esempi di codice in GitHub.