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

Поддержка собственного документа для языка ИИ Azure (предварительная версия)

  • Статья

Внимание

  • Выпуски общедоступной предварительной версии языка искусственного интеллекта Azure предоставляют ранний доступ к функциям, которые находятся в активной разработке.
  • Функции, подходы и процессы могут изменяться до общедоступной доступности на основе отзывов пользователей.

Язык ИИ Azure — это облачная служба, которая применяет функции обработки естественного языка (NLP) к текстовым данным. Возможность поддержки собственных документов позволяет асинхронно отправлять запросы API с помощью текста ЗАПРОСА HTTP POST для отправки данных и строки запроса HTTP GET для получения результатов состояния. Обработанные документы находятся в целевом контейнере Хранилище BLOB-объектов Azure.

Собственный документ ссылается на формат файла, используемый для создания исходного документа, например Microsoft Word (docx) или переносимого файла документа (pdf). Поддержка собственных документов устраняет необходимость предварительной обработки текста перед использованием возможностей ресурсов языка искусственного интеллекта Azure. В настоящее время поддержка собственных документов доступна для следующих возможностей:

  • Персональные данные (PII) Функция распознавания персональных данных позволяет определять, классифицировать и исправлять конфиденциальную информацию в неструктурированном тексте. PiiEntityRecognition API поддерживает собственную обработку документов.

  • Сводка документов. Сводка документов использует обработку естественного языка для создания извлекаемых (выделяющихся предложений) или абстрактных (извлечение контекстных слов) для документов. ExtractiveSummarization Оба AbstractiveSummarization и API поддерживают собственную обработку документов.

Поддерживаемые форматы документов

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

Тип файла Расширение файла Описание
Текст .txt Неформатированный текстовый документ.
Adobe PDF .pdf Переносимый документ с форматированным документом.
Microsoft Word .docx Файл документа Microsoft Word.

Рекомендации по входным данным

Поддерживаемые форматы файлов

Тип поддержка и ограничения
PDF-файлы Полностью сканированные PDF-файлы не поддерживаются.
Текст в изображениях Цифровые изображения с внедренным текстом не поддерживаются.
Цифровые таблицы Таблицы в сканированных документах не поддерживаются.

Размер документа

Атрибут Ограничение входных данных
Общее количество документов на запрос ≤ 20
Общий размер контента на запрос ≤ 10 МБ

Включение собственных документов с HTTP-запросом

Давайте приступим к работе:

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

    Примечание.

    Пакет cURL предварительно установлен в большинстве дистрибутивов Windows 10 и Windows 11, а также в большинстве дистрибутивов macOS и Linux. Вы можете проверить версию пакета со следующими командами: Windows: curl.exe -V macOS curl -V Linux: curl --version

  • Если cURL не установлен, вот ссылки на установку для вашей платформы:

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

  • Учетная запись хранения BLOB-объектов Azure. Кроме того, необходимо создать контейнеры в учетной записи Хранилище BLOB-объектов Azure для исходных и целевых файлов:

    • Контейнер исходных файлов. Этот контейнер предназначен для отправки собственных файлов для анализа (обязательно).
    • Контейнер целевых файлов. В этом контейнере хранятся проанализированные файлы (обязательные).

  • Ресурс языка с одним обслуживанием (а не ресурс служб ИИ Azure с несколькими службами):

    Заполните поля сведений о проекте ресурсов языка и экземпляре следующим образом:

    1. Подписка. Выберите одну из доступных подписок Azure.

    2. Группа ресурсов. Можно создать новую группу ресурсов или добавить ресурс в уже существующую группу, которая использует тот же жизненный цикл, разрешения и политики.

    3. Область ресурсов. Выберите Глобальный, если для вашего бизнеса или приложения не требуется конкретный регион. Если вы планируете использовать управляемое удостоверение, назначаемое системой (RBAC), для проверки подлинности выберите географический регион, например западная часть США.

    4. Имя. Введите имя, выбранное для ресурса. Выбранное вами имя должно быть уникальным в Azure.

    5. Ценовая категория. Используйте бесплатную ценовую категорию (Free F0), чтобы опробовать службу, а затем выполните обновление до платного уровня для рабочей среды.

    6. Выберите Review + Create (Просмотреть и создать).

    7. Проверьте условия обслуживания и щелкните Создать, чтобы развернуть ресурс.

    8. После успешного развертывания ресурса выберите "Перейти к ресурсу".

