Guia de início rápido: compreensão de linguagem conversacional

  • Artigo

Use este artigo para começar a entender a linguagem conversacional usando o Language Studio e a API REST. Siga estes passos para experimentar um exemplo.

Pré-requisitos

Iniciar sessão no Language Studio

  1. Aceda ao Language Studio e inicie sessão com a sua conta do Azure.

  2. Na janela Escolha um recurso de idioma que aparece, localize sua assinatura do Azure e escolha seu recurso de idioma. Se não tiver um recurso, pode criar um novo.

    Detalhe da instância Valor obrigatório
    Subscrição do Azure A sua subscrição do Azure.
    Grupo de recursos do Azure Seu nome de grupo de recursos do Azure.
    Nome do recurso do Azure Seu nome de recurso do Azure.
    Localização Uma das regiões suportadas para o seu recurso Idioma. Por exemplo, "West US 2".
    Escalão de preço Um dos níveis de preços válidos para o seu recurso de idioma. Você pode usar a camada Gratuito (F0) para experimentar o serviço.

    A screenshot showing the resource selection screen in Language Studio.

Criar um projeto de compreensão de linguagem conversacional

Depois de selecionar um recurso de idioma, crie um projeto de compreensão de linguagem conversacional. 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 outras pessoas que tenham acesso ao recurso linguístico que está a ser utilizado.

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

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

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

  2. Isso levará você à página Projetos de compreensão de linguagem conversacional. Ao lado do botão Criar novo projeto, selecione Importar.

    A screenshot showing the conversation project page in Language Studio.

  3. Na janela apresentada, carregue o ficheiro JSON que pretende importar. Certifique-se de que o ficheiro segue o formato JSON suportado.

Quando o upload estiver concluído, você pousará na página de definição de esquema. Para esse início rápido, o esquema já está construído e os enunciados já são rotulados com intenções e entidades.

Preparar o modelo

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

Para treinar um modelo, você precisa começar um trabalho de treinamento. O resultado de um trabalho de treinamento bem-sucedido é o seu modelo treinado.

Para começar a treinar o seu modelo a partir do Language Studio:

  1. Selecione Modelo de trem 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 de 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, em seguida, 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 o treinamento padrão para treinamento mais rápido, mas ele só está disponível para inglês. Ou pode escolher a formação avançada, que é suportada para outras línguas e projetos multilingues, mas envolve tempos de formação mais longos. Saiba mais sobre os modos de preparação.

  5. Selecione um método de divisão de dados. Você pode escolher Dividir automaticamente o conjunto de testes dos dados de treinamento, onde o sistema dividirá seus enunciados entre os conjuntos de treinamento e teste, de acordo com as porcentagens especificadas. Ou você pode usar uma divisão manual de dados de treinamento e teste, essa opção só é habilitada se você tiver adicionado enunciados ao seu conjunto de teste quando rotulou seus enunciados.

  6. Selecione o botão Trem .

    A screenshot showing the training page in Language Studio.

  7. Selecione o ID do trabalho de treinamento na lista. Será exibido um painel onde você pode verificar o progresso do treinamento, status do trabalho e outros detalhes para este trabalho.

    Nota

    • Apenas trabalhos de formação concluídos com sucesso gerarão modelos.
    • O treinamento pode levar algum tempo entre alguns minutos e algumas horas com base na contagem de enunciados.
    • Só pode ter um trabalho de preparação em execução de cada vez. Você não pode iniciar outros trabalhos de treinamento dentro do 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 Selecionar aqui para alterar na página Iniciar um trabalho de treinamento e escolha uma versão anterior.

Implementar o modelo

Geralmente, depois de treinar um modelo, você revisaria seus detalhes de avaliação. 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.

Para implantar seu modelo a partir do Language Studio:

  1. Selecione Implantando um modelo no menu do lado esquerdo.

  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 nova 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.

    Nota

    A substituição de uma implantação existente não requer alterações na chamada da 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 o trabalho de implantação.

  6. Depois que a implantação for bem-sucedida, uma data de expiração aparecerá ao lado dela. A expiração da implantação é quando o modelo implantado não estará disponível para ser usado para previsão, o que normalmente acontece doze meses após a expiração de uma configuração de treinamento.

Testar modelo implantado

Para testar seus modelos implantados de dentro do Language Studio:

  1. Selecione Testando implantações no menu do lado esquerdo.

  2. Para projetos multilíngues, na lista suspensa Selecionar idioma do 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 declarações relacionadas a e-mail, você pode digitar Excluir este e-mail.

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

  6. Depois de executar o teste, você verá a resposta do modelo no resultado. Você pode visualizar os resultados na visualização de cartões de entidades ou visualizá-los no formato JSON.

Clean up resources (Limpar recursos)

Quando você não precisar mais do seu projeto, poderá excluí-lo usando o Language Studio. Selecione Projetos no menu de navegação esquerdo, selecione o projeto que deseja excluir e selecione Excluir no menu superior.

