Migrazione di Document Intelligence v4.0

Guide alla migrazione dell'SDK

Per indicazioni sull'aggiornamento del codice dell'applicazione per l'uso degli SDK v4.0, vedere le guide alla migrazione dell'SDK specifiche del linguaggio nei repository di GitHub. Queste guide forniscono istruzioni per aggiornare il codice per chiamare i nuovi metodi API e gestire i formati di risposta aggiornati introdotti nella versione 4.0:

• .NET/C# SDK

• JAVA SDK

• PYTHON SDK

• JavaScript/TypeScript SDK*

Migrazione dalla versione 3.1 alla versione 4.0

Le API di anteprima sono periodicamente ritirate. Se si usa una versione dell'API di anteprima, aggiornare l'applicazione in modo che corrisponda alla versione dell'API a disponibilità generale. Per eseguire la migrazione da una versione dell'API di anteprima alla 2024-11-30 (GA) versione dell'API usando l'SDK, eseguire l'aggiornamento alla versione corrente dell'SDK specifico del linguaggio. Le versioni precedenti dell'API v3.x verranno ritirate secondo il calendario pubblicato; v3.0 verrà ritirata il 30 marzo 2029.

Funzionalità di analisi

✓ - 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 l'estrazione delle proprietà di alta risoluzione, formule e caratteri tipografici.
• 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 per i tipi di documenti nel modello ID documento.
• 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à aggiuntive 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. Espandiamo il codice JSON del risultato per includere la quota e le informazioni utilizzate per aiutarti a 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 di 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 v4.0 è 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. Fare riferimento a panoramica del modello per le funzionalità e le capacità disponibili in v4.0.

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

Analizzare l'operazione

• 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, restituisce l'URL del risultato analizzato tramite l'intestazione Operation-Location nella risposta.
• Eseguire il polling dell'URL Analyze Result tramite una richiesta GET per controllare lo stato dell'operazione Analyze (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.

Analizzare il corpo della richiesta

Il contenuto da analizzare viene fornito tramite il corpo della richiesta. L'URL o i dati codificati in Base64 possono essere usati 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 aggiuntivamente

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. Es. "1-3,5,7-9"
• locale : Suggerimento locale 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 tag di lingua (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

Viene eseguito il refactoring della risposta di analisi nei seguenti risultati di livello superiore e supporta elementi a più pagine.

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

Compilare o addestrare 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 dall'uomo.
• 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, 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 è un esempio di richiesta di build usando un token SAS. 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 grazie all'aggiunta delle 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 al modello di copia

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

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

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 formulare la richiesta di 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 riuscito. Per elencare i modelli non riusciti o in corso, vedere Elencare le operazioni.

Esempio di richiesta per elencare i modelli

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

Modificare per ottenere l'operazione del modello

Come Get Model ora include 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 di ottenimento informazioni

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

• Esaminare la nuova API REST
• Che cos'è l'intelligence sui documenti?
• Guida rapida a Document Intelligence 0