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

  • Статья

Это содержимое относится к:checkmarkv4.0 (предварительная версия)checkmark3.1 (GA)v3.0 (GA)checkmarkcheckmarkv2.1 (GA)

Важно!

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

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

Предварительные версии API периодически устарели. Если вы используете предварительную версию API, обновите приложение для целевой версии API общедоступной версии. Чтобы перейти от версии API 2023-02-28-preview к 2023-07-31 версии API (GA), обновите текущую версию пакета SDK для конкретного языка.

API 2023-07-31 общедоступной версии API имеет несколько обновлений и изменений из предварительной версии API:

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

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

Model ID Извлечение текста Абзацы Роли абзаца Метки выделения Таблицы Пары "Ключ-значение" Языки Штрихкоды Анализ документов Формулы* StyleFont* Высокий разрешение OCR*
prebuilt-read ✓ ✓ O O O O O
prebuilt-layout ✓ ✓ ✓ ✓ ✓ O O O O O
prebuilt-document ✓ ✓ ✓ ✓ ✓ ✓ O O O O O
prebuilt-businessCard ✓ ✓
prebuilt-idDocument ✓ O O ✓ O O O
prebuilt-invoice ✓ ✓ ✓ O O O ✓ O O O
prebuilt-receipt ✓ O O ✓ O O O
prebuilt-healthInsuranceCard.us ✓ O O ✓ O O O
prebuilt-tax.us.w2 ✓ ✓ O O ✓ O O O
prebuilt-tax.us.1098 ✓ ✓ O O ✓ O O O
prebuilt-tax.us.1098E ✓ ✓ O O ✓ O O O
prebuilt-tax.us.1098T ✓ ✓ O O ✓ O O O
предварительно созданный контракт ✓ ✓ ✓ ✓ O O ✓ O O O
{ customModelName } ✓ ✓ ✓ ✓ ✓ O O ✓ O O O

✓ — включенА O — необязательные формулы/ 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

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

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

Внимание

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

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

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

Запрос 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-адреса результатов анализа с помощью запроса GET для проверки состояния операции анализа (минимальный рекомендуемый интервал между запросами — 1 секунда).
  • При успешном выполнении состояние устанавливается в значение "Успешно" и analyzeResult возвращается в тексте ответа. Если возникают ошибки, возвращается failedсостояние и возвращается ошибка.
Модель Версия 2.0 Версия 2.1 3.1
Префикс URL-адреса запроса https://{your-form-recognizer-endpoint}/formrecognizer/v2.0 https://{your-form-recognizer-endpoint}/formrecognizer/v2.1 https://{your-form-recognizer-endpoint}/formrecognizer
Документ общего назначения; Неприменимо Неприменимо /documentModels/prebuilt-document:analyze
Макет /layout/analyze /layout/analyze /documentModels/prebuilt-layout:analyze
Пользовательское /custom/models/{modelId}/analyze /custom/{modelId}/analyze /documentModels/{modelId}:analyze
Счет-фактура Н/П /prebuilt/invoice/analyze /documentModels/prebuilt-invoice:analyze
Получения /prebuilt/receipt/analyze /prebuilt/receipt/analyze /documentModels/prebuilt-receipt:analyze
Удостоверение Н/П /prebuilt/idDocument/analyze /documentModels/prebuilt-idDocument:analyze
Визитная карточка Н/П /prebuilt/businessCard/analyze /documentModels/prebuilt-businessCard:analyze
W-2 Неприменимо Неприменимо /documentModels/prebuilt-tax.us.w2:analyze
Медицинское страхование карта Неприменимо Неприменимо /documentModels/prebuilt-healthInsuranceCard.us:analyze
Контракт Неприменимо Неприменимо /documentModels/prebuilt-contract:analyze

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

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

Чтобы указать общедоступный URL-адрес, задайте для Content-Type значение 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).

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

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

Следующие шаги