Como usar recursos do Serviço de Linguagem de maneira assíncrona

  • Artigo

O Serviço de Linguagem permite que você envie solicitações de API de forma assíncrona, usando a API REST ou a biblioteca de clientes. Você também pode incluir vários recursos diferentes do Serviço de Linguagem em sua solicitação, a serem executados em seus dados ao mesmo tempo.

Atualmente, os seguintes recursos estão disponíveis para serem usados de forma assíncrona:

  • Vinculação de entidade
  • Resumo de documento
  • Resumo de conversa
  • Extração de frases-chave
  • Detecção de idioma
  • NER (Reconhecimento de Entidade Nomeada)
  • Detecção de conteúdo do cliente
  • Análise de sentimento e mineração de opiniões
  • Análise de Texto para integridade
  • PII (informações de identificação pessoal)

Ao enviar solicitações assíncronas, você incorrerá em encargos com base no número de registros de texto incluídos na solicitação para cada uso de recurso. Por exemplo, se você enviar um registro de texto para análise de sentimento e NER, ele será contado como envio de dois registros de texto e você será cobrado por ambos de acordo com o seu tipo de preço.

Enviar um trabalho assíncrono usando a API REST

Para enviar um trabalho assíncrono, examine a documentação de referência para o corpo JSON que você enviará na solicitação.

  1. Adicione seus documentos ao objeto analysisInput.
  2. No objeto tasks, inclua as operações que você deseja realizar em seus dados. Por exemplo, se você quisesse executar a análise de sentimento, incluiria o objeto SentimentAnalysisLROTask.
  3. Você pode, opcionalmente:
    1. Escolha uma versão do modelo específica, usada em seus dados.
    2. Inclua recursos adicionais do Serviço de Linguagem no objeto tasks a serem executados em seus dados ao mesmo tempo.

Depois de criar o corpo JSON para sua solicitação, adicione sua chave ao cabeçalho Ocp-Apim-Subscription-Key. Em seguida, envie sua solicitação de API para o ponto de extremidade de criação do trabalho. Por exemplo:

POST https://your-endpoint.cognitiveservices.azure.com/language/analyze-text/jobs?api-version=2022-05-01

Uma chamada bem-sucedida retornará um código de resposta 202. O operation-location no cabeçalho da resposta será a URL que você usará para recuperar os resultados da API. O valor será parecido com a seguinte URL:

GET {Endpoint}/language/analyze-text/jobs/12345678-1234-1234-1234-12345678?api-version=2022-05-01

Para obter o status e recuperar os resultados da solicitação, envie uma solicitação GET para a URL que você recebeu no cabeçalho operation-location da resposta da API anterior. Lembre-se de incluir sua chave no Ocp-Apim-Subscription-Key. A resposta incluirá os resultados da chamada à API.

Enviar solicitações de API assíncronas usando a biblioteca de clientes

Primeiro, certifique-se de ter a biblioteca de clientes instalada para o idioma de sua escolha. Para ver as etapas sobre como instalar a biblioteca de clientes, confira o artigo de início rápido do recurso que você deseja usar.

Posteriormente, use o objeto de cliente para enviar chamadas assíncronas para a API. As chamadas de método a serem usadas irão variar dependendo do idioma. Use os exemplos disponíveis e a documentação de referência para ajudá-lo a começar.

Disponibilidade de resultados

Ao usar esse recurso de forma assíncrona, os resultados da API ficam disponíveis por 24 horas a partir do momento em que a solicitação foi ingerida; isso é indicado na resposta. Após esse período de tempo, os resultados são limpos e não estão mais disponíveis para recuperação.

Detecção automática de idioma

Da versão 2022-07-01-preview da API REST em diante, você pode solicitar a detecção automática de idioma em seus documentos. Ao definir o parâmetro language como auto, o código do idioma detectado do texto será retornado como um valor de idioma na resposta. Essa detecção de idioma não incorrerá encargos extras para o seu recurso de idioma.

Limites de dados

Observação

  • Se você precisar analisar documentos maiores do que o limite permite, poderá dividir o texto em partes menores antes de enviá-los para a API.
  • Um documento é uma cadeia de caracteres de texto.

Você pode enviar até 125.000 caracteres em todos os documentos contidos na solicitação assíncrona, conforme medido por StringInfo.LengthInTextElements. Esse limite de caracteres é maior que o limite para solicitações síncronas para habilitar uma taxa de transferência mais alta.

Quando um documento dentro da API ultrapassa o limite de tamanho máximo de caracteres, ela rejeita a solicitação e retorna um erro 400 bad request.

Confira também