migrazione Riconoscimento modulo v3.0

  • Articolo
  • 9 minuti per la lettura

Importante

Riconoscimento modulo'API REST v3.0 introduce modifiche di rilievo nella richiesta dell'API REST e analizza JSON della risposta.

Migrazione da una versione dell'API di anteprima v3.0

Le API di anteprima vengono periodicamente deprecate. Se si usa una versione dell'API di anteprima, pianificare l'aggiornamento dell'applicazione alla versione dell'API GA una volta disponibile. Per eseguire la migrazione dalle versioni 2022-08-31 dell'API 2021-09-30 o dell'API 2022-01-30-preview alla versione dell'API (GA) usando l'SDK, aggiornare alla versione corrente dell'SDK specifico del linguaggio.

L'API ha alcuni aggiornamenti dalle versioni dell'API 2022-08-31 di anteprima:

  • Rinomina campo: boundingBox al poligono per supportare aree poligono non quadrilateri.
  • Campo eliminato: le entità rimosse dal risultato del modello di documento generale.
  • Ridenominazione campo: documentLanguage.languageCode in impostazioni locali
  • Aggiunta del supporto per il formato HEIF
  • Aggiunta del rilevamento dei paragrafi, con la classificazione dei ruoli per i modelli di layout e documenti generali
  • Aggiunta del supporto per i campi degli indirizzi analizzati.

Migrazione da v2.1

Riconoscimento modulo v3.0 introduce diverse nuove funzionalità e funzionalità:

In questo articolo verranno illustrate le differenze tra Riconoscimento modulo v2.1 e v3.0 e come passare alla versione più recente dell'API.

Attenzione

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

Modifiche agli endpoint dell'API REST

L'API REST v3.0 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=2022-08-31

Richiesta GET

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

Analizzare l'operazione

  • Il payload della richiesta e il modello di chiamata rimangono invariati.
  • L'operazione Analizza specifica i documenti di input e le configurazioni specifiche del contenuto, restituisce l'URL dei risultati 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 (intervallo minimo consigliato tra le richieste è 1 secondo).
  • Al termine dell'operazione, lo stato è impostato su riuscito e analizzaResult viene restituito nel corpo della risposta. Se vengono rilevati errori, lo stato verrà impostato su failede verrà restituito un errore.
Modellare v2.1 v3.0
Prefisso URL richiesta https://{your-form-recognizer-endpoint}/formrecognizer/v2.1 https://{your-form-recognizer-endpoint}/formrecognizer
Documento generale N/D /documentModels/prebuilt-document:analyze
Layout /layout/analizza /documentModels/prebuilt-layout:analyze
Impostazione personalizzata /custom/{modelId}/analysis /documentModels/{modelId}:analyze
Fattura /predefinita/fattura/analisi /documentModels/prebuilt-invoice:analyze
Ricevuta /predefinita/ricevuta/analisi /documentModels/prebuilt-receipt:analyze
Documento di identità /prebuilt/idDocument/analyze /documentModels/prebuilt-idDocument:analyze
Tessera business /precompilt/businessCard/analyze /documentModels/prebuilt-businessCard:analyze
W-2 /prebuilt/w-2/analysis /documentModels/prebuilt-w-2: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 Base64 è supportata anche in Riconoscimento modulo v3.0:

{
  "base64Source": "{base64EncodedContent}"
}

Parametri inoltre supportati

Parametri che continuano a essere supportati:

  • pages : analizzare 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 della lingua (ad esempio "en", "fr") o BCP 47 language tag (ad esempio "en-US").

Parametri non più supportati:

  • includeTextDetails

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

Modifiche per analizzare i risultati

La risposta di analisi è stata refactorata nei risultati di primo livello seguenti per supportare elementi a più pagine.

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

Nota

Le modifiche alla risposta analysisResult includono una serie di modifiche come lo spostamento da una proprietà di pagine a una proprietà top lever all'interno di analysisResult.


{
// 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
}, ...
], // List of extracted entities
"entities": [
{
"category": "DateTime", // Primary entity category
"subCategory": "Date", // Secondary entity category
"content": "11/15/2019", // Entity content
"boundingRegions": [ ... ], // Entity bounding regions
"spans": [ ... ], // Entity spans
"confidence": 0.99 // Extraction confidence
}, ...
], // List of extracted styles
"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 del 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 è stata rinominato in description
  • buildMode è una nuova proprietà con valori di template per modelli di modulo personalizzati o neural per 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, 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 è il percorso della risorsa del modello. L'URL del modello può invece essere costruito dal modelId specificato, recuperato anche dalla proprietà resourceLocation nella risposta. Al termine dell'operazione, lo stato è impostato su succeeded e il risultato contiene le informazioni del modello personalizzate. 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 e description proprietà.

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

Modifiche al modello di copia

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 l'operazione completata correttamente

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

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

I modelli di elenco sono stati estesi a ora restituiscono modelli predefiniti e personalizzati. Tutti i nomi dei modelli predefiniti iniziano con prebuilt-. Vengono restituiti solo i modelli con stato di esito positivo. Per elencare i modelli non riusciti o in corso, vedere Operazioni elenco.

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 tipo di documento è descritto dal nome, dalla descrizione facoltativa, dallo schema del campo e dalla attendibilità facoltativa del campo. Lo schema del campo descrive l'elenco di 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 nel 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

In questa guida alla migrazione si è appreso come aggiornare l'applicazione di Riconoscimento modulo esistente per usare le API v3.0.