Анализ пакетной аналитики документов

Статья
02/07/2025

API пакетного анализа позволяет выполнять массовую обработку нескольких документов с помощью одного асинхронного запроса. Вместо того чтобы отправлять документы по отдельности и отслеживать несколько идентификаторов запросов, вы можете проанализировать коллекцию документов, таких как счета, ряд документов по кредиту или группу пользовательских документов одновременно. Пакетный API поддерживает чтение документов из хранилища BLOB-объектов Azure и запись результатов в хранилище BLOB-объектов.

Для использования пакетного анализа требуется учетная запись хранения BLOB-объектов Azure с определенными контейнерами для исходных документов и обработанных выходных данных.
После завершения пакетная операция выводит список всех отдельных документов, обработанных с их состоянием, например succeeded, skippedили failed.
Версия пакетной Предварительная версия API доступна с помощью цен на оплату по мере использования.

Руководство по пакетной аналитике

Максимальное количество документов, обрабатываемых на один пакетный анализ запроса (включая пропущенные документы), составляет 10 000.
Результаты операции сохраняются в течение 24 часов после завершения. Документы и результаты указаны в учетной записи хранения, но состояние операции больше не доступно через 24 часа после завершения.

Готовы приступить к работе?

Необходимые компоненты

наличие активной подписки Azure. Если у вас нет подписки Azure, создайте ее бесплатно.
После получения подписки Azure экземпляра Аналитики документов в портал Azure. Вы можете использовать ценовую категорию "Бесплатный" (F0), чтобы поработать со службой.
После развертывания ресурса выберите элемент Перейти к ресурсу, чтобы получить ключ и конечную точку.
- Для подключения приложения к службе аналитики документов требуется ключ и конечная точка из ресурса. Вставьте ключ и конечную точку в код далее в кратком руководстве. Эти значения можно найти на странице "Ключи портал Azure" и "Конечная точка".
Учетная запись хранения BLOB-объектов Azure. Вы создадите контейнеры в учетной записи Хранилище BLOB-объектов Azure для исходных и результирующих файлов:
- Контейнер исходных файлов. В этом контейнере вы отправляете файлы для анализа (обязательно).
- Контейнер результатов. Этот контейнер хранит обработанные файлы (необязательно).

Вы можете назначить тот же контейнер Хранилище BLOB-объектов Azure для исходных и обработанных документов. Тем не менее, чтобы свести к минимуму потенциальные шансы случайного перезаписи данных, рекомендуется выбрать отдельные контейнеры.

Авторизация контейнера хранилища

Вы можете выбрать один из следующих вариантов, чтобы авторизовать доступ к ресурсу Document.

✔️ Управляемое удостоверение. Управляемое удостоверение — это субъект-служба, создающий удостоверение Microsoft Entra и определенные разрешения для управляемого ресурса Azure. Управляемые удостоверения позволяют запускать приложение Аналитики документов без необходимости внедрять учетные данные в код. Управляемые удостоверения — это более безопасный способ предоставления доступа к данным хранилища и замены требования к включению маркеров подписи общего доступа (SAS) в URL-адреса источника и результата.

Дополнительные сведения см. в разделе"Управляемые удостоверения" для аналитики документов.

Снимок экрана: поток управляемого удостоверения (управление доступом на основе ролей).

Внимание

При использовании управляемых удостоверений не включайте URL-адрес маркера SAS в HTTP-запросы, иначе запросы будут завершаться ошибкой. Использование управляемых удостоверений заменяет требование для включения маркеров подписанных URL-адресов (SAS).

✔️ Подписанный URL-адрес (SAS). Подписанный URL-адрес — это URL-адрес, предоставляющий ограниченный доступ в течение указанного периода времени службе аналитики документов. Чтобы использовать этот метод, необходимо создать маркеры подписанного URL-адреса (SAS) для исходных и результирующих контейнеров. Исходные и результирующий контейнеры должны включать маркер подписанного URL-адреса (SAS), добавленного в качестве строки запроса. Маркер может быть назначен контейнеру или конкретным BLOB-объектам.

