Краткое руководство: REST API для пользовательской классификации текста

Используйте эту статью, чтобы приступить к созданию проекта пользовательской классификации текста, в котором можно выполнять обучение настраиваемых моделей для классификации текста. Модель — это программное обеспечение ИИ, обученное для выполнения определенной задачи. Для этой системы модели классифицируют текст, а для обучения этих моделей используются данные с тегами.

Пользовательская классификация текстов поддерживает проекты двух типов:

• Классификация по одной метке — каждому документу из набора данных можно назначить только один класс. Например, сценарий фильма можно классифицировать только как "Романтика" или "Комедия".
• Классификация по нескольким меткам — каждому документу из набора данных можно назначить несколько классов. Например, сценарий фильма можно классифицировать как "Комедия" или "Романтика" и "Комедия".

В этом кратком руководстве вы можете использовать примеры наборов данных, предоставляемых для создания классификации нескольких меток для классификации сценариев фильмов в одну или несколько категорий. Кроме того, можно использовать один набор данных классификации меток для классификации абстрактов научных статей в одном из определенных доменов.

Предварительные условия

• Подписка Azure — создайте бесплатную учетную запись.

Создание нового языка Azure в ресурсе Foundry Tools и учетной записи хранения Azure

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

Создание ресурса на портале Azure

1. Перейдите на портал Azure , чтобы создать новый ресурс Azure Language in Foundry Tools.

2. В появившемся окне выберите настраиваемую классификацию текста и распознавание именованных сущностей из пользовательских функций. Нажмите кнопку "Продолжить", чтобы создать ресурс в нижней части экрана.

   

3. Создайте языковой ресурс с приведенными ниже сведениями.

   Имя.	Обязательное значение
   Подписка	Ваша подписка Azure.
   Группа ресурсов	Группа ресурсов, которая будет включать ваш ресурс. Можно использовать уже существующий или создать новый.
   Область/регион	Один из поддерживаемых регионов. Например, "Запад США 2".
   Имя.	Имя ресурса.
   Ценовая категория	Одна из поддерживаемых ценовых категорий. Вы можете использовать уровень "Бесплатный" (F0), чтобы поработать со службой.

   Если появится сообщение Ваша учетная запись входа не является владельцем выбранной группы ресурсов учетной записи хранения, значит, вашей учетной записи должна быть назначена роль владельца в группе ресурсов, только тогда вы сможете создать ресурс "Язык". Обратитесь за помощью к владельцу подписки Azure.

   Вы можете определить владельца подписки Azure, выполнив поиск в группе ресурсов и следуя ссылке на связанную подписку. Затем:

   1. Выберите вкладку контроль доступа (IAM)
   2. Выбор назначений ролей
   3. Фильтрация по роли:владелец.

4. В разделе "Настраиваемая классификация текста" и "Распознавание именованных сущностей" выберите существующую учетную запись хранения или выберите новую учетную запись хранения. Учтите, что эти значения предназначены для того, чтобы помочь вам начать работу, и это не обязательно те значения для учетной записи хранения, которые вы захотите использовать в производственных средах. Чтобы избежать задержек при создании проекта, подключитесь к учетным записям хранения в том же регионе, что и языковой ресурс.

   Значение учетной записи хранения	Рекомендуемое значение
   Название учетной записи хранилища	Любое имя
   Тип учётной записи хранилища	Стандартный LRS

5. Убедитесь, что флажок Уведомление об ответственном применении ИИ установлен. Выберите Review + create в нижней части страницы.

Загрузка примерных данных в контейнер blob

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

Портал Azure

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

   Если группа ресурсов не отображается, убедитесь, что фильтр "Подписка равенВсе".

2. В учетной записи хранения в меню слева выберите Контейнеры под пунктом Хранилище данных. На появившемся экране нажмите + Контейнер. Присвойте контейнеру имя example-data и оставьте Уровень общего доступа, установленный по умолчанию.

   

3. После создания контейнера выберите его. Затем нажмите кнопку "Отправить", чтобы выбрать .txt скачанные ранее файлы..json

   

Получите свои ключи ресурсов и конечную точку

• Перейдите на страницу обзора ресурса на портале Azure

• В меню слева выберите Ключи и конечная точка. Конечная точка и ключ используются для запросов API.

Создание пользовательского проекта классификации текстов

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

Активация задания импорта проектов