Получение конечной точки ключевой и языковой службы

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

  1. Если вы создали новый ресурс, после его развертывания нажмите кнопку "Перейти к ресурсу". Если у вас есть существующий ресурс службы языка, перейдите непосредственно на страницу ресурсов.

  2. На левой границе в разделе Управление ресурсами выберите Ключи и конечная точка.

  3. Вы можете скопировать и вставить key language service instance endpoint в примеры кода, чтобы пройти проверку подлинности запроса в языковой службе. Для вызова API необходим только один ключ.

Создание контейнеров Хранилище BLOB-объектов Azure

Создайте контейнеры в учетной записи Хранилище BLOB-объектов Azure для исходных и целевых файлов.

  • Контейнер исходных файлов. Этот контейнер предназначен для отправки собственных файлов для анализа (обязательно).
  • Контейнер целевых файлов. В этом контейнере хранятся проанализированные файлы (обязательные).

Аутентификация

Ресурс языка должен предоставить доступ к учетной записи хранения, прежде чем он сможет создавать, читать или удалять большие двоичные объекты. Существует два основных метода, которые можно использовать для предоставления доступа к данным хранилища:

  • Маркеры подписанного URL-адреса (SAS). Маркеры SAS делегирования пользователей защищены учетными данными Microsoft Entra. Маркеры SAS обеспечивают безопасный делегированный доступ к ресурсам в учетной записи хранения Azure.

  • Управление доступом на основе ролей управляемого удостоверения (RBAC). Управляемые удостоверения для ресурсов Azure — это субъекты-службы, которые создают удостоверение Microsoft Entra и определенные разрешения для управляемых ресурсов Azure.

Для этого проекта мы проверяем доступ к source location url-адресам и target location URL-адресам с помощью маркеров подписанного URL-адреса (SAS), добавленных в виде строк запроса. Каждому маркеру назначается определенный большой двоичный объект (файл).

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

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

Совет

Так как мы обрабатываем один файл (большой двоичный объект), рекомендуется делегировать доступ SAS на уровне БОЛЬШОго двоичного объекта.

Заголовки запросов и параметры

параметр Описание
-X POST <endpoint> Указывает конечную точку ресурса языка для доступа к API.
--header Content-Type: application/json Тип содержимого для отправки данных JSON.
--header "Ocp-Apim-Subscription-Key:<key> Указывает ключ ресурса языка для доступа к API.
-data JSON-файл, содержащий данные, которые необходимо передать с запросом.

Приведенные ниже команды cURL выполняются из оболочки BASH. Измените эти команды, указав имя ресурса, ключ ресурса и значения JSON. Попробуйте проанализировать собственные документы, выбрав Personally Identifiable Information (PII) проект или Document Summarization пример кода:

Пример документа piI

Для этого краткого руководства вам потребуется исходный документ, отправленный в исходный контейнер. Вы можете скачать пример документа Microsoft Word или Adobe PDF для этого проекта. Исходный язык — английский.

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

  1. С помощью предпочтительного редактора или интегрированной среды разработки создайте новый каталог для вашего приложения с именем native-document.

  2. Создайте файл JSON с именем pii-detection.json в собственном каталоге документов.

  3. Скопируйте и вставьте следующий пример запроса персональных данных (PII) в pii-detection.json файл. Замените и {your-target-container-SAS-URL} на значения {your-source-container-SAS-URL} из экземпляра контейнеров учетной записи хранения портал Azure:

Пример запроса

{ 
    "displayName": "Document PII Redaction example", 
    "analysisInput": { 
        "documents": [ 
            { 
                "language": "en-US", 
                "id": "Output-1", 
                "source": { 
                    "location": "{your-source-blob-with-SAS-URL}" 
                }, 
                "target": { 
                    "location": "{your-target-container-with-SAS-URL}" 
                } 
            } 
        ] 
    }, 
    "tasks": [ 
        { 
            "kind": "PiiEntityRecognition", 
            "taskName": "Redact PII Task 1", 
            "parameters": { 
                "redactionPolicy": { 
                    "policyKind": "entityMask"  // Optional. Defines redactionPolicy; changes behavior based on value. Options: noMask, characterMask (default), and entityMask. 
                }, 
                "piiCategories": [ 
                    "Person", 
                    "Organization" 
                ], 
                "excludeExtractionData": false  // Default is false. If true, only the redacted document is stored, without extracted entities data. 
            } 
        } 
    ] 
}

  • Исходное значение — ЭТО URL-адрес SAS для location исходного документа (BLOB-объекта), а не URL-адрес SAS исходного контейнера.

  • Возможные redactionPolicy значения: UseRedactionCharacterWithRefId (по умолчанию) или UseEntityTypeName. Дополнительные сведения см. в разделе "Параметры PiiTask".

