Condividi tramite

Analisi batch di Informazioni sui documenti (anteprima)

  • Articolo

Importante

  • Le versioni di anteprima pubblica di Informazioni sui documenti consentono l'accesso anticipato alle funzionalità in fase di sviluppo attivo. Le funzionalità, gli approcci e i processi possono cambiare prima della disponibilità generale, a seconda del feedback degli utenti.
  • Per impostazione predefinita, la versione di anteprima pubblica delle librerie client di Intelligence dei documenti è la versione dell'API REST 2024-07-31-preview.
  • La versione di anteprima pubblica 2024-07-31-preview è al momento disponibile solo nelle aree di Azure seguenti. Si noti che il modello di generazione personalizzata (estrazione di campi di documento) in Studio AI è disponibile solo nell'area Stati Uniti centro-settentrionali:
    • Stati Uniti orientali
    • Stati Uniti occidentali 2
    • Europa occidentale
    • Stati Uniti centro-settentrionali

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 contemporaneamente una raccolta di fatture, una serie di documenti di prestito o un gruppo di documenti di training del modello personalizzati.

  • 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.

I modelli seguenti supportano l'analisi batch:

  • Lettura. Estrarre righe di testo, parole, lingue rilevate e stile scritto a mano da moduli e documenti.

  • Layout. Estrarre testo, tabelle, segni di selezione e informazioni sulla struttura da moduli e documenti.

  • Modello personalizzato. Eseguire il training di modelli per estrarre coppie chiave-valore, segni di selezione, tabelle, campi della firma e aree da moduli strutturati.

  • Neurale personalizzato. Eseguire il training dei modelli per estrarre i campi dati specificati da documenti strutturati, semistrutturati e non strutturati.

  • Modello generativo personalizzato. Eseguire il training di modelli per estrarre dati specificati da oggetti complessi, ad esempio tabelle nidificate, campi astrattivi/generativi e formati realmente non strutturati.

Linee guida per l'analisi batch

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

  • Il parametro azureBlobFileListSource può essere usato per suddividere le richieste di dimensioni maggiori in richieste più piccole.

  • 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, vedere Identità 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 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.

    • Se si usa lo stesso contenitore, impostare resultContainerUrl e resultPrefix in modo che corrispondano 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.

Consentire un solo azureBlobSource o azureBlobFileListSource.

POST /documentModels/{modelId}:analyzeBatch

[
  {
    "azureBlobSource": {
      "containerUrl": "{your-source-container-SAS-URL}",
      "prefix": "trainingDocs/"
    },
    "azureBlobFileListSource": {
      "containerUrl": "{your-source-container-SAS-URL}",
      "fileList": "myFileList.jsonl"
    },
    "resultContainerUrl": "{your-result-container-SAS-URL}",
    "resultPrefix": "trainingDocsResult/",
    "overwriteExisting": false
  }
]

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.