Отправьте запрос POST, используя следующий URL-адрес, заголовки и текст JSON, чтобы импортировать файл меток. Убедитесь, что файл меток соответствует допустимому формату.

Если проект с таким именем уже существует, данные этого проекта заменяются.

{Endpoint}/language/authoring/analyze-text/projects/{projectName}/:import?api-version={API-VERSION}

Заголовки

Используйте следующий заголовок для проверки подлинности запроса.

Содержимое

Используйте следующий код JSON в запросе. Замените значения заполнителей собственными значениями.

{
  "projectFileVersion": "{API-VERSION}",
  "stringIndexType": "Utf16CodeUnit",
  "metadata": {
    "projectName": "{PROJECT-NAME}",
    "storageInputContainerName": "{CONTAINER-NAME}",
    "projectKind": "customMultiLabelClassification",
    "description": "Trying out custom multi label text classification",
    "language": "{LANGUAGE-CODE}",
    "multilingual": true,
    "settings": {}
  },
  "assets": {
    "projectKind": "customMultiLabelClassification",
    "classes": [
      {
        "category": "Class1"
      },
      {
        "category": "Class2"
      }
    ],
    "documents": [
      {
        "location": "{DOCUMENT-NAME}",
        "language": "{LANGUAGE-CODE}",
        "dataset": "{DATASET}",
        "classes": [
          {
            "category": "Class1"
          },
          {
            "category": "Class2"
          }
        ]
      },
      {
        "location": "{DOCUMENT-NAME}",
        "language": "{LANGUAGE-CODE}",
        "dataset": "{DATASET}",
        "classes": [
          {
            "category": "Class2"
          }
        ]
      }
    ]
  }
}

{
  "projectFileVersion": "{API-VERSION}",
  "stringIndexType": "Utf16CodeUnit",
  "metadata": {
    "projectName": "{PROJECT-NAME}",
    "storageInputContainerName": "{CONTAINER-NAME}",
    "projectKind": "customSingleLabelClassification",
    "description": "Trying out custom multi label text classification",
    "language": "{LANGUAGE-CODE}",
    "multilingual": true,
    "settings": {}
  },
  "assets": {
    "projectKind": "customSingleLabelClassification",
        "classes": [
            {
                "category": "Class1"
            },
            {
                "category": "Class2"
            }
        ],
        "documents": [
            {
                "location": "{DOCUMENT-NAME}",
                "language": "{LANGUAGE-CODE}",
                "dataset": "{DATASET}",
                "class": {
                    "category": "Class2"
                }
            },
            {
                "location": "{DOCUMENT-NAME}",
                "language": "{LANGUAGE-CODE}",
                "dataset": "{DATASET}",
                "class": {
                    "category": "Class1"
                }
            }
        ]
    }
}

После отправки запроса API вы получите ответ, указывающий 202 на правильность отправки задания. В заголовках ответа извлеките значение operation-location, отформатированное следующим образом:

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/import/jobs/{JOB-ID}?api-version={API-VERSION}

{JOB-ID} используется для идентификации запроса, так как эта операция является асинхронной. Этот URL-адрес используется для получения состояния задания импорта.

Возможные сценарии ошибок для этого запроса:

• выбранный ресурс не имеет необходимых разрешений для учетной записи хранения;
• Указанный storageInputContainerName не существует.
• используется недопустимый код языка или тип кода языка не является строковым;
• Значение multilingual является строкой, а не логическим значением.

Получение сведений о состоянии задания на импорт

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

Запросить URL-адрес

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/import/jobs/{JOB-ID}?api-version={API-VERSION}

Заголовки

Используйте следующий заголовок для проверки подлинности запроса.

Обучение модели

Как правило, после создания проекта вы присваиваете теги документам в подключенном к проекту контейнере. В этом кратком руководстве вы импортировали пример набора данных с тегами и инициализировали проект, используя пример JSON-файла с тегами.

Начало обучения модели

После импорта проекта можно начать обучение модели.

Отправьте запрос POST, используя следующий URL-адрес, заголовки и текст JSON, чтобы отправить задание обучения. Замените значения заполнителей собственными значениями.

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/:train?api-version={API-VERSION}

Заголовки

Используйте следующий заголовок для проверки подлинности запроса.

Текст запроса

Используйте следующий код JSON в тексте запроса. После завершения обучения модель получит имя {MODEL-NAME}. Модели создаются только в результате успешных заданий обучения.