Запуск запроса POST

  1. Ниже приведена предварительная структура запроса POST:

       POST {your-language-endpoint}/language/analyze-documents/jobs?api-version=2024-11-15-preview

  2. Перед выполнением запроса POST замените {your-language-resource-endpoint} значения {your-key} из экземпляра службы языка портал Azure.

    Внимание

    Обязательно удалите ключ из кода, когда завершите работу, и ни в коем случае не публикуйте его в открытом доступе. Для рабочей среды используйте безопасный способ хранения и доступа к учетным данным, например Azure Key Vault. Дополнительные сведения см. в статье "Безопасность служб искусственного интеллекта Azure".

    PowerShell

       cmd /c curl "{your-language-resource-endpoint}/language/analyze-documents/jobs?api-version=2024-11-15-preview" -i -X POST --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}" --data "@pii-detection.json"

    командная строка или терминал

       curl -v -X POST "{your-language-resource-endpoint}/language/analyze-documents/jobs?api-version=2024-11-15-preview" --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}" --data "@pii-detection.json"

  3. Ниже приведен пример ответа:

    HTTP/1.1 202 Accepted
Content-Length: 0
operation-location: https://{your-language-resource-endpoint}/language/analyze-documents/jobs/f1cc29ff-9738-42ea-afa5-98d2d3cabf94?api-version=2024-11-15-preview
apim-request-id: e7d6fa0c-0efd-416a-8b1e-1cd9287f5f81
x-ms-region: West US 2
Date: Thu, 25 Jan 2024 15:12:32 GMT

ОТВЕТ POST (jobId)

Вы получите ответ 202 (успешно), содержащий заголовок Operation-Location только для чтения. Значение этого заголовка содержит идентификатор задания , который можно запросить, чтобы получить состояние асинхронной операции и получить результаты с помощью запроса GET :

Снимок экрана: значение расположения операции в ответе POST.

Получение результатов анализа (запрос GET)

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

  2. Ниже приведена предварительная структура запроса GET :

      GET {your-language-endpoint}/language/analyze-documents/jobs/{jobId}?api-version=2024-11-15-preview

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

    • Замените {jobId} заголовком Operation-Location из ответа POST.

    • Замените {your-language-resource-endpoint} и {your-key} значениями из экземпляра языковой службы в портал Azure.

Запрос Get

    cmd /c curl "{your-language-resource-endpoint}/language/analyze-documents/jobs/{jobId}?api-version=2024-11-15-preview" -i -X GET --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}"

    curl -v -X GET "{your-language-resource-endpoint}/language/analyze-documents/jobs/{jobId}?api-version=2024-11-15-preview" --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}"

Изучите ответ.

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

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

{
  "jobId": "f1cc29ff-9738-42ea-afa5-98d2d3cabf94",
  "lastUpdatedDateTime": "2024-01-24T13:17:58Z",
  "createdDateTime": "2024-01-24T13:17:47Z",
  "expirationDateTime": "2024-01-25T13:17:47Z",
  "status": "succeeded",
  "errors": [],
  "tasks": {
    "completed": 1,
    "failed": 0,
    "inProgress": 0,
    "total": 1,
    "items": [
      {
        "kind": "PiiEntityRecognitionLROResults",
        "lastUpdateDateTime": "2024-01-24T13:17:58.33934Z",
        "status": "succeeded",
        "results": {
          "documents": [
            {
              "id": "doc_0",
              "source": {
                "kind": "AzureBlob",
                "location": "https://myaccount.blob.core.windows.net/sample-input/input.pdf"
              },
              "targets": [
                {
                  "kind": "AzureBlob",
                  "location": "https://myaccount.blob.core.windows.net/sample-output/df6611a3-fe74-44f8-b8d4-58ac7491cb13/PiiEntityRecognition-0001/input.result.json"
                },
                {
                  "kind": "AzureBlob",
                  "location": "https://myaccount.blob.core.windows.net/sample-output/df6611a3-fe74-44f8-b8d4-58ac7491cb13/PiiEntityRecognition-0001/input.docx"
                }
              ],
              "warnings": []
            }
          ],
          "errors": [],
          "modelVersion": "2023-09-01"
        }
      }
    ]
  }
}

После успешного завершения:

  • Проанализированные документы можно найти в целевом контейнере.
  • Успешный метод POST возвращает код ответа, указывающий 202 Accepted , что служба создала пакетный запрос.
  • Запрос POST также вернул заголовки ответа, включая Operation-Location значение, используемое в последующих запросах GET.

Очистка ресурсов

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

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

Обзор сведений об обнаружении персональных данных