Início Rápido: API REST de classificação de texto personalizado

Use este artigo para começar a criar um projeto de classificação de texto personalizada, no qual você pode treinar modelos personalizados para a classificação de texto. Um modelo é um software de IA treinado para realizar uma determinada tarefa. Para esse sistema, os modelos classificam texto e são treinados aprendendo com os dados marcados.

A classificação de textos personalizada dá suporte a dois tipos de projetos:

• Classificação de rótulo único: é possível atribuir uma classe a cada documento no conjunto de dados. Por exemplo, um roteiro de filme só poderia ser classificado como "Romance" ou "Comédia".
• Classificação de diversos rótulos: é possível atribuir diversas classes a cada documento no conjunto de dados. Por exemplo, um roteiro de filme pode ser classificado como "Comédia" ou "Romance" e "Comédia".

Neste início rápido, você pode usar os conjuntos de dados de exemplo fornecidos para criar uma classificação de vários rótulos para classificar scripts de filme em uma ou mais categorias. Como alternativa, você pode usar o conjunto de dados de classificação de rótulo único para classificar resumos de artigos científicos em um dos domínios definidos.

Pré-requisitos

• Assinatura do Azure – crie uma gratuitamente.

Criar um novo recurso do Azure Language in Foundry Tools e uma conta de armazenamento do Azure

Antes de usar a classificação de texto personalizada, você precisará criar um recurso de linguagem, que fornecerá as credenciais necessárias para criar um projeto e começar a treinar um modelo. Você também precisará de uma conta de armazenamento do Azure, na qual poderá carregar seu conjunto de dados usado na criação do modelo.

Criar um recurso usando o portal do Azure

1. Acesse o portal do Azure para criar um novo recurso de Serviços de Linguagem do Azure nas Ferramentas Foundry.

2. Na janela que aparece, selecione Classificação de textos personalizada e reconhecimento de entidade nomeada personalizada nos recursos personalizados. Selecione Continuar para criar seu recurso na parte inferior da tela.

   

3. Crie um recurso de Linguagem com os detalhes a seguir.

   Nome	Valor obrigatório
   Subscrição	Sua assinatura do Azure.
   Grupo de recursos	O grupo de recursos que conterá seu recurso. É possível usar um grupo existente ou criar um do zero.
   Região	Uma das regiões com suporte. Por exemplo, "Oeste dos EUA 2".
   Nome	Um nome para seu recurso.
   Tipo de preço	Um dos tipos de preços com suporte. Use a camada Gratuita (F0) para experimentar o serviço.

   Se você receber uma mensagem dizendo que "sua conta de logon não é uma proprietária do grupo de recursos da conta de armazenamento selecionada", sua conta precisará ter uma função de proprietário atribuída no grupo de recursos antes de criar um recurso de linguagem. Entre em contato com o proprietário da assinatura do Azure para obter ajuda.

   Determine o proprietário da assinatura do Azure pesquisando seu grupo de recursos e seguindo o link para a assinatura associada. Em seguida:

   1. Selecione a guia Controle de Acesso (IAM)
   2. Selecione Atribuições de função
   3. Filtrar por Função:Proprietário.

4. Na seção Classificação de textos personalizada e reconhecimento de entidade nomeada personalizada, selecione uma conta de armazenamento existente ou Nova conta de armazenamento. Observe que esses valores são para ajudar você a começar a usar o recurso, e não são necessariamente os valores de conta de armazenamento que você usará nos ambientes de produção. Para evitar latência durante a criação do projeto, conecte-se às contas de armazenamento na mesma região que o recurso de Linguagem.

   Valor de conta de armazenamento	Valor recomendado
   Nome da conta de armazenamento	Qualquer nome
   Tipo de conta de armazenamento	LRS Padrão

5. Verifique se a opção Aviso de IA Responsável está marcada. Selecione Revisar + criar na parte inferior da página.

Carregar dados de exemplo para o contêiner de blob

Depois de criar uma conta de armazenamento do Azure e conectá-la ao recurso de idioma, você precisará carregar os documentos do conjunto de dados de exemplo para o diretório raiz do contêiner. Esses documentos são usados para treinar seu modelo.

