Início Rápido: Compreensão da linguagem coloquial

Pré-requisitos

• Assinatura do Azure – crie uma gratuitamente.

Conectar ao Language Studio

1. Vá para o Language Studio e entre com sua conta do Azure.

2. Na janela Escolher um recurso de linguagem que aparece, localize sua assinatura do Azure e escolha o recurso de linguagem. Se você não tiver um recurso, poderá criar um.

   Detalhes da instância	Valor obrigatório
   Assinatura do Azure	Sua assinatura do Azure.
   Grupo de recursos do Azure	O nome do grupo de recursos do Azure.
   Nome do recurso do Azure	Nome do seu recurso do Azure.
   Localização	Uma das regiões com suporte para o recurso de Linguagem. Por exemplo, "Oeste dos EUA 2".
   Tipo de preço	Um dos tipos de preço válidos para o recurso de Linguagem. Use a camada Gratuita (F0) para experimentar o serviço.

   

Criar um projeto de compreensão da linguagem coloquial

Após selecionar um recurso de Linguagem, crie um projeto de compreensão da linguagem coloquial. 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 por outras pessoas que têm acesso ao recurso de idioma sendo usado.

Para este início rápido, você pode baixar este arquivo de projeto de exemplo e importá-lo. Esse projeto pode prever os comandos pretendidos pela entrada do usuário, tais como: ler emails, excluir emails e anexar um documento a um email.

1. Na seção Compreensão de perguntas e da linguagem coloquial do Language Studio, selecione Compreensão da linguagem coloquial.

   

2. Isso o levará à página Projetos de compreensão da linguagem coloquial. Ao lado do botão Criar projeto, selecione Importar.

   

3. Na janela exibida, carregue o arquivo JSON que você deseja importar. Verifique se o arquivo segue o formato JSON com suporte.

Quando o carregamento for concluído, você chegará à página Definição de esquema. Neste início rápido, o esquema já foi criado e os enunciados já estão rotulados com intenções e entidades.

Treinar seu modelo

Normalmente, depois de criar um projeto, você deve criar um esquema e rotular enunciados. Neste início rápido, já importamos um projeto pronto com esquema criado e enunciados rotulados.

Para treinar um modelo, você precisa iniciar um trabalho de treinamento. A saída de um trabalho de treinamento bem-sucedido é seu modelo treinado.

Para começar a treinar o modelo no Language Studio:

1. Selecione Testar modelo no menu do lado esquerdo.

2. Selecione Iniciar um trabalho de treinamento no menu superior.

3. Selecione Treinar um novo modelo e insira um novo nome do modelo na caixa de texto. Caso contrário, para substituir um modelo existente por um modelo treinado nos novos dados, selecione Substituir um modelo existente e selecione um modelo existente. A substituição de um modelo treinado é irreversível, mas não afetará os modelos implantados até que você implante o novo modelo.

4. Selecione o modo de treinamento. Você pode escolher Treinamento padrão para um treinamento mais rápido, mas ele só está disponível em inglês. Ou você pode escolher Treinamento avançado que tem suporte para outros idiomas e projetos multilíngues, mas envolve tempos de treinamento mais longos. Saiba mais sobre os modos de treinamento.

5. Selecione o método divisão de dados. É possível optar por Dividir automaticamente o conjunto de teste dos dados de treinamento, em que o sistema dividirá os enunciados entre os conjuntos de treinamento e de teste, conforme os percentuais especificados. Ou você pode Usar uma divisão manual dos dados de treinamento e de teste. Essa opção será habilitada somente se você tiver adicionado enunciados ao conjunto de teste quando rotulou seus enunciados.

6. Selecione o botão Treinar.

   

7. Selecione a ID do trabalho de treinamento na lista. Um painel lateral será exibido para permitir a verificação do progresso do treinamento, do status do trabalho e de outros detalhes do trabalho.

   Observação

   • Somente os trabalhos de treinamento concluídos com êxito vão gerar modelos.
   • O treinamento pode levar entre alguns minutos e algumas horas, de acordo com a contagem dos dados rotulados.
   • É possível ter um trabalho de treinamento em execução por vez. Não é possível iniciar outros trabalhos de treinamento no mesmo projeto até que o trabalho em execução seja concluído.
   • O aprendizado de máquina usado para treinar modelos é atualizado regularmente. Para treinar em uma versão de configuração anterior, selecione Selecione aqui para alterar na página Iniciar um trabalho de treinamento e escolha uma versão anterior.

