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

Use este artigo para ver uma introdução à compreensão da linguagem coloquial usando o Language Studio e a API REST. Siga estas etapas para testar um exemplo.

Pré-requisitos

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.

    A screenshot showing the resource selection screen in Language Studio.

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.

    A screenshot showing the location of Custom Language Understanding in the Language Studio landing page.

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

    A screenshot showing the conversation project page in Language Studio.

  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.

    A screenshot showing the training page in Language Studio.

  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.

    A screenshot showing the model deployment button in Language Studio.

  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.

    A screenshot showing the screen for adding a new deployment in Language Studio.

  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

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

    A screenshot showing the key and endpoint page in the Azure portal

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}
Espaço reservado Valor Exemplo
{ENDPOINT} O ponto de extremidade para autenticação de sua solicitação de API. https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME} O nome do seu projeto. Esse valor diferencia maiúsculas de minúsculas e deve corresponder ao nome do projeto no arquivo JSON que você está importando. EmailAppDemo
{API-VERSION} A versão da API que você está chamando. 2023-04-01

Cabeçalhos

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

Chave Valor
Ocp-Apim-Subscription-Key A chave para o recurso. Usado para autenticação de suas solicitações de API.

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

Chave Espaço reservado Valor Exemplo
{API-VERSION} A versão da API que você está chamando. 2023-04-01
projectName {PROJECT-NAME} O nome do seu projeto. Esse valor diferencia maiúsculas de minúsculas. EmailAppDemo
language {LANGUAGE-CODE} Uma cadeia de caracteres que especifica o código de idioma dos enunciados usados no projeto. Se for um projeto multilíngue, escolha o código de idioma da maioria dos enunciados. en-us
multilingual true Um valor booliano que permite que você tenha documentos em vários idiomas em seu conjunto de dados. Quando seu modelo for implantado, você poderá consultar o modelo em qualquer idioma com suporte, incluindo os idiomas que não estão incluídos em seus documentos de treinamento. true
dataset {DATASET} Confira como treinar um modelo para saber como dividir seus dados entre um conjunto de testes e um de treinamento. Os valores possíveis para esse campo são Train e Test. Train

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}
Espaço reservado Valor Exemplo
{ENDPOINT} O ponto de extremidade para autenticação de sua solicitação de API. https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME} O nome do seu projeto. Esse valor diferencia maiúsculas de minúsculas. myProject
{JOB-ID} A ID para encontrar o status do seu trabalho de importação. xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx
{API-VERSION} A versão da API que você está chamando. 2023-04-01

Cabeçalhos

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

Chave Descrição Valor
Ocp-Apim-Subscription-Key A chave para o recurso. Usado para autenticação de suas solicitações de API. {YOUR-PRIMARY-RESOURCE-KEY}

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}
Espaço reservado Valor Exemplo
{ENDPOINT} O ponto de extremidade para autenticação de sua solicitação de API. https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME} O nome do seu projeto. Esse valor diferencia maiúsculas de minúsculas. EmailApp
{API-VERSION} A versão da API que você está chamando. 2023-04-01

Cabeçalhos

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

Chave Valor
Ocp-Apim-Subscription-Key A chave para o recurso. Usado para autenticação de suas solicitações de API.

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
  }
}
Chave Espaço reservado Valor Exemplo
modelLabel {MODEL-NAME} O nome do seu Modelo. Model1
trainingConfigVersion {CONFIG-VERSION} A versão do modelo de configuração de treinamento. Por padrão, a versão do modelo mais recente do modelo é usada. 2022-05-01
trainingMode {TRAINING-MODE} O modo de treinamento a ser usado para o treinamento. Os modos com suporte são Treinamento padrão: treinamento mais rápido, mas disponível apenas em inglês; e Treinamento avançado: com suporte para outros idiomas e projetos multilíngues, mas envolve tempos de treinamento mais longos. Saiba mais sobre os modos de treinamento. standard
kind percentage Métodos de divisão. Os valores possíveis são percentage ou manual. Confira como treinar um modelo para obter mais informações. percentage
trainingSplitPercentage 80 Porcentual dos dados marcados a serem incluídos no conjunto de treinamentos. O valor recomendado é 80. 80
testingSplitPercentage 20 Porcentual dos dados marcados a serem incluídos no conjunto de teste. O valor recomendado é 20. 20

Observação

trainingSplitPercentage e testingSplitPercentage serão necessários somente se Kind for definido como percentage, sendo que a soma de ambos os percentuais deverá ser igual a 100.

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}
Espaço reservado Valor Exemplo
{YOUR-ENDPOINT} O ponto de extremidade para autenticação de sua solicitação de API. https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME} O nome do seu projeto. Esse valor diferencia maiúsculas de minúsculas. EmailApp
{JOB-ID} A ID para localização do status de treinamento do modelo. xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx
{API-VERSION} A versão da API que você está chamando. 2023-04-01