{
	"modelLabel": "{MODEL-NAME}",
	"trainingConfigVersion": "{CONFIG-VERSION}",
	"evaluationOptions": {
		"kind": "percentage",
		"trainingSplitPercentage": 80,
		"testingSplitPercentage": 20
	}
}

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

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/train/jobs/{JOB-ID}?api-version={API-VERSION}

{JOB-ID} используется для идентификации запроса, так как эта операция является асинхронной. Этот URL-адрес позволяет получить текущее состояние обучения.

Получение состояния задания обучения

Обучение может занять от 10 до 30 минут. Следующий запрос можно использовать для регулярного опроса состояния задания обучения, пока оно не будет успешно завершено.

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

Запросить URL-адрес

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/train/jobs/{JOB-ID}?api-version={API-VERSION}

Заголовки

Используйте следующий заголовок для проверки подлинности запроса.

Текст ответа

После отправки запроса вы получите следующий ответ.

{
  "result": {
    "modelLabel": "{MODEL-NAME}",
    "trainingConfigVersion": "{CONFIG-VERSION}",
    "estimatedEndDateTime": "2022-04-18T15:47:58.8190649Z",
    "trainingStatus": {
      "percentComplete": 3,
      "startDateTime": "2022-04-18T15:45:06.8190649Z",
      "status": "running"
    },
    "evaluationStatus": {
      "percentComplete": 0,
      "status": "notStarted"
    }
  },
  "jobId": "{JOB-ID}",
  "createdDateTime": "2022-04-18T15:44:44Z",
  "lastUpdatedDateTime": "2022-04-18T15:45:48Z",
  "expirationDateTime": "2022-04-25T15:44:44Z",
  "status": "running"
}

Разверните вашу модель

Обычно после обучения модели изучаются сведения об оценке и вносятся необходимые улучшения. В этом кратком руководстве вы развернете свою модель и сделаете её доступной для тестирования в Language Studio, либо можете вызвать API прогнозирования.

Отправка задания развертывания

Отправьте запрос PUT, используя следующий URL-адрес, заголовки и текст JSON, чтобы отправить задание развертывания. Замените значения заполнителей собственными значениями.

{Endpoint}/language/authoring/analyze-text/projects/{projectName}/deployments/{deploymentName}?api-version={API-VERSION}

Заголовки

Используйте следующий заголовок для проверки подлинности запроса.

Текст запроса

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

{
  "trainedModelLabel": "{MODEL-NAME}"
}

После отправки запроса API вы получите ответ, указывающий 202 на правильность отправки задания. В заголовках ответа извлеките значение operation-location, отформатированное следующим образом:

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/deployments/{DEPLOYMENT-NAME}/jobs/{JOB-ID}?api-version={API-VERSION}

{JOB-ID} используется для идентификации запроса, так как эта операция является асинхронной. Этот URL-адрес можно использовать для получения состояния развертывания.

Получение статуса задания развертывания

Используйте следующий запрос GET для запроса состояния задания развертывания. Вы можете использовать URL-адрес, полученный на предыдущем шаге, или заменить значения заполнителей собственными значениями.

{ENDPOINT}/language/authoring/analyze-text/projects/{PROJECT-NAME}/deployments/{DEPLOYMENT-NAME}/jobs/{JOB-ID}?api-version={API-VERSION}

Заголовки

Используйте следующий заголовок для проверки подлинности запроса.

Текст ответа

После отправки запроса вы получите следующий ответ. Продолжайте опрос этой конечной точки до тех пор, пока значение параметра Состояние не изменится на "Выполнено". Необходимо получить код 200, указывающий на успешное выполнение запроса.

{
    "jobId":"{JOB-ID}",
    "createdDateTime":"{CREATED-TIME}",
    "lastUpdatedDateTime":"{UPDATED-TIME}",
    "expirationDateTime":"{EXPIRATION-TIME}",
    "status":"running"
}

Классификация текста

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

Отправка задачи пользовательской классификации текста

Используйте этот запрос POST для запуска задачи классификации текста.

{ENDPOINT}/language/analyze-text/jobs?api-version={API-VERSION}

Заголовки

Содержимое

