Migrazione di Document Intelligence v3.1

Migrazione dalla versione dell'API v3.1

Le API di anteprima vengono deprecate periodicamente. Se si usa una versione dell'API di anteprima, aggiornare l'applicazione in modo che corrisponda alla versione dell'API di disponibilità generale. Per eseguire la migrazione da una versione dell'API di anteprima alla 2023-11-30 (GA) versione dell'API usando l'SDK, eseguire l'aggiornamento alla versione corrente dell'SDK specifico del linguaggio.

Funzionalità di analisi

✓ - O abilitato - Formule facoltative/StyleFont/OCR Alta risoluzione* - Le funzionalità Premium comportano costi aggiuntivi

Migrazione dalla versione 3.0

Rispetto alla versione 3.0, Document Intelligence v3.1 introduce diverse nuove funzionalità:

• Estrazione di codice a barre.
• Funzionalità dei componenti aggiuntivi, tra cui estrazione di proprietà relativamente a tipo di carattere, risoluzione elevata, formula.
• Modello di classificazione personalizzato per la suddivisione e la classificazione dei documenti.
• Supporto nuovi campi ed espansione della lingua nel modello Fattura e Ricevuta.
• Nuovo supporto relativo al tipo di documento nel modello ID documento.
• Nuovo modello di carta di assicurazione sanitaria predefinito.
• I file Office/HTML sono supportati nel modello prebuilt-read, con l’estrazione di parole e paragrafi senza rettangoli delimitatori. Le immagini incorporate non sono più supportate. Se sono richieste funzionalità del componente aggiuntivo per i file Office/HTML, viene restituita una matrice vuota senza errori.
• Scadenza del modello per modelli di estrazione e classificazione personalizzati: i nostri nuovi modelli personalizzati si basano su un modello di base di grandi dimensioni che viene aggiornato periodicamente per migliorare la qualità. Una data di scadenza viene introdotta in tutti i modelli personalizzati per consentire il ritiro dei modelli di base corrispondenti. Una volta scaduto un modello personalizzato, è necessario ripetere il training del modello usando la versione più recente dell'API (modello di base).

GET /documentModels/{customModelId}?api-version={apiVersion}
{
  "modelId": "{customModelId}",
  "description": "{customModelDescription}",
  "createdDateTime": "2023-09-24T12:54:35Z",
  "expirationDateTime": "2025-01-01T00:00:00Z",
  "apiVersion": "2023-07-31",
  "docTypes": { ... }
}

• Quota di compilazione del modello neurale personalizzato: il numero di modelli neurali che ogni sottoscrizione può compilare per area ogni mese è limitato. Il codice JSON del risultato viene espanso per includere la quota e le informazioni usate per comprendere l'utilizzo corrente come parte delle informazioni sulle risorse restituite da GET/info.

{
  "customDocumentModels": { ... },
  "customNeuralDocumentModelBuilds": {
    "used": 1,
    "quota": 10,
    "quotaResetDateTime": "2023-03-01T00:00:00Z"
  }
}

• Un parametro di query facoltativo features per analizzare le operazioni può facoltativamente abilitare funzionalità specifiche. Alcune funzionalità Premium possono comportare la fatturazione aggiunta. Per informazioni dettagliate, vedere Analizzare l'elenco delle funzionalità.
• Estendere gli oggetti campo valuta estratti per restituire un campo di codice valuta normalizzato, quando possibile. Attualmente, i campi correnti possono restituire l'importo, ad esempio 123,45) e il simbolo della valuta (ad esempio $). Questa funzionalità esegue il mapping del simbolo di valuta a un codice ISO 4217 canonico (ad esempio USD). Il modello può facoltativamente utilizzare il contenuto globale del documento per evitare ambiguità o dedurre il codice di valuta.

{
  "fields": {
    "Total": {
      "type": "currency",
      "content": "$123.45",
      "valueCurrency": {
        "amount": 123.45,
        "currencySymbol": "$",
        "currencyCode": "USD"
      },
      ...
    }
  }
}

Oltre al miglioramento della qualità del modello, è consigliabile aggiornare l'applicazione per usare la versione 3.1 per trarre vantaggio da queste nuove funzionalità.

Migrazione dalla versione 2.1 o v2.0

