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

Краткое руководство. Основные интерфейсы REST API службы "Основные сведения о содержимом ИИ Azure"

  • Статья

  • Начните использовать последнюю предварительную версию REST API службы "Понимание содержимого Azure" (2024-12-01-preview).

  • Azure AI Content Understanding — это новая служба ИИ на основе искусственного интеллекта Azure, которая анализирует файлы любого модальности (документы, изображения, видео и аудио) и извлекает структурированные выходные данные в пользовательских форматах полей.

  • Интегрируйте службу "Распознавание содержимого" в рабочие процессы и приложения, легко вызывая интерфейсы REST API.

  • В этом кратком руководстве описано, как использовать REST API content Understanding для создания пользовательского анализатора и извлечения содержимого и полей из входных данных.

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

Чтобы приступить к работе, вам нужна активная подписка Azure. Если у вас нет учетной записи Azure, можно создать бесплатную подписку.

  • После получения подписки Azure создайте ресурс Служб искусственного интеллекта Azure в портал Azure. Этот ресурс с несколькими службами обеспечивает доступ к нескольким службам ИИ Azure с одним набором учетных данных.

    • Этот ресурс указан в службах ИИ Azure → службах ИИ Azure на портале.

      Внимание

      Azure предоставляет несколько типов ресурсов с именем служб ИИ Azure. Убедитесь, что выбран один из служб ИИ Azure → службами ИИ Azure, как показано на следующем рисунке. Дополнительные сведения см. в статье "Создание ресурса Служб искусственного интеллекта Azure".

      Снимок экрана: страница ресурсов с несколькими службами в портал Azure.

  • В этом кратком руководстве мы используем средство командной строки cURL. Если она не установлена, можно скачать версию для среды разработки:

Добавление пользовательского анализатора

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

Сначала создайте JSON-файл request_body.json с именем со следующим содержимым:

{
  "description": "Sample invoice analyzer",
  "scenario": "document",
  "config": {
    "returnDetails": true
  },
  "fieldSchema": {
    "fields": {
      "VendorName": {
        "type": "string",
        "method": "extract",
        "description": "Vendor issuing the invoice"
      },
      "Items": {
        "type": "array",
        "method": "extract",
        "items": {
          "type": "object",
          "properties": {
            "Description": {
              "type": "string",
              "method": "extract",
              "description": "Description of the item"
            },
            "Amount": {
              "type": "number",
              "method": "extract",
              "description": "Amount of the item"
            }
          }
        }
      }
    }
  }
}

Перед выполнением следующих cURL команд внесите следующие изменения в HTTP-запрос:

  1. Замените {endpoint} конечные {key} точки и ключевые значения из экземпляра служб ИИ Azure портал Azure.
  2. Замените именем нового анализатора и создайте {analyzerId} , например myInvoice.

Запрос PUT

curl -i -X PUT "{endpoint}/contentunderstanding/analyzers/{analyzerId}?api-version=2024-12-01-preview" \
  -H "Ocp-Apim-Subscription-Key: {key}" \
  -H "Content-Type: application/json" \
  -d @request_body.json

Ответ PUT

Ответ 201 (Created) содержит Operation-Location заголовок, содержащий URL-адрес, который можно использовать для отслеживания состояния этой асинхронной операции создания.

201 Created
Operation-Location: {endpoint}/contentunderstanding/analyzers/{analyzerId}/operations/{operationId}?api-version=2024-12-01-preview

После завершения выполнение HTTP GET по URL-адресу возвращается "status": "succeeded".

curl -i -X GET "{endpoint}/contentunderstanding/analyzers/{analyzerId}/operations/{operationId}?api-version=2024-12-01-preview" \
  -H "Ocp-Apim-Subscription-Key: {key}"

Анализ файла

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

Перед выполнением команды cURL внесите следующие изменения в HTTP-запрос:

  1. Замените {endpoint} конечные {key} точки и ключевые значения из экземпляра служб ИИ Azure портал Azure.
  2. Замените {analyzerId} именем созданного ранее пользовательского анализатора.
  3. Замените {fileUrl} общедоступным URL-адресом файла для анализа, например путем к служба хранилища Azure BLOB-объекту с подписанным URL-адресом (SAS) или примером URL-адресаhttps://github.com/Azure-Samples/cognitive-services-REST-api-samples/raw/master/curl/form-recognizer/rest-api/invoice.pdf.

Запрос POST

curl -i -X POST "{endpoint}/contentunderstanding/analyzers/{analyzerId}:analyze?api-version=2024-12-01-preview" \
  -H "Ocp-Apim-Subscription-Key: {key}" \
  -H "Content-Type: application/json" \
  -d "{\"url\":\"{fileUrl}\"}"

Ответ POST

Ответ 202 (Accepted) содержит Operation-Location заголовок, содержащий URL-адрес, который можно использовать для отслеживания состояния этой асинхронной операции анализа.

202 Accepted
Operation-Location: {endpoint}/contentunderstanding/analyzers/{analyzerId}/results/{resultId}?api-version=2024-12-01-preview