Implantar o seu modelo

Geralmente, após treinar um modelo, você poderá examinar os detalhes da avaliação. Neste início rápido, você implantará somente o modelo e o disponibilizará para ser experimentado no estúdio de Linguagem ou você poderá chamar a API de previsão.

Para implantar o modelo por meio do Language Studio:

1. Selecione Implantar um modelo no menu à esquerda.

2. Selecione Adicionar implantação para iniciar o assistente Adicionar implantação.

   

3. Selecione Criar um novo nome de implantação para criar uma implantação e atribuir um modelo treinado na lista suspensa abaixo. Caso contrário, você pode selecionar Substituir um nome de implantação existente para substituir efetivamente o modelo usado por uma implantação existente.

   Observação

   A substituição de uma implantação existente não exige alterações na chamada à API de Previsão, mas os resultados obtidos serão baseados no modelo recém-atribuído.

   

4. Selecione um modelo treinado na lista suspensa Modelo.

5. Selecione Implantar para iniciar a implantação.

6. Depois que a implantação for realizada com sucesso, uma data de validade será exibida. A expiração da implantação consiste no momento em que o modelo implantado não estará disponível para ser usado para previsão, o que normalmente acontece 12 meses após a expiração de uma configuração de treinamento.

Testar modelo implantado

Para testar os modelos implantados de dentro do Language Studio:

1. Selecione Testar implantações no menu à esquerda.

2. Para projetos multilíngues, na lista suspensa Selecionar idioma de texto, selecione o idioma do enunciado que você está testando.

3. Na lista suspensa Nome da implantação, selecione o nome da implantação correspondente ao modelo que você deseja testar. Você só pode testar modelos atribuídos a implantações.

4. Na caixa de texto, insira um enunciado para testar. Por exemplo, se você criou um aplicativo para enunciados relacionados a email, poderá inserir Excluir este email.

5. Na parte superior da página, selecione Executar o teste.

6. Após executar o teste, você deverá ver a resposta do modelo no resultado. É possível exibir os resultados no modo de exibição de cartões de entidades ou então exibi-los no formato JSON.

Limpar os recursos

Quando não precisar mais do seu projeto, poderá excluí-lo do projeto usando o Language Studio. Selecione Projetos no menu de navegação à esquerda, escolha o projeto que deseja excluir e clique em Excluir no menu superior.

Pré-requisitos

• Assinatura do Azure – crie uma gratuitamente.

Criar um recurso usando o portal do Azure

1. Entre no portal do Azure para criar um novo recurso de Linguagem de IA do Azure.

2. Selecione Criar um novo recurso

3. Na janela exibida, procure serviço de Linguagem

4. Escolha Criar

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

   Detalhes da instância	Valor necessário
   Região	Uma das regiões com suporte para o recurso de Linguagem.
   Nome	Nome obrigatório para o recurso de linguagem
   Tipo de preço	Um dos tipos de preço com suporte para o recurso de Linguagem.

Obter suas chaves de recurso e ponto de extremidade

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

2. No menu do lado esquerdo, selecione Chaves e Ponto de Extremidade. Você usará o ponto de extremidade e a chave para as solicitações de API

   

Importar um novo projeto de exemplo da CLU

Após criar um recurso de Linguagem, crie um projeto de compreensão da linguagem coloquial. 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 por outras pessoas que têm acesso ao recurso de idioma sendo usado.

Para este início rápido, você pode baixar este projeto de exemplo e importá-lo. Esse projeto pode prever os comandos pretendidos pela entrada do usuário, tais como: ler emails, excluir emails e anexar um documento a um email.

Disparar o trabalho de projeto de importação

Envie uma solicitaçãoPOST usando a URL, os cabeçalhos e o corpo JSON a seguir para importar seu projeto.

URL da solicitação

Use a URL a seguir ao criar sua solicitação de API. Substitua os valores do espaço reservado pelos seus.

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

Cabeçalhos

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

Corpo

O corpo JSON que você envia é semelhante ao exemplo a seguir. Confira a documentação de referência para obter mais detalhes sobre o objeto JSON.