{
  "displayName": "Classifying documents",
  "analysisInput": {
    "documents": [
      {
        "id": "1",
        "language": "{LANGUAGE-CODE}",
        "text": "Text1"
      },
      {
        "id": "2",
        "language": "{LANGUAGE-CODE}",
        "text": "Text2"
      }
    ]
  },
  "tasks": [
     {
      "kind": "CustomMultiLabelClassification",
      "taskName": "Multi Label Classification",
      "parameters": {
        "projectName": "{PROJECT-NAME}",
        "deploymentName": "{DEPLOYMENT-NAME}"
      }
    }
  ]
}

{
  "displayName": "Classifying documents",
  "analysisInput": {
    "documents": [
      {
        "id": "1",
        "language": "{LANGUAGE-CODE}",
        "text": "Text1"
      },
      {
        "id": "2",
        "language": "{LANGUAGE-CODE}",
        "text": "Text2"
      }
    ]
  },
  "tasks": [
    {
      "kind": "CustomSingleLabelClassification",
      "taskName": "Single Classification Label",
      "parameters": {
        "projectName": "{PROJECT-NAME}",
        "deploymentName": "{DEPLOYMENT-NAME}"
      }
    }
  ]
}

Ответ

Вы получите ответ 202, указывающий на успешность. В заголовках ответа извлеките . operation-location имеет следующий формат:

{ENDPOINT}/language/analyze-text/jobs/{JOB-ID}?api-version={API-VERSION}

Этот URL-адрес можно использовать для запроса состояния завершения задачи и получения результатов после ее завершения.

Получение результатов выполнения задачи

Используйте следующий запрос GET, чтобы запросить состояние или результаты задания классификации текста.

{ENDPOINT}/language/analyze-text/jobs/{JOB-ID}?api-version={API-VERSION}

Заголовки

Текст ответа

Ответ будет содержать документ JSON с приведенными ниже параметрами.

{
  "createdDateTime": "2021-05-19T14:32:25.578Z",
  "displayName": "MyJobName",
  "expirationDateTime": "2021-05-19T14:32:25.578Z",
  "jobId": "xxxx-xxxxxx-xxxxx-xxxx",
  "lastUpdateDateTime": "2021-05-19T14:32:25.578Z",
  "status": "succeeded",
  "tasks": {
    "completed": 1,
    "failed": 0,
    "inProgress": 0,
    "total": 1,
    "items": [
      {
        "kind": "customMultiClassificationTasks",
        "taskName": "Classify documents",
        "lastUpdateDateTime": "2020-10-01T15:01:03Z",
        "status": "succeeded",
        "results": {
          "documents": [
            {
              "id": "{DOC-ID}",
              "classes": [
                  {
                      "category": "Class_1",
                      "confidenceScore": 0.0551877357
                  }
              ],
              "warnings": []
            }
          ],
          "errors": [],
          "modelVersion": "2020-04-01"
        }
      }
    ]
  }
}

{
  "createdDateTime": "2021-05-19T14:32:25.578Z",
  "displayName": "MyJobName",
  "expirationDateTime": "2021-05-19T14:32:25.578Z",
  "jobId": "xxxx-xxxxxx-xxxxx-xxxx",
  "lastUpdateDateTime": "2021-05-19T14:32:25.578Z",
  "status": "succeeded",
  "tasks": {
    "completed": 1,
    "failed": 0,
    "inProgress": 0,
    "total": 1,
    "items": [
      {
        "kind": "customSingleClassificationTasks",
        "taskName": "Classify documents",
        "lastUpdateDateTime": "2020-10-01T15:01:03Z",
        "status": "succeeded",
        "results": {
          "documents": [
            {
              "id": "{DOC-ID}",
              "class": [
                  {
                      "category": "Class_1",
                      "confidenceScore": 0.0551877357
                  }
              ],
              "warnings": []
            }
          ],
          "errors": [],
          "modelVersion": "2020-04-01"
        }
      }
    ]
  }
}

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

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

{Endpoint}/language/authoring/analyze-text/projects/{projectName}?api-version={API-VERSION}

Заголовки

Используйте следующий заголовок для проверки подлинности запроса.

После отправки запроса API вы получите ответ, указывающий 202 на успешность, что означает удаление проекта. Успешный вызов приводит к использованию заголовка Operation-Location для проверки состояния задания.

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

После создания пользовательской модели классификации текста можно:

• Использование API среды выполнения для классификации текста

Когда вы начнете создавать собственные проекты пользовательской классификации текста, воспользуйтесь практическими руководствами, чтобы получить дополнительные сведения о разработке моделей.

• Выбор данных и проектирование схем
• Данные тегов
• Обучение модели
• Просмотр оценки модели