Exemplo: Detetar linguagem com análise de textoExample: Detect language with Text Analytics

A funcionalidade de Deteção de Idiomas do Azure Text Analytics REST API avalia a entrada de texto de cada documento e devolve os identificadores linguísticos com uma pontuação que indique a força da análise.The Language Detection feature of the Azure Text Analytics REST API evaluates text input for each document and returns language identifiers with a score that indicates the strength of the analysis.

Esta funcionalidade é útil para arquivos de conteúdo que recolhem texto arbitrário quando o idioma é desconhecido.This capability is useful for content stores that collect arbitrary text, where language is unknown. Pode analisar os resultados desta análise para determinar o idioma que é utilizado no documento de entrada.You can parse the results of this analysis to determine which language is used in the input document. A resposta também devolve uma pontuação que reflete a confiança do modelo.The response also returns a score that reflects the confidence of the model. O valor da pontuação é entre 0 e 1.The score value is between 0 and 1.

A funcionalidade de Deteção de Idiomas pode detetar uma vasta gama de línguas, variantes, dialetos e algumas línguas regionais ou culturais.The Language Detection feature can detect a wide range of languages, variants, dialects, and some regional or cultural languages. A lista exata de idiomas para esta funcionalidade não é publicada.The exact list of languages for this feature isn't published.

Se tiver conteúdo expresso num idioma menos utilizado, pode experimentar a funcionalidade de Deteção de Idiomas para ver se devolve um código.If you have content expressed in a less frequently used language, you can try the Language Detection feature to see if it returns a code. A resposta para línguas que não podem ser detetadas unknown é.The response for languages that can't be detected is unknown.

Dica

O Text Analytics também fornece uma imagem de recipiente Docker baseada em Linux para deteção de idiomas, para que possa instalar e executar o recipiente Text Analytics perto dos seus dados.Text Analytics also provides a Linux-based Docker container image for language detection, so you can install and run the Text Analytics container close to your data.

PreparaçãoPreparation

Importante

Texto Analytics API v3 não está disponível nas seguintes regiões: China Norte 2, China Leste.Text Analytics API v3 is not available in the following regions: China North 2, China East.

Você deve ter documentos JSON neste formato: ID e texto.You must have JSON documents in this format: ID and text.

O tamanho do documento deve ser inferior a 5.120 caracteres por documento.The document size must be under 5,120 characters per document. Você pode ter até 1.000 itens (IDs) por coleção.You can have up to 1,000 items (IDs) per collection. A coleção é enviada no corpo do pedido.The collection is submitted in the body of the request. A amostra a seguir é um exemplo de conteúdo que pode submeter para deteção de idiomas:The following sample is an example of content you might submit for language detection:

    {
        "documents": [
            {
                "id": "1",
                "text": "This document is in English."
            },
            {
                "id": "2",
                "text": "Este documento está en inglés."
            },
            {
                "id": "3",
                "text": "Ce document est en anglais."
            },
            {
                "id": "4",
                "text": "本文件为英文"
            },
            {
                "id": "5",
                "text": "Этот документ на английском языке."
            }
        ]
    }

Passo 1: estruturar o pedidoStep 1: Structure the request

Para obter mais informações sobre a definição de pedido, consulte a API de Análise de Texto.For more information on request definition, see Call the Text Analytics API. Os seguintes pontos são novamente apresentados para sua comodidade:The following points are restated for convenience:

  • Crie um pedido POST.Create a POST request. Para rever a documentação da API para este pedido, consulte a API de Deteção de Idiomas.To review the API documentation for this request, see the Language Detection API.

  • Defina o ponto de final HTTP para a deteção de idioma.Set the HTTP endpoint for language detection. Utilize um recurso text analytics no Azure ou um recipiente de análise de textoinstantâneo .Use either a Text Analytics resource on Azure or an instantiated Text Analytics container. Deve incluir /text/analytics/v3.0/languages na URL.You must include /text/analytics/v3.0/languages in the URL. Por exemplo: https://<your-custom-subdomain>.cognitiveservices.azure.com/text/analytics/v3.0/languages.For example: https://<your-custom-subdomain>.cognitiveservices.azure.com/text/analytics/v3.0/languages.

  • Desa estade um cabeçalho de pedido para incluir a chave de acesso para operações de Análise de Texto.Set a request header to include the access key for Text Analytics operations.

  • No corpo do pedido, forneça a coleção de documentos JSON que preparou para esta análise.In the request body, provide the JSON documents collection you prepared for this analysis.