{
  "projectFileVersion": "{API-VERSION}",
  "stringIndexType": "Utf16CodeUnit",
  "metadata": {
    "projectKind": "Conversation",
    "settings": {
      "confidenceThreshold": 0.7
    },
    "projectName": "{PROJECT-NAME}",
    "multilingual": true,
    "description": "Trying out CLU",
    "language": "{LANGUAGE-CODE}"
  },
  "assets": {
    "projectKind": "Conversation",
    "intents": [
      {
        "category": "intent1"
      },
      {
        "category": "intent2"
      }
    ],
    "entities": [
      {
        "category": "entity1"
      }
    ],
    "utterances": [
      {
        "text": "text1",
        "dataset": "{DATASET}",
        "intent": "intent1",
        "entities": [
          {
            "category": "entity1",
            "offset": 5,
            "length": 5
          }
        ]
      },
      {
        "text": "text2",
        "language": "{LANGUAGE-CODE}",
        "dataset": "{DATASET}",
        "intent": "intent2",
        "entities": []
      }
    ]
  }
}

Após uma solicitação bem-sucedida, a resposta da API conterá um cabeçalho operation-location com uma URL que você pode usar para verificar o status do trabalho de importação. É formatado assim:

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

Obter o status do trabalho de importação

Ao enviar uma solicitação de importação de projeto bem-sucedida, a URL completa da solicitação para verificar o status do trabalho de importação (incluindo seu ponto de extremidade, nome do projeto e ID do trabalho) está contida no cabeçalho operation-location da resposta.

Use a solicitação GET a seguir para consultar o status do trabalho de importaçã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-conversations/projects/{PROJECT-NAME}/import/jobs/{JOB-ID}?api-version={API-VERSION}

Cabeçalhos

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

Corpo da resposta

Depois de enviar a solicitação, você receberá a seguinte resposta. Continue sondando esse ponto de extremidade até que o parâmetro de status mude para "bem-sucedido".

{
  "jobId": "xxxxx-xxxxx-xxxx-xxxxx",
  "createdDateTime": "2022-04-18T15:17:20Z",
  "lastUpdatedDateTime": "2022-04-18T15:17:22Z",
  "expirationDateTime": "2022-04-25T15:17:20Z",
  "status": "succeeded"
}

Começar a treinar seu modelo

Normalmente, após de criar um projeto, você deverá criar esquema e marcar enunciados. Neste início rápido, já importamos um projeto pronto com esquema criado e enunciados marcados.

Crie uma solicitação POST usando a URL, os cabeçalhos e o corpo JSON a seguir para enviar um trabalho de treinamento.

URL da solicitação

Use a URL a seguir ao criar sua solicitação de API. Substitua os valores do espaço reservado pelos seus.

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

Cabeçalhos

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

Corpo da solicitação

Use o seguinte objeto em sua solicitação. O modelo receberá o nome do valor que você usa no parâmetro modelLabel assim que o treinamento for concluído.

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

Depois de enviar sua solicitação de API, você receberá uma 202 resposta indicando êxito. Nos cabeçalhos de resposta, extraia o valor operation-location. A formatação ficará da seguinte maneira:

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

É possível usar essa URL para obter o status do trabalho de treinamento.

Obter o status do trabalho de treinamento

O treinamento pode levar tempo para ser concluído. Às vezes, entre 10 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.

Ao enviar uma solicitação de treinamento bem-sucedida, a URL completa da solicitação para verificar o status do trabalho (incluindo seu ponto de extremidade, nome do projeto e ID do trabalho) está contida no cabeçalho operation-location da resposta.

Use a seguinte solicitação GET para obter o status de progresso do treinamento do modelo. Substitua os valores dos espaços reservados abaixo pelos seus próprios valores.

URL da solicitação

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

Cabeçalhos

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

Corpo da resposta

Depois de enviar a solicitação, você receberá a seguinte resposta. Continue sondando esse ponto de extremidade até que o parâmetro de status mude para "bem-sucedido".

