Quickstart: API REST personalizada de classificação de texto

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

A classificação de texto personalizada suporta dois tipos de projetos:

• Classificação de rótulo único - você pode atribuir uma única classe para cada documento em seu conjunto de dados. Por exemplo, um roteiro de filme só pode ser classificado como "Romance" ou "Comédia".
• Classificação de vários rótulos - você pode atribuir várias classes para cada documento em seu conjunto de dados. Por exemplo, um roteiro de filme pode ser classificado como "Comédia" ou "Romance" e "Comédia".

Neste quickstart, pode usar os conjuntos de dados de exemplo fornecidos para construir uma classificação multi-rótulo para classificar roteiros de filmes em uma ou mais categorias. Em alternativa, pode usar um conjunto de dados de classificação de etiqueta única para classificar resumos de artigos científicos num dos domínios definidos.

Pré-requisitos

• Subscrição do Azure - Crie uma gratuitamente.

Crie uma nova linguagem Azure no recurso Foundry Tools e uma conta de armazenamento Azure

Antes de poderes usar uma classificação de texto personalizada, terás de criar um recurso de Linguagem, que te dará as credenciais necessárias para criar um projeto e começar a treinar um modelo. Também vais precisar de uma conta de armazenamento Azure, onde podes carregar o conjunto de dados usado na construção do teu modelo.

Criar um novo recurso a partir do portal do Azure

1. Vá ao portal Azure para criar um novo recurso Azure Language no Foundry Tools.

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

   

3. Crie um recurso de idioma com os seguintes detalhes.

   Nome	Valor obrigatório
   Subscrição	A sua subscrição do Azure.
   Grupo de recursos	Um grupo de recursos que conterá seu recurso. Você pode usar um existente ou criar um novo.
   País/Região	Uma das regiões apoiadas. Por exemplo, "West US 2".
   Nome	Um nome para o seu recurso.
   Escalão de preço	Um dos níveis de preços suportados. Você pode usar a camada Gratuito (F0) para experimentar o serviço.

   Se você receber uma mensagem dizendo "sua conta de login não é 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 poder criar um recurso de idioma. Entre em contato com o proprietário da assinatura do Azure para obter assistência.

   Você pode determinar o proprietário da assinatura do Azure pesquisando seu grupo de recursos e seguindo o link para sua assinatura associada. Em seguida:

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

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

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

5. Certifique-se de que o Aviso de IA Responsável está verificado. Selecione Rever + criar na parte inferior da página.

Carregar dados de amostra para o contêiner de blob

Depois de criar uma conta de armazenamento Azure e ligá-la ao seu recurso de Linguagem, precisa de carregar os documentos do conjunto de dados de exemplo para o diretório raiz do seu contentor. Estes documentos são utilizados para treinar o seu modelo.

portal do Azure

1. No portal Azure, navegue até à conta de armazenamento que criou e selecione-a selecionando Contas de armazenamento e escrevendo o nome da sua conta de armazenamento em Filter para qualquer campo.

   se o teu grupo de recursos não aparecer, certifica-te de que o filtro Subscrição é igual a Todos.

2. Na sua conta de armazenamento, selecione Contêineres no menu à esquerda, localizado abaixo de Armazenamento de dados. Na tela exibida, selecione + Contêiner. Dê ao contêiner o nome example-data e deixe o nível de acesso público padrão.

   

3. Depois de criar o teu contentor, seleciona-o. Em seguida, selecione o botão Carregar para selecionar os .txt arquivos que .json você baixou anteriormente.

   

Obtenha suas chaves de recursos e ponto de extremidade

• Vá para a página de visão geral dos recursos no portal do Azure

• No menu do lado esquerdo, selecione Teclas e Ponto de extremidade. O endpoint e a chave são usados para pedidos de API.

Criar um projeto de classificação de texto personalizado

Depois que o contêiner de recursos e armazenamento estiver configurado, crie um novo projeto de classificação de texto personalizado. Um projeto é uma área de trabalho para criar seus modelos de ML personalizados com base em seus dados. O seu projeto só pode ser acedido por si e por outros que tenham acesso ao recurso Azure Language que está a ser utilizado.

Acionar trabalho de projeto de importação