Document Intelligence v3.1 è la versione disponibile a livello generale più recente con le funzionalità più ricche, la copertura relativa alla maggior parte delle lingue e dei tipi di documento e una migliore qualità del modello. Vedere la panoramica del modello per le funzionalità disponibili nella versione 3.1.

A partire dalla versione 3.0, l'API REST di Document Intelligence è stata riprogettata per migliorare l'usabilità. In questa sezione vengono illustrate le differenze tra Document Intelligence v2.0, v2.1 e v3.1 e come passare alla versione più recente dell'API.

Modifiche apportate agli endpoint dell'API REST

L'API REST v3.1 combina le operazioni di analisi per l'analisi del layout, i modelli predefiniti e i modelli personalizzati in una singola coppia di operazioni assegnando documentModels e modelId ai modelli predefiniti e di analisi del layout.

Richiesta POST

https://{your-form-recognizer-endpoint}/formrecognizer/documentModels/{modelId}?api-version=2023-07-31

Richiesta GET

https://{your-form-recognizer-endpoint}/formrecognizer/documentModels/{modelId}/AnalyzeResult/{resultId}?api-version=2023-07-31

Operazione di analisi

• Il payload della richiesta e lo schema della chiamata rimangono invariati.
• L'operazione di analisi consente di specificare il documento di input e le configurazioni specifiche del contenuto. Restituisce l'URL del risultato di analisi tramite l'intestazione Operation-Location nella risposta.
• Eseguire il polling di questo URL del risultato di analisi tramite una richiesta GET per controllare lo stato dell'operazione di analisi (l'intervallo minimo consigliato tra le richieste è pari a un secondo).
• Se l'operazione viene completata correttamente, lo stato viene impostato su succeeded e nel corpo della risposta viene restituito analyzeResult. Se vengono rilevati errori, lo stato viene impostato su failede viene restituito un errore.

Analizzare il corpo della richiesta

Il contenuto da analizzare viene fornito tramite il corpo della richiesta. Per costruire la richiesta, è possibile usare l'URL o dati con codifica Base64.

Per specificare un URL Web accessibile pubblicamente, impostare Content-Type su application/json e inviare il corpo seguente in formato JSON:

{
  "urlSource": "{urlPath}"
}

La codifica Base 64 è supportata anche in Document Intelligence v3.0:

{
  "base64Source": "{base64EncodedContent}"
}

Parametri ancora supportati

Parametri che continuano a essere supportati:

• pages : analizza solo un subset specifico di pagine del documento. Elenco di numeri di pagina da analizzare indicizzati a partire dal numero 1. Ex. "1-3,5,7-9"
• locale : hint delle impostazioni locali per il riconoscimento del testo e l'analisi dei documenti. Il valore può contenere solo il codice linguistico (ad esempio en, fr) o il tag di lingua BCP 47 (ad esempio "en-US").

Parametri non più supportati:

• includeTextDetails

Il nuovo formato di risposta è più compatto e viene sempre restituito l'output completo.

Modifiche apportate al risultato di analisi

Per supportare gli elementi a più pagine, è stato eseguito il refactoring della risposta di analisi ai risultati di primo livello seguenti.

• pages
• tables
• keyValuePairs
• entities
• styles
• documents