portal do Azure

1. No portal do Azure, navegue até a conta de armazenamento que você criou e selecione-a selecionando contas de armazenamento e digitando o nome da conta de armazenamento em Filtro para qualquer campo.

   Se seu grupo de recursos não for exibido, verifique se o filtro A assinatura é igual a está definido como Todos.

2. Em sua conta de armazenamento, selecione Contêineres no menu esquerdo localizado abaixo de Armazenamento de dados. Na tela exibida, selecione + Contêiner. Nomeie o contêiner como example-data e deixe o Nível de acesso público padrão.

   

3. Depois que o contêiner for criado, selecione-o. Em seguida, selecione o botão Carregar para selecionar os arquivos .txt e .json baixados anteriormente.

   

Obter suas chaves de recurso e ponto de extremidade

• No portal do Azure, vá para a página de visão geral do recurso

• No menu do lado esquerdo, selecione Chaves e Ponto de Extremidade. O endpoint e a chave são usados para solicitações de API.

Criar um projeto de classificação de textos personalizada

Após configurar o recurso e o contêiner de armazenamento, crie um projeto de classificação de textos personalizada. Um projeto é uma área de trabalho para a criação de modelos de ML personalizados com base em seus dados. Seu projeto só pode ser acessado por você e outras pessoas que têm acesso ao recurso de Linguagem do Azure que está sendo usado.

Disparar trabalho de projeto de importação

Envie uma solicitaçãoPOST usando o URL, os cabeçalhos e o corpo JSON a seguir para importar o arquivo de rótulos. Verifique se o arquivo de rótulos segue o formato de arquivo aceito.

Se já existir um projeto com o mesmo nome, os dados desse projeto serão substituídos.

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

headers

Use o cabeçalho a seguir para autenticar sua solicitação.

Corpo

Use o JSON a seguir em sua solicitação. Substitua os valores do espaço reservado pelos seus.

{
  "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"
                }
            }
        ]
    }
}

Depois de enviar sua solicitação de API, você receberá uma 202 resposta indicando que o trabalho foi enviado corretamente. Nos cabeçalhos de resposta, extraia o operation-location valor formatado da seguinte forma:

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

{JOB-ID} é usado para identificar sua solicitação, pois essa operação é assíncrona. Use esta URL para obter o status da tarefa de importação.

Possíveis cenários de erro para esta solicitação:

• O recurso selecionado não tem as permissões apropriadas para a conta de armazenamento.
• O storageInputContainerName especificado não existe.
• Um código de idioma inválido foi usado ou o tipo de código de idioma não é cadeia de caracteres.
• O valor multilingual é uma cadeia de caracteres e não um booliano.

Obter Status do Trabalho de Importação

Use a solicitação GET a seguir para obter o status da importação do projeto. Substitua os valores do espaço reservado pelos seus.

URL de Solicitação

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

headers

Use o cabeçalho a seguir para autenticar sua solicitação.

Treinar seu modelo

Normalmente, depois de criar um projeto, você começa a marcar os documentos presentes no contêiner conectado ao projeto. Para este início rápido, você importou um conjunto de dados marcado de exemplo e inicializou o projeto com o arquivo de marcas JSON de exemplo.

Começar a treinar seu modelo

Depois que o projeto tiver sido importado, você poderá começar a treinar o modelo.

Envie uma solicitação POST usando a URL, os cabeçalhos e o corpo JSON a seguir para enviar um trabalho de treinamento. Substitua os valores do espaço reservado pelos seus.

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

headers

Use o cabeçalho a seguir para autenticar sua solicitação.

Corpo da solicitação

Use o JSON a seguir no corpo da solicitação. O modelo receberá o {MODEL-NAME} quando o treinamento for concluído. Somente os trabalhos de treinamento executados com êxito produzirão modelos.

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

Depois de enviar sua solicitação de API, você receberá uma 202 resposta indicando que o trabalho foi enviado corretamente. Nos cabeçalhos de resposta, extraia o location valor formatado da seguinte forma:

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

A {JOB-ID} é usada para identificar a solicitação, pois essa operação é assíncrona. Você pode usar essa URL para obter o status de treinamento.