Pré-requisitos

Criar um novo recurso a partir do 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 que aparece, procure por Serviço de idioma

  4. Selecione Criar

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

    Detalhe da instância Valor obrigatório
    Região Uma das regiões suportadas para o seu recurso Idioma.
    Nome Nome obrigatório para o recurso Idioma
    Escalão de preço Um dos níveis de preços suportados para o seu recurso de idioma.

Obtenha suas chaves de recursos e ponto de extremidade

  1. Vá para a página de visão geral do recurso no portal do Azure.

  2. No menu do lado esquerdo, selecione Teclas 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 de CLU

Depois de criar um recurso de linguagem, crie um projeto de compreensão de linguagem conversacional. 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 outras pessoas que tenham acesso ao recurso linguístico que está a ser utilizado.

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

Acionar o trabalho de importação do projeto

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

URL do Pedido

Use a seguinte URL ao criar sua solicitação de API. Substitua os valores de espaço reservado por seus próprios valores.

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/:import?api-version={API-VERSION}
Marcador de Posição Valor Exemplo
{ENDPOINT} O ponto de extremidade para autenticar 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.

Key valor
Ocp-Apim-Subscription-Key A chave para o seu recurso. Usado para autenticar suas solicitações de API.

Corpo

O corpo JSON enviado é semelhante ao exemplo a seguir. Consulte 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 Marcador de Posição 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 especificando o código de idioma para os enunciados usados em seu projeto. Se o seu projeto for multilingue, escolha o código linguístico da maioria dos enunciados. en-us
multilingual true Um valor booleano que permite que você tenha documentos em vários idiomas em seu conjunto de dados. Quando o modelo é implantado, você pode consultá-lo em qualquer idioma suportado, incluindo idiomas que não estão incluídos nos documentos de treinamento. true
dataset {DATASET} Veja como treinar um modelo para obter informações sobre como dividir seus dados entre um conjunto de testes e treinamento. Os valores possíveis para este campo são Train e Test. Train

Após uma solicitação bem-sucedida, a resposta da API conterá um operation-location cabeçalho com uma URL que você pode usar para verificar o status do trabalho de importação. Está 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

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

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

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/import/jobs/{JOB-ID}?api-version={API-VERSION}
Marcador de Posição Valor Exemplo
{ENDPOINT} O ponto de extremidade para autenticar 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 localizar o status do 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 seu recurso. Usado para autenticar suas solicitações de API. {YOUR-PRIMARY-RESOURCE-KEY}

Corpo da resposta

Depois de enviar a solicitação, você receberá a seguinte resposta. Continue pesquisando este 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"
}

Comece a treinar o seu modelo

Normalmente, depois de criar um projeto, você deve criar enunciados de esquema e marcação. Para este início rápido, já importamos um projeto pronto com esquema construído e enunciados marcados.

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

URL do Pedido

Use a seguinte URL ao criar sua solicitação de API. Substitua os valores de espaço reservado por seus próprios valores.

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/:train?api-version={API-VERSION}
Marcador de Posição Valor Exemplo
{ENDPOINT} O ponto de extremidade para autenticar 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.

Key valor
Ocp-Apim-Subscription-Key A chave para o seu recurso. Usado para autenticar suas solicitações de API.

Corpo do pedido

Use o seguinte objeto em sua solicitação. O modelo será nomeado de acordo com o valor que você usa para o parâmetro quando o modelLabel treinamento for concluído.

{
  "modelLabel": "{MODEL-NAME}",
  "trainingMode": "{TRAINING-MODE}",
  "trainingConfigVersion": "{CONFIG-VERSION}",
  "evaluationOptions": {
    "kind": "percentage",
    "testingSplitPercentage": 20,
    "trainingSplitPercentage": 80
  }
}
Chave Marcador de Posição 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 mais recente do modelo é usada. 2022-05-01
trainingMode {TRAINING-MODE} O modo de treinamento a ser usado para treinamento. Os modos suportados são treinamento padrão, treinamento mais rápido, mas disponível apenas para inglês e treinamento avançado suportado para outros idiomas e projetos multilíngues, mas envolve tempos de treinamento mais longos. Saiba mais sobre os modos de preparação. standard
kind percentage Métodos de divisão. Os valores possíveis são percentage ou manual. Veja como treinar um modelo para obter mais informações. percentage
trainingSplitPercentage 80 Porcentagem dos dados marcados a serem incluídos no conjunto de treinamento. O valor recomendado é 80. 80
testingSplitPercentage 20 Porcentagem dos dados marcados a serem incluídos no conjunto de testes. O valor recomendado é 20. 20

Nota

O trainingSplitPercentage e só são necessários se Kind for definido como percentage e testingSplitPercentage a soma de ambas as percentagens deve ser igual a 100.

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

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

Você pode 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 pesquisando o status do trabalho de treinamento até que ele seja concluído com êxito.

Quando você envia 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 da operation-location resposta.

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

