Migrazione di Document Intelligence v3.1

  • Articolo

Questo contenuto si applica a:checkmarkv4.0 (anteprima)checkmarkv3.1 (GA)checkmarkv3.0 (GA)checkmarkv2.1 (GA)

Importante

L'API REST di Document Intelligence v3.1 introduce modifiche di rilievo nella richiesta dell'API REST e analizza il codice JSON della risposta.

Migrazione dalla versione dell'API di anteprima v3.1

Le API di anteprima sono periodicamente deprecate. Se si usa una versione dell'API di anteprima, aggiornare l'applicazione in modo che corrisponda alla versione dell'API ga. Per eseguire la migrazione dalla versione dell'API 2023-02-28-preview alla 2023-07-31 versione dell'API (GA) usando l'SDK, eseguire l'aggiornamento alla versione corrente dell'SDK specifico del linguaggio.

L'API 2023-07-31 (GA) include alcuni aggiornamenti e modifiche dalla versione dell'API di anteprima:

  • Le funzionalità abilitate per impostazione predefinita sono limitate a quelle essenziali per il modello specifico con il vantaggio di ridurre la latenza e le dimensioni della risposta. Le funzionalità aggiunte possono essere abilitate tramite valori di enumerazione nel features parametro .
  • Alcune funzionalità di layout da precompilt-read-read e keyValuePairs oltre a quella predefinita-{documento,invoice} non sono più supportate.
  • Disabilitazione dei codici a barre per impostazione predefinita per precompilt-read e precompilt-layout, lingue per precompilt-read e keyValuePairs per la fattura predefinita.
  • L'estrazione delle annotazioni viene rimossa.
  • I campi di query e i nomi comuni delle coppie chiave-valore vengono rimossi.
  • I file Office/HTML sono supportati nel modello predefinito di lettura, estraendo 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.

Funzionalità di analisi

Model ID Estrazione testo Paragrafi Ruoli paragrafo Segni di selezione Tabelle Coppie chiave-valore Linguaggi Codici Analisi dei documenti Formule* StyleFont* OCR High Resolution*
precompilt-read ✓ ✓ O O O O O
precompilt-layout ✓ ✓ ✓ ✓ ✓ O O O O O
precompilt-document ✓ ✓ ✓ ✓ ✓ ✓ O O O O O
precompilt-businessCard ✓ ✓
prebuilt-idDocument ✓ O O ✓ O O O
fattura predefinita ✓ ✓ ✓ O O O ✓ O O O
ricevuta predefinita ✓ O O ✓ O O O
prebuilt-healthInsuranceCard.us ✓ O O ✓ O O O
prebuilt-tax.us.w2 ✓ ✓ O O ✓ O O O
prebuilt-tax.us.1098 ✓ ✓ O O ✓ O O O
prebuilt-tax.us.1098E ✓ ✓ O O ✓ O O O
prebuilt-tax.us.1098T ✓ ✓ O O ✓ O O O
precompilt-contract ✓ ✓ ✓ ✓ O O ✓ O O O
{ customModelName } ✓ ✓ ✓ ✓ ✓ O O ✓ O O O

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