{
// Basic analyze result metadata
"apiVersion": "2022-08-31", // REST API version used
"modelId": "prebuilt-invoice", // ModelId used
"stringIndexType": "textElements", // Character unit used for string offsets and lengths:
// textElements, unicodeCodePoint, utf16CodeUnit // Concatenated content in global reading order across pages.
// Words are generally delimited by space, except CJK (Chinese, Japanese, Korean) characters.
// Lines and selection marks are generally delimited by newline character.
// Selection marks are represented in Markdown emoji syntax (:selected:, :unselected:).
"content": "CONTOSO LTD.\nINVOICE\nContoso Headquarters...", "pages": [ // List of pages analyzed
{
// Basic page metadata
"pageNumber": 1, // 1-indexed page number
"angle": 0, // Orientation of content in clockwise direction (degree)
"width": 0, // Page width
"height": 0, // Page height
"unit": "pixel", // Unit for width, height, and polygon coordinates
"spans": [ // Parts of top-level content covered by page
{
"offset": 0, // Offset in content
"length": 7 // Length in content
}
], // List of words in page
"words": [
{
"text": "CONTOSO", // Equivalent to $.content.Substring(span.offset, span.length)
"boundingBox": [ ... ], // Position in page
"confidence": 0.99, // Extraction confidence
"span": { ... } // Part of top-level content covered by word
}, ...
], // List of selectionMarks in page
"selectionMarks": [
{
"state": "selected", // Selection state: selected, unselected
"boundingBox": [ ... ], // Position in page
"confidence": 0.95, // Extraction confidence
"span": { ... } // Part of top-level content covered by selection mark
}, ...
], // List of lines in page
"lines": [
{
"content": "CONTOSO LTD.", // Concatenated content of line (may contain both words and selectionMarks)
"boundingBox": [ ... ], // Position in page
"spans": [ ... ], // Parts of top-level content covered by line
}, ...
]
}, ...
], // List of extracted tables
"tables": [
{
"rowCount": 1, // Number of rows in table
"columnCount": 1, // Number of columns in table
"boundingRegions": [ // Polygons or Bounding boxes potentially across pages covered by table
{
"pageNumber": 1, // 1-indexed page number
"polygon": [ ... ], // Previously Bounding box, renamed to polygon in the 2022-08-31 API
}
],
"spans": [ ... ], // Parts of top-level content covered by table // List of cells in table
"cells": [
{
"kind": "stub", // Cell kind: content (default), rowHeader, columnHeader, stub, description
"rowIndex": 0, // 0-indexed row position of cell
"columnIndex": 0, // 0-indexed column position of cell
"rowSpan": 1, // Number of rows spanned by cell (default=1)
"columnSpan": 1, // Number of columns spanned by cell (default=1)
"content": "SALESPERSON", // Concatenated content of cell
"boundingRegions": [ ... ], // Bounding regions covered by cell
"spans": [ ... ] // Parts of top-level content covered by cell
}, ...
]
}, ...
], // List of extracted key-value pairs
"keyValuePairs": [
{
"key": { // Extracted key
"content": "INVOICE:", // Key content
"boundingRegions": [ ... ], // Key bounding regions
"spans": [ ... ] // Key spans
},
"value": { // Extracted value corresponding to key, if any
"content": "INV-100", // Value content
"boundingRegions": [ ... ], // Value bounding regions
"spans": [ ... ] // Value spans
},
"confidence": 0.95 // Extraction confidence
}, ...
],
"styles": [
{
"isHandwritten": true, // Is content in this style handwritten?
"spans": [ ... ], // Spans covered by this style
"confidence": 0.95 // Detection confidence
}, ...
], // List of extracted documents
"documents": [
{
"docType": "prebuilt-invoice", // Classified document type (model dependent)
"boundingRegions": [ ... ], // Document bounding regions
"spans": [ ... ], // Document spans
"confidence": 0.99, // Document splitting/classification confidence // List of extracted fields
"fields": {
"VendorName": { // Field name (docType dependent)
"type": "string", // Field value type: string, number, array, object, ...
"valueString": "CONTOSO LTD.",// Normalized field value
"content": "CONTOSO LTD.", // Raw extracted field content
"boundingRegions": [ ... ], // Field bounding regions
"spans": [ ... ], // Field spans
"confidence": 0.99 // Extraction confidence
}, ...
}
}, ...
]
}

Creare il modello o eseguirne il training

L'oggetto modello include tre aggiornamenti nella nuova API:

• modelId è ora una proprietà che può essere impostata su un modello per un nome leggibile.
• modelName viene rinominata description
• buildMode è una nuova proprietà con valori template per modelli di modulo personalizzati o neural per i modelli neurali personalizzati.

Per eseguire il training di un modello, viene richiamata l'operazione build. Il payload della richiesta e lo schema della chiamata rimangono invariati. L'operazione di creazione consente di specificare il modello e il set di dati di training. Restituisce il risultato tramite l'intestazione Operation-Location nella risposta. Eseguire il polling di questo URL dell'operazione sul modello tramite una richiesta GET per controllare lo stato dell'operazione di creazione (l'intervallo minimo consigliato tra le richieste è pari a un secondo). A differenza della versione 2.1, questo URL non corrisponde alla posizione della risorsa del modello. L'URL del modello può invece essere costruito dal valore specificato di modelId, recuperato anche dalla proprietà resourceLocation nella risposta. Se l'operazione viene completata correttamente, lo stato viene impostato su succeeded e il risultato contiene le informazioni sul modello personalizzato. Se vengono rilevati errori, lo stato viene impostato su failed e viene restituito un errore.

