Миграция Распознавателя документов версии 3.0

  • Статья
  • Чтение занимает 8 мин

Важно!

REST API Распознавателя документов версии 3.0 вводит критические изменения в запрос REST API и анализ ответа JSON.

Миграция с предварительной версии API версии 3.0

Api предварительной версии периодически не рекомендуется использовать. Если вы используете предварительную версию API, запланируйте обновление приложения, чтобы оно ранее было доступно для общедоступной версии API. Чтобы перейти с версий API 2021-09-30-preview или 2022-01-30-preview на 2022-08-31 (общедоступную) версию API с помощью пакета SDK, обновите до текущей версии пакета SDK для конкретного языка.

Api 2022-08-31 содержит несколько обновлений из предварительных версий API:

  • Переименование поля: boundingBox к многоугольнику для поддержки не четырехугольников.
  • Поле удалено: сущности, удаленные из результата общей модели документа.
  • Переименование поля: documentLanguage.languageCode в языковой стандарт
  • Добавлена поддержка формата HEIF.
  • Добавлено обнаружение абзаца с классификацией ролей для макета и общих моделей документов.
  • Добавлена поддержка проанализированных полей адресов.

Миграция с версии 2.1

Распознаватель документов версии 3.0 предоставляет несколько новых функций и возможностей:

В этой статье представлены сведения о различиях между Распознавателем документов версии 2.1 и версии 3.0, а также о способах перехода к новой версии API.

Внимание!

  • Выпуск REST API 2022-08-31 включает критическое изменение в JSON ответа анализа REST API.
  • Свойство boundingBox переименовывается в polygon в каждом экземпляре.

Изменения в конечных точках REST API

REST API версии 3.0 объединяет аналитические операции по анализу макета, готовые модели и пользовательские модели в единую пару операций путем назначения documentModels и modelId для анализа макета (готового макета) и готовых моделей.

Запрос POST

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

Запрос GET

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

Операция анализа

  • Полезная нагрузка запроса и шаблон вызова остаются без изменений.
  • Операция Analyze ("Анализ") задает входной документ и конфигурации для конкретного содержимого, она возвращает URL-адрес результатов анализа через заголовок Operation-Location ("Расположение операции") в ответе.
  • Опрос данного URL-адреса результатов анализа с помощью запроса GET для проверки состояния операции анализа (минимальный рекомендуемый интервал между запросами — 1 секунда).
  • При успешном выполнении состояние устанавливается в значение "Успешно" и analyzeResult возвращается в тексте ответа. В случае обнаружения ошибок будет задано состояние failed и будет возвращена ошибка.
Моделирование Версия 2.1 v3.0
Префикс URL-адреса запроса https://{your-form-recognizer-endpoint}/formrecognizer/v2.1 https://{your-form-recognizer-endpoint}/formrecognizer
Документ общего назначения; Н/Д /documentModels/prebuilt-document:analyze
Макет /layout/analyze /documentModels/prebuilt-layout:analyze
Пользовательский /custom/{modelId}/analyze /documentModels/{modelId}:analyze
Накладная /prebuilt/invoice/analyze /documentModels/prebuilt-invoice:analyze
Карточка квитанции /prebuilt/receipt/analyze /documentModels/prebuilt-receipt:analyze
Удостоверение /prebuilt/idDocument/analyze /documentModels/prebuilt-idDocument:analyze
Визитная карточка /prebuilt/businessCard/analyze /documentModels/prebuilt-businessCard:analyze
W-2 /prebuilt/w-2/analyze /documentModels/prebuilt-w-2:analyze

Анализ текста запроса

Анализируемое содержимое предоставляется через текст запроса. URL-адрес или данные, закодированные с помощью Base64, могут быть пользовательскими для создания запроса.

Чтобы указать общедоступный URL-адрес, задайте для Content-Type значение application/json и отправьте следующий текст JSON:

{
  "urlSource": "{urlPath}"
}

Кодировка Base64 также поддерживается в Распознавателе документов версии 3.0:

{
  "base64Source": "{base64EncodedContent}"
}

Дополнительные поддерживаемые параметры

Параметры, которые продолжают поддерживаться:

  • pages: анализ только части страниц в документе. Список номеров страниц, индексированных из числа 1, для анализа. Например: "1-3,5,7-9"
  • locale: указание языкового стандарта для распознавания текста и анализа документов. Значение может содержать только языковой код (например, en, fr) или тег языка BCP 47 (например, en-US).

Параметры, которые больше не поддерживаются:

  • includeTextDetails

Новый формат ответа является более компактным, и всегда возвращаются все выходные данные.

Изменения в результатах анализа

Анализ ответа был перестроен в соответствии со следующими результатами верхнего уровня для поддержки многостраничных элементов.

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

Примечание

Изменения ответа analyzeResult включают ряд изменений, таких как переход от свойства страницы к свойству верхнего уровня в 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
}, ...
}
}, ...
]
}

Сборка или обучение модели

В новом API объект модели имеет три обновления

  • modelId теперь является свойством, которое можно задать для модели в виде понятного человеческого имени.
  • modelName был переименован в description.
  • buildMode — это новое свойство со значениями template для пользовательских моделей форм или neural для пользовательских нейронных моделей.

Операция build вызывается для обучения модели. Полезная нагрузка запроса и шаблон вызова остаются без изменений. В операции сборки указывается модель и набор данных обучения, результат возвращается через заголовок Operation-Location в ответе. Опрос данного URL-адреса операции модели с помощью запроса GET для проверки состояния операции сборки (минимальный рекомендуемый интервал между запросами — 1 секунда). В отличие от версии 2.1, этот URL-адрес не является расположением ресурса модели. Вместо этого URL-адрес модели может быть создан из заданного modelId, также полученного из свойства resourceLocation в ответе. При успешном выполнении состояние получает значение succeeded, а результат содержит сведения о пользовательской модели. В случае обнаружения ошибки задается состояние failed и возвращается ошибка.

Следующий код является примером запроса на сборку с использованием маркера SAS. Обратите внимание на замыкающую косую черту при установке префикса или пути к папке.

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/}"
  }
}

Изменения в создании модели

Создание модели теперь ограничено одним уровнем вложенности. Составные модели теперь согласовываются с пользовательскими моделями с добавлением свойств modelId и description.

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

Изменения в копировании модели

Шаблон вызова для копирования модели остается неизменным:

  • Авторизация операции копирования с помощью вызова authorizeCopy целевого ресурса. Теперь это запрос POST.
  • Отправка авторизации в исходный ресурс для копирования вызова модели copyTo
  • Опрос возвращенной операции для проверки успешности выполнения операции

Единственными изменениями функции копирования модели являются следующие:

  • Действие HTTP в authorizeCopy теперь является запросом POST.
  • Полезные данные авторизации содержат всю информацию, необходимую для отправки запроса на копирование.

Авторизация копирования

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

Используйте текст ответа из действия авторизации для создания запроса на копирование.

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

Изменения в списке моделей

Теперь список моделей расширен, чтобы теперь возвращать предварительно созданные и пользовательские модели. Все предварительно созданные имена моделей начинаются с prebuilt-. Добавлены только модели с состоянием "Успешно". Сведения о том, как вывести список невыполненных или выполняемых моделей, см. в разделе Операции вывода списка.

Запрос примера списка моделей

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

Изменения в получении модели

Поскольку функция "получить модель" теперь включает в себя предварительно созданные модели, операция получения возвращает словарь docTypes. Каждый тип документа описывается при помощи: имени, дополнительного описания, схемы поля и достоверности дополнительного поля. Схема поля описывает список полей, которые могут возвращаться с типом документа.

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

Новая операция получения сведений

Операция info в службе возвращает подсчет пользовательских моделей и ограничение числа пользовательской модели.

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

Пример ответа

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

Дальнейшие действия

В этом руководстве по миграции были рассмотрены сведения о способах обновления существующего приложения Распознавателя документов для использования API версии 3.0.