URL do Pedido

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/train/jobs/{JOB-ID}?api-version={API-VERSION}
Marcador de Posição Valor Exemplo
{YOUR-ENDPOINT} O ponto de extremidade para autenticar 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} O ID para localizar o status de treinamento do seu 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.

Key valor
Ocp-Apim-Subscription-Key A chave para o seu recurso. Usado para autenticar suas solicitações de API.

Organismo de resposta

Depois de enviar o pedido, obterá a seguinte resposta. Continue pesquisando este 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"
}
Key valor Exemplo
modelLabel O nome do modelo Model1
trainingConfigVersion A versão de configuração de treinamento. Por padrão, a versão mais recente é usada. 2022-05-01
trainingMode O modo de treino selecionado. standard
startDateTime O tempo de treinamento começou 2022-04-14T10:23:04.2598544Z
status O estatuto do trabalho de formação running
estimatedEndDateTime Tempo estimado para a conclusão do trabalho de formação 2022-04-14T10:29:38.2598544Z
jobId O seu ID de trabalho de formação xxxxx-xxxx-xxxx-xxxx-xxxxxxxxx
createdDateTime Data e hora de criação de emprego de formação 2022-04-14T10:22:42Z
lastUpdatedDateTime Data e hora da última atualização do trabalho de formação 2022-04-14T10:23:45Z
expirationDateTime Data e hora de expiração do trabalho de treinamento 2022-04-14T10:22:42Z

Implementar o modelo

Geralmente, depois de treinar um modelo, você revisaria seus detalhes de 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 seguinte URL, cabeçalhos e corpo JSON para começar a implantar um modelo de compreensão de linguagem conversacional.

URL do Pedido

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/deployments/{DEPLOYMENT-NAME}?api-version={API-VERSION}
Marcador de Posição Valor Exemplo
{ENDPOINT} O ponto de extremidade para autenticar 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 sua 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.

Key valor
Ocp-Apim-Subscription-Key A chave para o seu recurso. Usado para autenticar suas solicitações de API.

Corpo do Pedido

{
  "trainedModelLabel": "{MODEL-NAME}",
}
Chave Marcador de Posição Valor Exemplo
trainedModelLabel {MODEL-NAME} O nome do modelo que será atribuído à sua 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 sucesso. Nos cabeçalhos de resposta, extraia o operation-location valor. Será formatado da seguinte forma:

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

Você pode usar essa URL para obter o status do trabalho de implantação.

Obter o status do trabalho de implantação

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

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

URL do Pedido

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/deployments/{DEPLOYMENT-NAME}/jobs/{JOB-ID}?api-version={API-VERSION}
Marcador de Posição Valor Exemplo
{ENDPOINT} O ponto de extremidade para autenticar 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 sua implantação. Esse valor diferencia maiúsculas de minúsculas. staging
{JOB-ID} O ID para localizar o status de treinamento do seu 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.

Key valor
Ocp-Apim-Subscription-Key A chave para o seu recurso. Usado para autenticar suas solicitações de API.

Organismo de resposta

Depois de enviar a solicitação, você receberá a seguinte resposta. Continue pesquisando este 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.

Quando 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 seguinte URL, cabeçalhos e corpo JSON para começar a testar um modelo de compreensão de linguagem conversacional.

URL do Pedido

{ENDPOINT}/language/:analyze-conversations?api-version={API-VERSION}
Marcador de Posição Valor Exemplo
{ENDPOINT} O ponto de extremidade para autenticar 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.

Key valor
Ocp-Apim-Subscription-Key A chave para o seu recurso. Usado para autenticar suas solicitações de API.

Corpo do pedido

{
  "kind": "Conversation",
  "analysisInput": {
    "conversationItem": {
      "id": "1",
      "participantId": "1",
      "text": "Text 1"
    }
  },
  "parameters": {
    "projectName": "{PROJECT-NAME}",
    "deploymentName": "{DEPLOYMENT-NAME}",
    "stringIndexType": "TextElement_V8"
  }
}
Chave Marcador de Posição Valor Exemplo
participantId {JOB-NAME} "MyJobName
id {JOB-NAME} "MyJobName
text {TEST-UTTERANCE} O enunciado do qual você deseja prever sua 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

Depois de 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 da amostra Descrição
query "Leia o e-mail de Matt" O texto enviado para consulta.
topIntent "Ler" A intenção prevista com maior pontuação de confiança.
intenções [] Uma lista de todas as intenções que foram previstas para o texto da consulta, cada uma delas com uma pontuação de confiança.
entidades [] Matriz que contém a lista de entidades extraídas do texto da consulta.

Resposta da 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 em seu projeto.

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

Clean up resources (Limpar recursos)

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

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

URL do Pedido

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}?api-version={API-VERSION}
Marcador de Posição Valor Exemplo
{ENDPOINT} O ponto de extremidade para autenticar 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.

Key valor
Ocp-Apim-Subscription-Key A chave para o seu recurso. Usado para autenticar suas solicitações de API.

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

Próximos passos