Dica

Utilize o Postman ou abra a consola de teste da API na documentação para estruturar um pedido e publicá-lo no serviço.Use Postman or open the API testing console in the documentation to structure a request and POST it to the service.

Passo 2: POST o pedidoStep 2: POST the request

A análise é realizada aquando da receção do pedido.Analysis is performed upon receipt of the request. Para obter informações sobre o tamanho e o número de pedidos que pode enviar por minuto e segundo, consulte a secção limite de dados na visão geral.For information on the size and number of requests you can send per minute and second, see the data limits section in the overview.

Lembre-se de que o serviço não tem estado.Recall that the service is stateless. Não são armazenados dados na sua conta.No data is stored in your account. Os resultados são devolvidos imediatamente na resposta.Results are returned immediately in the response.

Passo 3: Ver os resultadosStep 3: View the results

Todos os pedidos post retornam uma resposta formatada por JSON com os IDs e propriedades detetadas.All POST requests return a JSON-formatted response with the IDs and detected properties.

O resultado é devolvido imediatamente.Output is returned immediately. Pode transmitir os resultados para uma aplicação que aceite o JSON ou guarde a saída para um ficheiro no sistema local.You can stream the results to an application that accepts JSON or save the output to a file on the local system. Em seguida, importe a saída para uma aplicação que pode usar para ordenar, pesquisar e manipular os dados.Then, import the output into an application that you can use to sort, search, and manipulate the data.

Os resultados do pedido de exemplo deverão assemelhar-se ao seguinte JSON.Results for the example request should look like the following JSON. Note que é um documento com vários itens.Notice that it's one document with multiple items. Os resultados são apresentados em inglês.Output is in English. Os identificadores de idioma incluem um nome amigável e um código de idioma no formato ISO 639-1.Language identifiers include a friendly name and a language code in ISO 639-1 format.

Uma pontuação positiva igual a 1,0 expressa o nível de confiança mais elevado possível da análise.A positive score of 1.0 expresses the highest possible confidence level of the analysis.

{
    "documents": [
        {
            "id": "1",
            "detectedLanguage": {
                "name": "English",
                "iso6391Name": "en",
                "confidenceScore": 1.0
            },
            "warnings": []
        },
        {
            "id": "2",
            "detectedLanguage": {
                "name": "Spanish",
                "iso6391Name": "es",
                "confidenceScore": 1.0
            },
            "warnings": []
        },
        {
            "id": "3",
            "detectedLanguage": {
                "name": "French",
                "iso6391Name": "fr",
                "confidenceScore": 1.0
            },
            "warnings": []
        },
        {
            "id": "4",
            "detectedLanguage": {
                "name": "Chinese_Simplified",
                "iso6391Name": "zh_chs",
                "confidenceScore": 1.0
            },
            "warnings": []
        },
        {
            "id": "5",
            "detectedLanguage": {
                "name": "Russian",
                "iso6391Name": "ru",
                "confidenceScore": 1.0
            },
            "warnings": []
        }
    ],
    "errors": [],
    "modelVersion": "2019-10-01"
}

Conteúdo ambíguoAmbiguous content

Em alguns casos, pode ser difícil desambiguar línguas com base na entrada.In some cases it may be hard to disambiguate languages based on the input. Pode utilizar o countryHint parâmetro para especificar um código país/região de 2 letras.You can use the countryHint parameter to specify a 2-letter country/region code. Por predefinição, a API está a usar os "EUA" como país padrãoHint, para remover este comportamento pode redefinir este parâmetro definindo este valor para cadeia vazia countryHint = "" .By default the API is using the "US" as the default countryHint, to remove this behavior you can reset this parameter by setting this value to empty string countryHint = "" .