Снимок экрана: URI хранилища с добавленным маркером SAS.

Исходныйконтейнер или большой двоичный объект должен назначить доступ для чтения, записи, списка и удаления.
Контейнер результатов или большой двоичный объект должны назначить запись, список, удалить доступ.

Дополнительные сведения см. в разделе "Создание маркеров SAS".

Вызов API пакетного анализа

Укажите URL-адрес контейнера Хранилище BLOB-объектов Azure для исходного azureBlobSource документа в пределах или azureBlobFileListSource объектов.

Указание входных файлов

Пакетный API поддерживает два варианта указания обрабатываемого файла. Если вам нужны все файлы в контейнере или папке, а количество файлов меньше 10000 для одного пакетного запроса, используйте azureBlobSource контейнер.

Если у вас есть определенные файлы в контейнере или папке для обработки, или количество обрабатываемых файлов превышает максимальное ограничение для одного пакета, используйте этот azureBlobFileListSourceпараметр. Разделите набор данных на несколько пакетов и добавьте файл со списком файлов, которые будут обрабатываться в формате JSONL в корневой папке контейнера. Примером формата списка файлов является.

{"file": "Adatum Corporation.pdf"}
{"file": "Best For You Organics Company.pdf"}

Укажите расположение результатов

Укажите URL-адрес контейнера Хранилище BLOB-объектов Azure для результатов пакетного анализа с помощью resultContainerUrl. Чтобы избежать случайного перезаписи, рекомендуется использовать отдельные контейнеры для исходных и обработанных документов.

overwriteExisting Задайте для логического свойства значение false, если вы не хотите, чтобы существующие результаты были перезаписаны с теми же именами файлов. Этот параметр не влияет на выставление счетов и запрещает перезаписывать результаты после обработки входного файла.

resultPrefix Задайте для пространства имен результаты этого запуска пакетного API.

Если вы планируете использовать один и тот же контейнер для входных и выходных данных, задайте resultContainerUrl и resultPrefix для сопоставления входных данных azureBlobSource.
При использовании того же контейнера можно включить overwriteExisting поле, чтобы решить, следует ли перезаписать файлы с файлами результатов анализа.

Создание и запуск запроса POST

Перед выполнением запроса POST замените {your-source-container-SAS-URL} и {your-result-container-SAS-URL} значениями из экземпляров контейнеров хранилища BLOB-объектов Azure.

В следующем примере показано, как добавить azureBlobSource свойство в запрос:

Разрешить только один или один из azureBlobSourceazureBlobFileListSourceних.

POST /documentModels/{modelId}:analyzeBatch

{
  "azureBlobSource": {
    "containerUrl": "https://myStorageAccount.blob.core.windows.net/myContainer?mySasToken",
    "prefix": "trainingDocs/"
  },
  "resultContainerUrl": "https://myStorageAccount.blob.core.windows.net/myOutputContainer?mySasToken",
  "resultPrefix": "layoutresult/",
  "overwriteExisting": true
}

В следующем примере показано, как добавить azureBlobFileListSource свойство в запрос:

POST /documentModels/{modelId}:analyzeBatch

{
   "azureBlobFileListSource": {
      "containerUrl": "https://myStorageAccount.blob.core.windows.net/myContainer?mySasToken",
      "fileList": "myFileList.jsonl"
    },
  "resultContainerUrl": "https://myStorageAccount.blob.core.windows.net/myOutputContainer?mySasToken",
  "resultPrefix": "customresult/",
  "overwriteExisting": true
}

Успешный ответ

202 Accepted
Operation-Location: /documentModels/{modelId}/analyzeBatchResults/{resultId}

Получение результатов API пакетного анализа

После выполнения операции пакетного API можно получить результаты пакетного анализа с помощьюGET операции. Эта операция извлекает сведения о состоянии операции, процент завершения операции и создание и обновление даты и времени.