Cabeçalhos

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

Chave Valor
Ocp-Apim-Subscription-Key A chave para o recurso. Usado para autenticação de suas solicitações de API.

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"
}
Chave Valor Exemplo
modelLabel O nome do modelo Model1
trainingConfigVersion A versão da configuração de treinamento. Por padrão, a versão mais recente é usada. 2022-05-01
trainingMode Seu modo de treinamento selecionado. standard
startDateTime A hora de início do treinamento 2022-04-14T10:23:04.2598544Z
status O status do trabalho de treinamento running
estimatedEndDateTime Tempo estimado para o término do trabalho de treinamento 2022-04-14T10:29:38.2598544Z
jobId ID do trabalho de treinamento xxxxx-xxxx-xxxx-xxxx-xxxxxxxxx
createdDateTime Data e hora de criação do trabalho de treinamento 2022-04-14T10:22:42Z
lastUpdatedDateTime Data e hora da última atualização do trabalho de treinamento 2022-04-14T10:23:45Z
expirationDateTime Data e hora de validade do trabalho de treinamento 2022-04-14T10:22:42Z

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}
Espaço reservado Valor Exemplo
{ENDPOINT} O ponto de extremidade para autenticação de sua solicitação de API. https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME} O nome do seu projeto. Esse valor diferencia maiúsculas de minúsculas. myProject
{DEPLOYMENT-NAME} O nome da implantação. Esse valor diferencia maiúsculas de minúsculas. staging
{API-VERSION} A versão da API que você está chamando. 2023-04-01

Cabeçalhos

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

Chave Valor
Ocp-Apim-Subscription-Key A chave para o recurso. Usado para autenticação de suas solicitações de API.

Corpo da solicitação

{
  "trainedModelLabel": "{MODEL-NAME}",
}
Chave Espaço reservado Valor Exemplo
trainedModelLabel {MODEL-NAME} O nome do modelo que será atribuído à implantação. Você só pode atribuir modelos treinados com sucesso. Esse valor diferencia maiúsculas de minúsculas. myModel

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}
Espaço reservado Valor Exemplo
{ENDPOINT} O ponto de extremidade para autenticação de sua solicitação de API. https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME} O nome do seu projeto. Esse valor diferencia maiúsculas de minúsculas. myProject
{DEPLOYMENT-NAME} O nome da implantação. Esse valor diferencia maiúsculas de minúsculas. staging
{JOB-ID} A ID para localização do status de treinamento do modelo. xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx
{API-VERSION} A versão da API que você está chamando. 2023-04-01

Cabeçalhos

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

Chave Valor
Ocp-Apim-Subscription-Key A chave para o recurso. Usado para autenticação de suas solicitações de API.

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}
Espaço reservado Valor Exemplo
{ENDPOINT} O ponto de extremidade para autenticação de sua solicitação de API. https://<your-custom-subdomain>.cognitiveservices.azure.com
{API-VERSION} A versão da API que você está chamando. 2023-04-01

Cabeçalhos

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

Chave Valor
Ocp-Apim-Subscription-Key A chave para o recurso. Usado para autenticação de suas solicitações de API.

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"
  }
}
Chave Espaço reservado Valor Exemplo
participantId {JOB-NAME} "MyJobName
id {JOB-NAME} "MyJobName
text {TEST-UTTERANCE} O enunciado do qual você deseja prever a intenção e extrair entidades. "Read Matt's email
projectName {PROJECT-NAME} O nome do seu projeto. Esse valor diferencia maiúsculas de minúsculas. myProject
deploymentName {DEPLOYMENT-NAME} O nome da sua implantação. Esse valor diferencia maiúsculas de minúsculas. staging

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
        }
      ]
    }
  }
}
Chave Valor de exemplo Descrição
Consulta "Ler o email do Marcos" o texto enviado para a consulta.
topIntent "Ler" A intenção prevista com a maior pontuação de confiança.
intenções [] Uma lista de todas as intenções previstas para o texto da consulta, cada qual com uma pontuação de confiança.
entidades [] matriz que contém a lista de entidades extraídas do texto da consulta.

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}
Espaço reservado Valor Exemplo
{ENDPOINT} O ponto de extremidade para autenticação de sua solicitação de API. https://<your-custom-subdomain>.cognitiveservices.azure.com
{PROJECT-NAME} O nome do seu projeto. Esse valor diferencia maiúsculas de minúsculas. myProject
{API-VERSION} A versão da API que você está chamando. 2023-04-01

Cabeçalhos

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

Chave Valor
Ocp-Apim-Subscription-Key A chave para o recurso. Usado para autenticação de suas solicitações de API.

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

Próximas etapas