Obter status do trabalho de treinamento

O treinamento pode levar entre dez e 30 minutos. Você pode usar a solicitação a seguir para continuar sondando o status do trabalho de treinamento até que ele seja concluído com êxito.

Use a seguinte solicitação GET para obter o status de progresso do treinamento do modelo. Substitua os valores do espaço reservado pelos seus.

URL de Solicitação

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

headers

Use o cabeçalho a seguir para autenticar sua solicitação.

Corpo da resposta

Depois de enviar a solicitação, você obtém a resposta a seguir.

{
  "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"
}

Implantar o seu modelo

Geralmente, depois de treinar um modelo, você pode revisar os detalhes da avaliação e fazer melhorias, se necessário. Neste início rápido, você apenas implantará o modelo e o disponibilizará para ser experimentado no Language Studio ou você poderá chamar a API de previsão.

Enviar trabalho de implantação

Envie uma solicitaçãoPUT usando a URL, os cabeçalhos e o corpo JSON a seguir para enviar o trabalho de implantação. Substitua os valores do espaço reservado pelos seus.

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

headers

Use o cabeçalho a seguir para autenticar sua solicitação.

Corpo da solicitação

Use o JSON a seguir no corpo da solicitação. Use o nome do modelo atribuído à implantação.

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

Depois de enviar sua solicitação de API, você receberá uma 202 resposta indicando que o trabalho foi enviado corretamente. Nos cabeçalhos de resposta, extraia o operation-location valor formatado da seguinte forma:

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

A {JOB-ID} é usada para identificar a solicitação, pois essa operação é assíncrona. Você pode usar essa URL para obter o status de implantação.

Obter status do trabalho de implantação

Use a solicitação GET a seguir para consultar o status do trabalho de implantação. Você pode usar a URL que recebeu na etapa anterior ou substituir os valores do espaço reservado por seus próprios valores.

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

headers

Use o cabeçalho a seguir para autenticar sua solicitação.

Corpo da resposta

Depois de enviar a solicitação, você obtém a resposta a seguir. Continue sondando esse ponto de extremidade até que o parâmetro de status mude para "bem-sucedido". Você deve obter um código 200 para indicar o sucesso da solicitação.

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

Classificar textos

Depois que o modelo for implantado com êxito, você poderá começar a usá-lo para classificar o texto por meio da API de Previsão. No conjunto de dados de exemplo que você baixou anteriormente, poderá encontrar alguns documentos de teste que podem ser usados nesta etapa.

Enviar uma tarefa de classificação de textos personalizada

Use esta solicitação POST para iniciar uma tarefa de classificação de textos.

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

headers

Corpo

{
  "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}"
      }
    }
  ]
}

Resposta

Você recebe uma resposta 202 indicando êxito. Nos cabeçalhos da resposta, extraia operation-location. operation-location é formatado da seguinte maneira:

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

Você pode usar essa URL para consultar o status de conclusão da tarefa e obter os resultados quando a tarefa for concluída.

Obter resultados da tarefa

Use a solicitação GET a seguir para consultar os status/resultados da tarefa de classificação de textos.

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

headers

Corpo da resposta

A resposta será um documento JSON com os seguintes parâmetros.

{
  "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"
        }
      }
    ]
  }
}

Limpar os recursos

Quando você não precisar mais do seu projeto, poderá excluí-lo com a seguinte solicitação de DELETE. Substitua os valores do espaço reservado pelos seus.

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

headers

Use o cabeçalho a seguir para autenticar sua solicitação.

Depois de enviar sua solicitação de API, você receberá uma 202 resposta indicando êxito, o que significa que seu projeto é excluído. Uma chamada bem-sucedida resulta em um cabeçalho Operation-Location usado para verificar o status do trabalho.

Próximas etapas

Depois de criar um modelo de classificação de texto personalizado, você pode:

• Usar a API de runtime para classificar o texto

Ao começar a criar seus próprios projetos de classificação de textos personalizada, use os artigos de instruções para saber mais sobre como desenvolver seu modelo com mais detalhes:

• Seleção de dados e design de esquema
• Marcar dados
• Treinar um modelo
• Exibir a avaliação do modelo