Envie uma solicitação POST usando a seguinte URL, cabeçalhos e corpo JSON para importar seu arquivo de etiquetas. Certifique-se de que o ficheiro de etiquetas segue o formato aceite.

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}

Cabeçalhos

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

Corpo

Use o JSON a seguir em sua solicitação. Substitua os valores de espaço reservado por seus próprios valores.

{
  "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 valor operation-location formatado da seguinte forma:

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

{JOB-ID} é utilizado para identificar o seu pedido, uma vez que esta operação é assíncrona. Use essa URL para obter o estado da tarefa de importação.

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

• O recurso selecionado não tem permissões adequadas para a conta de armazenamento.
• O storageInputContainerName especificado não existe.
• Código de idioma inválido é usado, ou se o tipo de código de idioma não é string.
• multilingual value é uma cadeia de caracteres e não um booleano.

Obter status de trabalho de importação

Use a seguinte solicitação GET para obter o status da importação do projeto. Substitua os valores de espaço reservado por seus próprios valores.

URL do Pedido

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

Cabeçalhos

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

Preparar o modelo

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

Comece a treinar o seu modelo

Depois que seu projeto for importado, você poderá começar a treinar seu modelo.

Envie uma solicitação POST usando a seguinte URL, cabeçalhos e corpo JSON para enviar um trabalho de treinamento. Substitua os valores de espaço reservado por seus próprios valores.

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

Cabeçalhos

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

Corpo do pedido

Use o JSON a seguir no corpo da solicitação. O modelo será dado assim que o {MODEL-NAME} treinamento for concluído. Só empregos de formação bem sucedidos 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 valor location formatado da seguinte forma:

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

{JOB-ID} é utilizado para identificar o seu pedido, uma vez que esta operação é assíncrona. Você pode usar essa URL para obter o status de treinamento.

Obter status de trabalho de treinamento

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

Use a seguinte solicitação GET para obter o status do progresso do treinamento do seu modelo. Substitua os valores de espaço reservado por seus próprios valores.

URL do Pedido

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

Cabeçalhos

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

Organismo de resposta

Depois de enviar o pedido, recebe a seguinte resposta.

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

Implementar o modelo

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

Enviar trabalho de implantação

Envie uma solicitação PUT usando a seguinte URL, cabeçalhos e corpo JSON para enviar um trabalho de implantação. Substitua os valores de espaço reservado por seus próprios valores.

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

Cabeçalhos

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

Corpo do pedido

Use o JSON a seguir no corpo da sua solicitação. Use o nome do modelo que você atribui à 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 valor operation-location formatado da seguinte forma:

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

{JOB-ID} é utilizado para identificar o seu pedido, uma vez que esta operação é assíncrona. Você pode usar essa URL para obter o status da implantação.

Obter o status do trabalho de implantação

Use a seguinte solicitação GET para consultar o status do trabalho de implantação. Você pode usar a URL recebida da etapa anterior ou substituir os valores de marcadores de posição por seus próprios valores.

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

Cabeçalhos

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

Organismo de resposta

Depois de enviar o pedido, recebe a seguinte resposta. Continue pesquisando este ponto de extremidade até que o parâmetro de status mude para "bem-sucedido". Você deve obter um 200 código para indicar o sucesso da solicitação.

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

Classificar texto

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

Enviar uma tarefa de classificação de texto personalizada

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

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

Cabeçalhos

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

Recebe uma resposta 202 indicando sucesso. Nos cabeçalhos de resposta operation-location está formatado assim:

{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 de tarefas

Use a seguinte solicitação GET para consultar o status/resultados da tarefa de classificação de texto.

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

Cabeçalhos

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

Clean up resources (Limpar recursos)

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

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

Cabeçalhos

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

Assim que envia o seu pedido de API, recebe uma 202 resposta a indicar sucesso, o que significa que o seu projeto é eliminado. Uma chamada bem-sucedida resulta com um Operation-Location cabeçalho usado para verificar o status do trabalho.

Próximos passos

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

• Use a API de tempo de execução para classificar o texto

Quando você começar a criar seus próprios projetos de classificação de texto personalizados, 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
• Dados da tag
• Preparar um modelo
• Ver avaliação de modelo