Como utilizar as funcionalidades do Serviço de idiomas de forma assíncrona

  • Artigo

O serviço Idioma permite-lhe enviar pedidos de API de forma assíncrona, utilizando a API REST ou a biblioteca de cliente. Também pode incluir várias funcionalidades do Serviço de idiomas diferentes no seu pedido, a serem executadas nos seus dados ao mesmo tempo.

Atualmente, as seguintes funcionalidades estão disponíveis para serem utilizadas de forma assíncrona:

  • Associação de entidades
  • Resumo de documentos
  • Resumo de conversação
  • Extração de expressões-chave
  • Deteção de idioma
  • Reconhecimento de Entidades Nomeadas (NER)
  • Deteção de conteúdo do cliente
  • Análise de sentimentos e extração de opiniões
  • Análise de Texto para a saúde
  • Informações pessoais identificáveis (PII)

Quando envia pedidos assíncronos, incorrerá em custos com base no número de registos de texto que inclui no seu pedido, para cada utilização de funcionalidades. Por exemplo, se enviar um registo de texto para análise de sentimentos e NER, este será contabilizado como o envio de dois registos de texto e ser-lhe-á cobrado ambos de acordo com o seu escalão de preço.

Submeter uma tarefa assíncrona com a API REST

Para submeter uma tarefa assíncrona, reveja a documentação de referência do corpo JSON que enviará no seu pedido.

  1. Adicione os seus documentos ao analysisInput objeto.
  2. tasks No objeto, inclua as operações que pretende efetuar nos seus dados. Por exemplo, se quisesse efetuar a análise de sentimentos, incluiria o SentimentAnalysisLROTask objeto.
  3. Opcionalmente, pode:
    1. Escolha uma versão específica do modelo utilizado nos seus dados.
    2. Inclua funcionalidades adicionais do Serviço de idiomas no tasks objeto, a serem executadas nos seus dados ao mesmo tempo.

Depois de criar o corpo JSON para o pedido, adicione a chave ao Ocp-Apim-Subscription-Key cabeçalho. Em seguida, envie o pedido da API para o ponto final de criação de tarefas. Por exemplo:

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

Uma chamada bem-sucedida devolverá um código de resposta 202. No operation-location cabeçalho de resposta estará o URL que irá utilizar para obter os resultados da API. O valor terá um aspeto semelhante ao seguinte URL:

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

Para obter o estado e obter os resultados do pedido, envie um pedido GET para o URL que recebeu no operation-location cabeçalho da resposta da API anterior. Lembre-se de incluir a sua chave no Ocp-Apim-Subscription-Key. A resposta incluirá os resultados da chamada à API.

Enviar pedidos de API assíncronos com a biblioteca de cliente

Primeiro, certifique-se de que tem a biblioteca de cliente instalada para o seu idioma à sua escolha. Para obter os passos sobre como instalar a biblioteca de cliente, veja o artigo de início rápido da funcionalidade que pretende utilizar.

Posteriormente, utilize o objeto de cliente para enviar chamadas assíncronas para a API. As chamadas de método a utilizar variam consoante o seu idioma. Utilize os exemplos disponíveis e a documentação de referência para o ajudar a começar.

Disponibilidade de resultados

Ao utilizar esta funcionalidade de forma assíncrona, os resultados da API estão disponíveis durante 24 horas a partir do momento em que o pedido foi ingerido e são indicados na resposta. Após este período de tempo, os resultados são removidos e já não estão disponíveis para obtenção.

Deteção automática de idioma

A partir da versão 2022-07-01-preview da API REST, pode pedir a deteção automática de idioma nos seus documentos. Ao definir o language parâmetro como auto, o código de idioma detetado do texto será devolvido como um valor de idioma na resposta. Esta deteção de idioma não irá incorrer em custos adicionais para o recurso de Idioma.

Limites de dados

Nota

  • Se precisar de analisar documentos maiores do que o limite permitido, pode dividir o texto em segmentos de texto mais pequenos antes de os enviar para a API.
  • Um documento é uma única cadeia de carateres de texto.

Pode enviar até 125 000 carateres em todos os documentos contidos no pedido assíncrono, conforme medido por StringInfo.LengthInTextElements. Este limite de carateres é superior ao limite de pedidos síncronos, para permitir um débito mais elevado.

Se um documento exceder o limite de carateres, a API rejeitará todo o pedido e devolverá um 400 bad request erro se algum documento no mesmo exceder o tamanho máximo.

Ver também