Por exemplo, "Impossível" é comum tanto ao inglês como ao francês e, se for dado com um contexto limitado, a resposta basear-se-á na sugestão do país/região dos EUA.For example, "Impossible" is common to both English and French and if given with limited context the response will be based on the "US" country/region hint. Se o texto tiver origem em França, este país poderá ser dado como sugestão.If the origin of the text is known to be coming from France that can be given as a hint.

EntradaInput

    {
        "documents": [
            {
                "id": "1",
                "text": "impossible"
            },
            {
                "id": "2",
                "text": "impossible",
                "countryHint": "fr"
            }
        ]
    }

O serviço tem agora um contexto adicional para fazer um melhor julgamento:The service now has additional context to make a better judgment:

SaídaOutput

    {
        "documents": [
            {
                "id": "1",
                "detectedLanguages": [
                    {
                        "name": "English",
                        "iso6391Name": "en",
                        "confidenceScore": 1
                    }
                ]
            },
            {
                "id": "2",
                "detectedLanguages": [
                    {
                        "name": "French",
                        "iso6391Name": "fr",
                        "confidenceScore": 1
                    }
                ]
            }
        ],
        "errors": []
    }

Se o analisador não puder analisar a entrada, retorna (Unknown) .If the analyzer can't parse the input, it returns (Unknown). Um exemplo é se submeter um bloco de texto que consiste apenas em algarismos árabes.An example is if you submit a text block that consists solely of Arabic numerals.

    {
        "id": "5",
        "detectedLanguages": [
            {
                "name": "(Unknown)",
                "iso6391Name": "(Unknown)",
                "confidenceScore": "NaN"
            }
        ]
    }

Conteúdo em língua mistaMixed-language content

O conteúdo em linguagem mista dentro do mesmo documento devolve a língua com a maior representação do conteúdo, mas com uma classificação positiva mais baixa.Mixed-language content within the same document returns the language with the largest representation in the content, but with a lower positive rating. O rating reflete a força marginal da avaliação.The rating reflects the marginal strength of the assessment. No seguinte exemplo, a entrada é uma mistura de inglês, espanhol e francês.In the following example, input is a blend of English, Spanish, and French. O analisador conta carateres em cada segmento para determinar o idioma predominante.The analyzer counts characters in each segment to determine the predominant language.

EntradaInput

    {
      "documents": [
        {
          "id": "1",
          "text": "Hello, I would like to take a class at your University. ¿Se ofrecen clases en español? Es mi primera lengua y más fácil para escribir. Que diriez-vous des cours en français?"
        }
      ]
    }

SaídaOutput

A produção resultante consiste na língua predominante, com uma pontuação inferior a 1.0, o que indica um nível de confiança mais fraco.The resulting output consists of the predominant language, with a score of less than 1.0, which indicates a weaker level of confidence.

    {
      "documents": [
        {
          "id": "1",
          "detectedLanguages": [
            {
              "name": "Spanish",
              "iso6391Name": "es",
              "confidencescore": 0.94
            }
          ]
        }
      ],
      "errors": []
    }

ResumoSummary

Neste artigo, aprendeu conceitos e fluxo de trabalho para deteção de linguagem utilizando Text Analytics em Azure Cognitive Services.In this article, you learned concepts and workflow for language detection by using Text Analytics in Azure Cognitive Services. Foram explicados e demonstrados os seguintes pontos:The following points were explained and demonstrated:

  • A deteção de linguagens está disponível para uma vasta gama de línguas, variantes, dialetos e algumas línguas regionais ou culturais.Language detection is available for a wide range of languages, variants, dialects, and some regional or cultural languages.
  • Os documentos JSON no órgão de pedido incluem uma identificação e texto.JSON documents in the request body include an ID and text.
  • O pedido do POST é para um /languages ponto final usando uma chave de acesso personalizada e um ponto final válido para a sua subscrição.The POST request is to a /languages endpoint by using a personalized access key and an endpoint that's valid for your subscription.
  • A saída de resposta consiste em identificadores de linguagem para cada documento ID.Response output consists of language identifiers for each document ID. A saída pode ser transmitida para qualquer app que aceite o JSON.The output can be streamed to any app that accepts JSON. As aplicações de exemplo incluem Excel e Power BI, para citar alguns.Example apps include Excel and Power BI, to name a few.

Consulte tambémSee also