Migrazione dalla versione 3.0

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

  • Estrazione di codice a barre .
  • Funzionalità dei componenti aggiuntivi , tra cui estrazione di proprietà con risoluzione elevata, formula e tipo di carattere.
  • Modello di classificazione personalizzato per la suddivisione e la classificazione dei documenti.
  • L'espansione della lingua e i nuovi campi supportano il modello Fattura e Ricevuta.
  • Nuovo supporto del tipo di documento nel modello di documento ID.
  • Nuovo modello di carta di assicurazione sanitaria predefinita.
  • I file Office/HTML sono supportati nel modello predefinito di lettura, estraendo 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 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 currencySymbol (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 maggior parte delle lingue e la copertura dei tipi di documento e una migliore qualità del modello. Vedere panoramica del modello per le funzionalità e 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.

Attenzione

  • La versione dell'API REST 2023-07-31 include una modifica di rilievo nel codice JSON di analisi della risposta dell'API REST.
  • La boundingBox proprietà viene rinominata polygon in in ogni istanza.

Modifiche 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 all'analisi del layout (layout predefinito) e modelli predefiniti.

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 il modello di chiamata rimangono invariati.
  • L'operazione Analizza specifica 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 dei risultati di analisi tramite una richiesta GET per controllare lo stato dell'operazione di analisi (intervallo minimo consigliato tra le richieste è 1 secondo).
  • Al termine dell'operazione, lo stato viene impostato su succeeded e analyzeResult viene restituito nel corpo della risposta. Se vengono rilevati errori, lo stato viene impostato su failede viene restituito un errore.
Modello v2.0 v2.1 v3.1
Prefisso URL richiesta https://{your-form-recognizer-endpoint}/formrecognizer/v2.0 https://{your-form-recognizer-endpoint}/formrecognizer/v2.1 https://{your-form-recognizer-endpoint}/formrecognizer
Documento generale N/A N/A /documentModels/prebuilt-document:analyze
Layout /layout/analyze /layout/analyze /documentModels/prebuilt-layout:analyze
Personalizzazione /custom/models/{modelId}/analyze /custom/{modelId}/analyze /documentModels/{modelId}:analyze
Fattura N/D /precompilt/invoice/analyze /documentModels/prebuilt-invoice:analyze
Ricevuta /precompilt/receipt/analyze /precompilt/receipt/analyze /documentModels/prebuilt-receipt:analyze
Documento di identità N/D /prebuilt/idDocument/analyze /documentModels/prebuilt-idDocument:analyze
Tessera business N/D /precompilt/businessCard/analyze /documentModels/prebuilt-businessCard:analyze
W-2 N/A N/A /documentModels/prebuilt-tax.us.w2:analyze
Scheda assicurazione sanitaria N/A N/A /documentModels/prebuilt-healthInsuranceCard.us:analyze
Contratto N/A N/A /documentModels/prebuilt-contract:analyze

Analizzare il corpo della richiesta

Il contenuto da analizzare viene fornito tramite il corpo della richiesta. L'URL o i dati con codifica Base64 possono essere utente per costruire la richiesta.

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

{
  "urlSource": "{urlPath}"
}

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

{
  "base64Source": "{base64EncodedContent}"
}

Parametri supportati anche

Parametri che continuano a essere supportati:

  • pages : analizza solo un subset specifico di pagine nel documento. Elenco di numeri di pagina indicizzati dal numero 1 da analizzare. 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").

I parametri non sono più supportati:

  • includeTextDetails

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

Modifiche per analizzare i risultati

Analizza la risposta viene eseguito il refactoring nei risultati di primo livello seguenti per supportare gli elementi a più pagine.

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

Nota

Le modifiche alla risposta analyzeResult includono una serie di modifiche, ad esempio lo spostamento da una proprietà di pagine a una proprietà di leva superiore all'interno di analyzeResult.


{
// 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
}, ...
}
}, ...
]
}

Compilare o eseguire il training di un modello

L'oggetto modello ha tre aggiornamenti nella nuova API

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

L'operazione build viene richiamata per eseguire il training di un modello. Il payload della richiesta e il modello di chiamata rimangono invariati. L'operazione di compilazione specifica il modello e il set di dati di training, che restituisce il risultato tramite l'intestazione Operation-Location nella risposta. Eseguire il polling dell'URL dell'operazione del modello tramite una richiesta GET per controllare lo stato dell'operazione di compilazione (intervallo minimo consigliato tra le richieste è 1 secondo). A differenza della versione 2.1, questo URL non è la posizione della risorsa del modello. L'URL del modello può invece essere costruito dal modelId specificato, recuperato anche dalla proprietà resourceLocation nella risposta. In caso di esito positivo, lo stato è impostato su succeeded e il risultato contiene le informazioni sul modello personalizzato. Se vengono rilevati errori, lo stato viene impostato su failede viene restituito l'errore.

Il codice seguente è una richiesta di compilazione di esempio usando 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 al modello di composizione

La composizione del modello è ora limitata a un singolo livello di annidamento. I modelli composti sono ora coerenti con i modelli personalizzati con l'aggiunta di modelId proprietà 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 copia del modello

Il modello di chiamata per il modello di copia rimane invariato:

  • Autorizzare l'operazione di copia con la risorsa di destinazione che chiama authorizeCopy. Ora una richiesta POST.
  • Inviare l'autorizzazione alla risorsa di origine per copiare la chiamata al modello copyTo
  • Eseguire il polling dell'operazione restituita per convalidare correttamente l'operazione completata

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

  • L'azione HTTP in 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 ai modelli di elenco

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 completato. Per elencare i modelli non riusciti o in corso, vedere Elencare le operazioni.

Richiesta di modelli di elenco di esempio

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

Modifica per ottenere il modello

Poiché get model include ora modelli predefiniti, l'operazione get restituisce un docTypes dizionario. Ogni descrizione del tipo di documento include nome, descrizione facoltativa, schema dei campi e attendibilità dei campi facoltativi. Lo schema del campo 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 get info

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

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

Risposta di esempio

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

Passaggi successivi