{
  "result": {
    "modelLabel": "{MODEL-LABEL}",
    "trainingConfigVersion": "{TRAINING-CONFIG-VERSION}",
    "trainingMode": "{TRAINING-MODE}",
    "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": "xxxxx-xxxxx-xxxx-xxxxx-xxxx",
  "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, após treinar um modelo, você poderá examinar os detalhes da avaliação. Neste início rápido, você apenas implantará seu modelo e chamará a API de previsão para consultar os resultados.

Enviar trabalho de implantação

Crie uma solicitação PUT usando a URL, os cabeçalhos e o corpo JSON a seguir para começar a implantar um modelo de compreensão da linguagem coloquial.

URL da solicitação

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/deployments/{DEPLOYMENT-NAME}?api-version={API-VERSION}

Cabeçalhos

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

Corpo da solicitação

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

Depois de enviar sua solicitação de API, você receberá uma 202 resposta indicando êxito. Nos cabeçalhos de resposta, extraia o valor operation-location. A formatação ficará da seguinte maneira:

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

Use essa URL para obter o status do trabalho de implantação.

Obter status do trabalho de implantação

Ao enviar uma solicitação de implantação bem-sucedida, a URL completa da solicitação para verificar o status do trabalho (incluindo seu ponto de extremidade, nome do projeto e ID do trabalho) está contida no cabeçalho operation-location da resposta.

Use a solicitação GET a seguir para obter o status do trabalho de implantação. Substitua os valores do espaço reservado pelos seus.

URL da solicitação

{ENDPOINT}/language/authoring/analyze-conversations/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.

Corpo da resposta

Depois de enviar a solicitação, você receberá a seguinte resposta. Continue sondando esse ponto de extremidade até que o parâmetro de status mude para "bem-sucedido".

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

Modelo de consulta

Depois que o modelo for implantado, você poderá começar a usá-lo para fazer previsões por meio da API de previsão.

Uma vez que a implantação for bem-sucedida, você poderá começar a consultar seu modelo implantado para obter previsões.

Crie uma solicitação POST usando a URL, os cabeçalhos e o corpo JSON a seguir para começar a testar um modelo de compreensão da linguagem coloquial.

URL da solicitação

{ENDPOINT}/language/:analyze-conversations?api-version={API-VERSION}

Cabeçalhos

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

Corpo da solicitação

{
  "kind": "Conversation",
  "analysisInput": {
    "conversationItem": {
      "id": "1",
      "participantId": "1",
      "text": "Text 1"
    }
  },
  "parameters": {
    "projectName": "{PROJECT-NAME}",
    "deploymentName": "{DEPLOYMENT-NAME}",
    "stringIndexType": "TextElement_V8"
  }
}

Após enviar a solicitação, você receberá a seguinte resposta para a previsão

Corpo da resposta

{
  "kind": "ConversationResult",
  "result": {
    "query": "Text1",
    "prediction": {
      "topIntent": "inten1",
      "projectKind": "Conversation",
      "intents": [
        {
          "category": "intent1",
          "confidenceScore": 1
        },
        {
          "category": "intent2",
          "confidenceScore": 0
        },
        {
          "category": "intent3",
          "confidenceScore": 0
        }
      ],
      "entities": [
        {
          "category": "entity1",
          "text": "text1",
          "offset": 29,
          "length": 12,
          "confidenceScore": 1
        }
      ]
    }
  }
}

Resposta de API para um projeto de conversas

Em um projeto de conversas, você obterá previsões para suas intenções e entidades que estão presentes no seu projeto.

• As intenções e as entidades incluem uma pontuação de confiança entre 0,0 e 1,0 associada à confiança do modelo sobre a previsão de um determinado elemento em seu projeto.
• A principal intenção de pontuação está contida no próprio parâmetro.
• Somente as entidades previstas aparecerão em sua resposta.
• As entidades indicam:
  • O texto da entidade que foi extraído
  • O local de início indicado por um valor de deslocamento
  • O comprimento do texto da entidade indicado por um valor de comprimento

Limpar os recursos

Quando você não precisar mais do seu projeto, poderá excluí-lo usando as APIs.

Crie uma solicitação DELETE usando a URL, os cabeçalhos e o corpo JSON a seguir para excluir um projeto de compreensão da linguagem coloquial.

URL da solicitação

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

Cabeçalhos

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

Depois de enviar a solicitação da API, você receberá uma resposta 202 indicando êxito, o que significa que o projeto foi excluído.