Il codice seguente si riferisce a una richiesta di creazione di esempio in cui viene usato un token di firma di accesso condiviso. Si noti la barra finale quando si imposta il prefisso o il percorso della cartella.

POST https://{your-form-recognizer-endpoint}/formrecognizer/documentModels:build?api-version=2022-08-31

{
  "modelId": {modelId},
  "description": "Sample model",
  "buildMode": "template",
  "azureBlobSource": {
    "containerUrl": "https://{storageAccount}.blob.core.windows.net/{containerName}?{sasToken}",
    "prefix": "{folderName/}"
  }
}

Modifiche apportate alla funzione di composizione del modello

La funzione di composizione del modello è ora limitata a un singolo livello di annidamento. I modelli composti sono ora coerenti con i modelli personalizzati ma includono le proprietà modelId e description.

POST https://{your-form-recognizer-endpoint}/formrecognizer/documentModels:compose?api-version=2022-08-31
{
  "modelId": "{composedModelId}",
  "description": "{composedModelDescription}",
  "componentModels": [
    { "modelId": "{modelId1}" },
    { "modelId": "{modelId2}" },
  ]
}

Modifiche apportate alla funzione di copia del modello

Lo schema di chiamata per la funzione di copia del modello rimane invariato:

• Autorizzare l'operazione di copia con la risorsa di destinazione che chiama authorizeCopy. Creare ora una richiesta POST.
• Inviare l'autorizzazione alla risorsa di origine per copiare il modello che chiama copyTo.
• Eseguire il polling dell'operazione restituita per convalidare il corretto completamento dell'operazione.

Le uniche modifiche apportate alla funzione di copia del modello sono:

• L'azione HTTP su authorizeCopy è ora una richiesta POST.
• Il payload di autorizzazione contiene tutte le informazioni necessarie per inviare la richiesta di copia.

Autorizzare la copia

POST https://{targetHost}/formrecognizer/documentModels:authorizeCopy?api-version=2022-08-31
{
  "modelId": "{targetModelId}",
  "description": "{targetModelDescription}",
}

Usare il corpo della risposta dell'azione di autorizzazione per costruire la richiesta per la copia.

POST https://{sourceHost}/formrecognizer/documentModels/{sourceModelId}:copyTo?api-version=2022-08-31
{
  "targetResourceId": "{targetResourceId}",
  "targetResourceRegion": "{targetResourceRegion}",
  "targetModelId": "{targetModelId}",
  "targetModelLocation": "https://{targetHost}/formrecognizer/documentModels/{targetModelId}",
  "accessToken": "{accessToken}",
  "expirationDateTime": "2021-08-02T03:56:11Z"
}

Modifiche apportate alla funzione di elenco dei modelli

I modelli di elenco vengono estesi per restituire modelli predefiniti e personalizzati. Tutti i nomi dei modelli predefiniti iniziano con prebuilt-. Vengono restituiti solo i modelli con stato succeeded. Per elencare i modelli con stato failed o in progress, vedere le operazioni di elenco.

Richiesta di elenco dei modelli di esempio

GET https://{your-form-recognizer-endpoint}/formrecognizer/documentModels?api-version=2022-08-31

Modifica apportata alla funzione di recupero del modello

Poiché la funzione di recupero del modello include ora modelli predefiniti, l'operazione get restituisce un dizionario docTypes. Ogni descrizione del tipo di documento include nome, descrizione facoltativa, schema dei campi e attendibilità dei campi facoltativi. Lo schema dei campi descrive l'elenco dei campi potenzialmente restituiti con il tipo di documento.

GET https://{your-form-recognizer-endpoint}/formrecognizer/documentModels/{modelId}?api-version=2022-08-31

Nuova operazione di recupero delle informazioni

L'operazione info sul servizio restituisce il numero di modelli personalizzati e il limite di modelli personalizzati.

GET https://{your-form-recognizer-endpoint}/formrecognizer/info? api-version=2022-08-31

Risposta di esempio

{
  "customDocumentModels": {
    "count": 5,
    "limit": 100
  }
}

Passaggi successivi

• Esaminare la nuova API REST
• Che cos'è Document Intelligence?
• Avvio rapido di Document Intelligence