Миграция аналитики документов версии 4.0

Руководства по миграции пакета SDK

Инструкции по обновлению кода приложения для использования пакетов SDK версии 4.0 см. в руководствах по миграции пакета SDK для конкретного языка в репозиториях GitHub. В этих руководствах приведены инструкции по обновлению кода для вызова новых методов API и обработки обновленных форматов ответов, представленных в версии 4.0:

• SDK для .NET/C#

• SDK Java

• пакет SDK Python

• Пакет SDK JavaScript и TypeScript*

Переход с версии 3.1 на версию 4.0

Предварительные версии API периодически выводятся из эксплуатации. Если вы используете предварительную версию API, обновите приложение для работы с финальной версией API. Чтобы перейти из предварительной версии API в версию 2024-11-30 (GA) API с помощью пакета SDK, обновите текущую версию пакета SDK для конкретного языка. Более ранние версии API версии 3.x будут прекращены по опубликованным расписаниям; Версия 3.0 выходит на пенсию 30 марта 2029 г.

Функции анализа

✓ — включено O — необязательные Formulas/StyleFont/OCR High Resolution* — функции уровня "Премиум" требуют дополнительных затрат

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

По сравнению с версией 3.0, Аналитика документов версии 3.1 содержит несколько новых функций и возможностей:

• Извлечение штрихкода.
• Возможности надстройки, включая извлечение свойств высокого разрешения, формул и шрифтов.
• Пользовательская модель классификации для разделения документов и классификации.
• Поддержка расширения языков и новых полей в моделях выставления счетов и квитанций.
• Поддержка нового типа документа в модели документов идентификатора .
• Новая предварительно созданная модель карты медицинского страхования .
• Office/HTML-файлы поддерживаются в предварительно созданной модели чтения, извлекая слова и абзацы без ограничивающих прямоугольников. Внедренные образы больше не поддерживаются. Если функции надстройки запрашиваются для файлов Office/HTML, пустой массив возвращается без ошибок.
• Срок действия модели для пользовательских моделей извлечения и классификации . Новые пользовательские модели создаются на основе крупной базовой модели, которая периодически обновляется для улучшения качества. Дата окончания срока действия вводится для всех пользовательских моделей, чтобы обеспечить списание соответствующих базовых моделей. После истечения срока действия пользовательской модели необходимо повторно обучить модель с помощью последней версии API (базовой модели).

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": { ... }
}

• Квота на сборку пользовательской нейронной модели — количество нейронных моделей, которые каждая подписка может создавать в каждом регионе каждый месяц, ограничена. Мы расширяем результат JSON, чтобы включить квоту и использованную информацию, чтобы понять текущее использование как часть сведений о ресурсе, возвращаемых GET /info.

{
  "customDocumentModels": { ... },
  "customNeuralDocumentModelBuilds": {
    "used": 1,
    "quota": 10,
    "quotaResetDateTime": "2023-03-01T00:00:00Z"
  }
}

• Необязательный features параметр запроса для операций анализа может дополнительно включать определенные функции. Некоторые функции уровня "Премиум" могут повлечь за собой добавленное выставление счетов. Дополнительные сведения см. в разделе "Анализ списка функций ".
• Расширьте извлеченные объекты валюты, чтобы вывести нормализованное поле кода валюты, когда это возможно. В настоящее время текущие поля могут возвращать сумму (например, 123,45) и валюту (например, $). Эта функция сопоставляет символ валюты с каноническим кодом ISO 4217 (например, USD). Модель может дополнительно использовать глобальное содержимое документа для диамбигуации или вывода кода валюты.

{
  "fields": {
    "Total": {
      "type": "currency",
      "content": "$123.45",
      "valueCurrency": {
        "amount": 123.45,
        "currencySymbol": "$",
        "currencyCode": "USD"
      },
      ...
    }
  }
}

Помимо улучшения качества модели, настоятельно рекомендуется обновить приложение для использования версии 3.1, чтобы воспользоваться этими новыми возможностями.

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

Аналитика документов версии 4.0 — это последняя версия общедоступной версии с самыми богатыми функциями, большинством языков и типов документов, а также улучшенным качеством модели. Ознакомьтесь с общими сведениями о функциях и возможностях, доступных в версии 4.0.

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

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

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

запрос POST

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

GET запрос

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

Анализ операции

• Типовая нагрузка запроса и шаблон вызова остаются неизменными.
• Операция Analyze задает входной документ и конфигурации содержимого, возвращает проанализированный URL-адрес результата через заголовок Operation-Location в ответе.
• Опрашивайте URL-адрес Analyze Result с помощью GET-запроса, чтобы проверить состояние операции Analyze (минимальный рекомендуемый интервал между запросами составляет 1 секунду).
• При успешном выполнении состояние устанавливается как "успешное", а analyzeResult возвращается в теле ответа. Если возникают ошибки, устанавливается состояние failed, и ошибка возвращается.

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

Содержимое, которое необходимо проанализировать, предоставляется через тело запроса. Url-адрес или данные в кодировке Base64 могут быть использованы для создания запроса.

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

{
  "urlSource": "{urlPath}"
}

Кодировка Base 64 также поддерживается в Аналитике документов версии 3.0:

{
  "base64Source": "{base64EncodedContent}"
}

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

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

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

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

• ВключитьДеталиТекста

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

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

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

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

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

Объект модели имеет три обновления в новом 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

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

Поскольку Get Model теперь включает предварительно созданные модели, Get операция возвращает 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
  }
}

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

• Просмотрите новый REST API
• Что такое аналитика документов?
• Краткое руководство по аналитике документов 0