Получение результата анализа

resultId Используйте заголовок из Operation-Location заголовка, возвращаемого предыдущим POST ответом, и получите результат анализа.

  1. Замените {endpoint} конечные {key} точки и ключевые значения из экземпляра служб ИИ Azure портал Azure.
  2. Замените {analyzerId} именем созданного ранее пользовательского анализатора.
  3. Замените {resultId} возвращенным resultId из POST запроса.

Запрос GET

curl -i -X GET "{endpoint}/contentunderstanding/analyzers/{analyzerId}/results/{resultId}?api-version=2024-12-01-preview" \
  -H "Ocp-Apim-Subscription-Key: {key}"

ОТВЕТ GET

Ответ JSON 200 (OK) содержит status поле, указывающее состояние операции. Если операция не завершена, значение status равно running или notStarted. В таких случаях необходимо снова вызвать API либо вручную, либо через скрипт. Подождите интервал в одну секунду или несколько между вызовами.

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

{
  "id": "bcf8c7c7-03ab-4204-b22c-2b34203ef5db",
  "status": "Succeeded",
  "result": {
    "analyzerId": "sample_invoice_analyzer",
    "apiVersion": "2024-12-01-preview",
    "createdAt": "2024-11-13T07:15:46Z",
    "warnings": [],
    "contents": [
      {
        "markdown": "CONTOSO LTD.\n\n\n# INVOICE\n\nContoso Headquarters...",
        "fields": {
          "VendorName": {
            "type": "string",
            "valueString": "CONTOSO LTD.",
            "spans": [ { "offset": 0, "length": 12 } ],
            "confidence": 0.941,
            "source": "D(1,0.5729,0.6582,2.3353,0.6582,2.3353,0.8957,0.5729,0.8957)"
          },
          "Items": {
            "type": "array",
            "valueArray": [
              {
                "type": "object",
                "valueObject": {
                  "Description": {
                    "type": "string",
                    "valueString": "Consulting Services",
                    "spans": [ { "offset": 909, "length": 19 } ],
                    "confidence": 0.971,
                    "source": "D(1,2.3264,5.673,3.6413,5.673,3.6413,5.8402,2.3264,5.8402)"
                  },
                  "Amount": {
                    "type": "number",
                    "valueNumber": 60,
                    "spans": [ { "offset": 995, "length": 6 } ],
                    "confidence": 0.989,
                    "source": "D(1,7.4507,5.6684,7.9245,5.6684,7.9245,5.8323,7.4507,5.8323)"
                  }
                }
              }, ...
            ]
          }
        },
        "kind": "document",
        "startPageNumber": 1,
        "endPageNumber": 1,
        "unit": "inch",
        "pages": [
          {
            "pageNumber": 1,
            "angle": -0.0039,
            "width": 8.5,
            "height": 11,
            "spans": [ { "offset": 0, "length": 1650 } ],
            "words": [
              {
                "content": "CONTOSO",
                "span": { "offset": 0, "length": 7 },
                "confidence": 0.997,
                "source": "D(1,0.5739,0.6582,1.7446,0.6595,1.7434,0.8952,0.5729,0.8915)"
              }, ...
            ],
            "lines": [
              {
                "content": "CONTOSO LTD.",
                "source": "D(1,0.5734,0.6563,2.335,0.6601,2.3345,0.8933,0.5729,0.8895)",
                "span": { "offset": 0, "length": 12 }
              }, ...
            ]
          }
        ],
        "paragraphs": [
          {
            "content": "CONTOSO LTD.",
            "source": "D(1,0.5734,0.6563,2.335,0.6601,2.3345,0.8933,0.5729,0.8895)",
            "span": { "offset": 0, "length": 12 }
          }, ...
        ],
        "sections": [
          {
            "span": { "offset": 0, "length": 1649 },
            "elements": [ "/sections/1", "/sections/2" ]
          },
          {
            "span": { "offset": 0, "length": 12 },
            "elements": [ "/paragraphs/0" ]
          }, ...
        ],
        "tables": [
          {
            "rowCount": 2,
            "columnCount": 6,
            "cells": [
              {
                "kind": "columnHeader",
                "rowIndex": 0,
                "columnIndex": 0,
                "rowSpan": 1,
                "columnSpan": 1,
                "content": "SALESPERSON",
                "source": "D(1,0.5389,4.5514,1.7505,4.5514,1.7505,4.8364,0.5389,4.8364)",
                "span": { "offset": 512, "length": 11 },
                "elements": [ "/paragraphs/19" ]
              }, ...
            ],
            "source": "D(1,0.4885,4.5543,8.0163,4.5539,8.015,5.1207,0.4879,5.1209)",
            "span": { "offset": 495, "length": 228 }
          }, ...
        ]
      }
    ]
  }
}

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

  • Из этого краткого руководства вы узнали, как вызвать REST API для создания пользовательского анализатора. Для взаимодействия с пользователем воспользуйтесь порталом Azure AI Foundry.