GET /documentModels/{modelId}/analyzeBatchResults/{resultId}
200 OK

{
  "status": "running",      // notStarted, running, completed, failed
  "percentCompleted": 67,   // Estimated based on the number of processed documents
  "createdDateTime": "2021-09-24T13:00:46Z",
  "lastUpdatedDateTime": "2021-09-24T13:00:49Z"
...
}

Интерпретация сообщений о состоянии

Для каждого документа набор назначается состояние либо succeeded, failedлибо skipped. Для каждого документа есть два URL-адреса, предоставляемые для проверки результатов: sourceUrlэто контейнер исходного хранилища BLOB-объектов для успешного входного документа, который resultUrlсоздается путем объединения resultContainerUrl иresultPrefix создания относительного пути для исходного файла и .ocr.json.

Состояние notStarted или running. Операция пакетного анализа не инициируется или не завершена. Дождитесь завершения операции для всех документов.
Состояние completed. Операция пакетного анализа завершена.
Состояние failed. Сбой пакетной операции. Этот ответ обычно возникает при наличии общих проблем с запросом. Ошибки отдельных файлов возвращаются в ответе пакетного отчета, даже если все файлы не удалось. Например, ошибки хранения не останавливают пакетную операцию в целом, чтобы получить доступ к частичным результатам с помощью ответа пакетного отчета.

Только файлы с состоянием succeeded имеют свойство resultUrl , созданное в ответе. Это позволяет обучению модели обнаруживать имена файлов, которые заканчиваются .ocr.json и определять их как единственные файлы, которые можно использовать для обучения.

succeeded Пример ответа состояния:

[
  "result": {
    "succeededCount": 0,
    "failedCount": 2,
    "skippedCount": 2,
    "details": [
      {
        "sourceUrl": "https://{your-source-container}/myContainer/trainingDocs/file2.jpg",
        "status": "failed",
        "error": {
          "code": "InvalidArgument",
          "message": "Invalid argument.",
          "innererror": {
            "code": "InvalidSasToken",
            "message": "The shared access signature (SAS) is invalid: {details}"
                   }
               }
          }
      ]
   }
]
...

failed Пример ответа состояния:

Эта ошибка возвращается только в случае возникновения ошибок в общем пакетном запросе.
После запуска операции пакетного анализа состояние отдельной операции документа не влияет на состояние общего пакетного задания, даже если все файлы имеют состояние failed.

[
    "result": {
    "succeededCount": 0,
    "failedCount": 2,
    "skippedCount": 2,
    "details": [
        "sourceUrl": "https://{your-source-container}/myContainer/trainingDocs/file2.jpg",
        "status": "failed",
        "error": {
            "code": "InvalidArgument",
            "message": "Invalid argument.",
            "innererror": {
              "code": "InvalidSasToken",
              "message": "The shared access signature (SAS) is invalid: {details}"
                }
            }
        ]
    }
]
...

skipped Пример ответа состояния:

[
    "result": {
    "succeededCount": 3,
    "failedCount": 0,
    "skippedCount": 2,
    "details": [
        ...
        "sourceUrl": "https://myStorageAccount.blob.core.windows.net/myContainer/trainingDocs/file4.jpg",
        "status": "skipped",
        "error": {
            "code": "OutputExists",
            "message": "Analysis skipped because result file {path} already exists."
             }
        ]
    }
]
...

Результаты пакетного анализа помогают определить, какие файлы успешно анализируются и проверяют результаты анализа, сравнивая файл в resultUrl выходном файле в файле resultContainerUrlвывода.

Примечание.

Результаты анализа не возвращаются для отдельных файлов до завершения всего пакетного анализа набора документов. Чтобы отслеживать подробный ход выполнения, percentCompletedвы можете отслеживать *.ocr.json файлы по мере их записи в resultContainerUrl.

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

Просмотр примеров кода на GitHub.

Поделиться через