riconoscimento modulo migrazione v3.0 | Anteprima

Importante

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

riconoscimento modulo v3.0 (anteprima) introduce diverse nuove funzionalità:

Questo articolo illustra le differenze tra riconoscimento modulo v2.1 e v3.0 e come passare alla versione più recente dell'API.

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 un'unica coppia di operazioni assegnando e all'analisi del documentModels layout (layout predefinito) e ai modelli modelId predefiniti.

Richiesta POST

https://{your-form-recognizer-endpoint}/formrecognizer/documentModels/{modelId}?api-version=2021-07-30-preview

Richiesta GET

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

Operazione di analisi

  • Il payload della richiesta e il modello di chiamata rimangono invariati.
  • L'operazione Analyze specifica il documento di input e le configurazioni specifiche del contenuto e restituisce l'URL dei risultati dell'analisi tramite lOperation-Location nella risposta.
  • Eseguire il polling di questo URL risultato di analisi tramite una richiesta GET per controllare lo stato dell'operazione di analisi (l'intervallo minimo consigliato tra le richieste è 1 secondo).
  • In caso di esito positivo, lo stato viene impostato su succeeded e viene restituito analyzeResult nel corpo della risposta. Se vengono rilevati errori, lo stato verrà impostato su Non riuscito e 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
🆕 generale N/D /documentModels/prebuilt-document:analyze
Layout /layout/analyze /documentModels/prebuilt-layout:analyze
Impostazione personalizzata /custom/{modelId}/analyze /documentModels/{modelId}:analyze
Fattura /prebuilt/invoice/analyze /documentModels/prebuilt-invoice:analyze
Ricevuta /prebuilt/receipt/analyze /documentModels/prebuilt-receipt:analyze
Documento ID /prebuilt/idDocument/analyze /documentModels/prebuilt-idDocument:analyze
Biglietto da visita /prebuilt/businessCard/analyze /documentModels/prebuilt-businessCard: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 aggiuntivi

Parametri che continuano a essere supportati:

  • pagine
  • locale

Parametri non più supportati:

  • includeTextDetails

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

Modifiche per analizzare i risultati

La risposta di analisi è stata refactoring ai risultati di primo livello seguenti per supportare gli elementi a più pagine.

  • pagine
  • tabelle
  • keyValuePairs
  • entities
  • stili
  • documenti

Nota

Le modifiche della risposta analyzeResult includono una serie di modifiche, ad esempio il passaggio da una proprietà di pagine a una proprietà a livello superiore all'interno di analyzeResult.


{
// Basic analyze result metadata
"apiVersion": "2021-07-30-preview", // 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 bounding box 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": [ // Bounding boxes potentially across pages covered by table
{
"pageNumber": 1, // 1-indexed page number
"boundingBox": [ ... ], // Bounding box
}
],
"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 include due aggiornamenti nella nuova API

  • modelId è ora una proprietà che può essere impostata su un modello per un nome leggibile.
  • modelName è stata rinominato in description

buildL'operazione 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 e restituisce il risultato tramite lOperation-Location nella risposta. Eseguire il polling dell'URL dell'operazione del modello tramite una richiesta GET per controllare lo stato dell'operazione di compilazione (l'intervallo minimo consigliato tra le richieste è 1 secondo). A differenza della versione 2.1, questo URL non è il percorso della risorsa del modello. Al contrario, l'URL del modello può essere costruito dal modelId specificato, recuperato anche dalla proprietà resourceLocation nella risposta. In caso di esito positivo, lo stato viene impostato succeeded su e il risultato contiene le informazioni sul modello personalizzato. Se vengono rilevati errori, lo stato viene impostato su failed e viene restituito l'errore.

Il codice seguente è una richiesta di compilazione di esempio che usa 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=2021-09-30-preview

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

Modifiche per comporre il modello

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 delle modelId proprietà description e .

POST https://{your-form-recognizer-endpoint}/formrecognizer/documentModels:compose?api-version=2021-09-30-preview
{
  "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 è disponibile una richiesta POST.
  • Inviare l'autorizzazione alla risorsa di origine per copiare la chiamata al modello copy-to
  • Eseguire il polling dell'operazione restituita per convalidare il completamento dell'operazione

Le uniche modifiche alla funzione del modello di copia sono:

  • L'azione HTTP authorizeCopy in è 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=2021-09-30-preview
{
  "modelId": "{targetModelId}",
  "description": "{targetModelDescription}",
}

Usare il corpo della risposta dall'azione authorize per costruire la richiesta per la copia.

POST https://{sourceHost}/formrecognizer/documentModels/{sourceModelId}:copy-to?api-version=2021-09-30-preview
{
  "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 per restituire modelli predefiniti e personalizzati. Tutti i nomi di modello predefiniti iniziano con prebuilt- . Vengono restituiti solo i modelli con stato completato. Per elencare i modelli che hanno avuto esito negativo o sono in corso, vedere Operazioni di elenco.

Richiesta di modelli di elenco di esempio

GET https://{your-form-recognizer-endpoint}/formrecognizer/documentModels?api-version=2021-09-30-preview

Modificare per ottenere il modello

Poiché get model include ora modelli predefiniti, l'operazione get restituisce docTypes un dizionario. Ogni tipo di documento viene descritto in base al nome, alla descrizione facoltativa, allo schema del campo e all'attendibilità dei campi facoltativa. 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=2021-09-30-preview

Nuova operazione get info

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

GET https://{your-form-recognizer-endpoint}/formrecognizer/info? api-version=2021-09-30-preview

Risposta di esempio

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

Passaggi successivi

In questa guida alla migrazione si è appreso come aggiornare l'applicazione riconoscimento modulo esistente per usare le API v3.0. Continuare a usare l'API 2.1 per tutte le funzionalità di ga e usare l'API 3.0 per qualsiasi funzionalità di anteprima.