Como extrair entidades de texto com o Azure AI Language

João Barros 12 de July de 2026 5 min de leitura

Extrair entidades de texto — nomes de pessoas, organizações, locais, datas e quantidades — é uma das formas mais rápidas de transformar comentários, emails ou descrições em dados estruturados. Com o Azure AI Language, essa extração faz-se com um recurso no portal e poucas linhas de Python, sem treinar qualquer modelo.

Pré-requisitos

Uma subscrição Azure ativa.
Permissões para criar um recurso Language (Azure AI services) no portal.
Python 3.8 ou superior instalado.
Noções básicas de Python (variáveis, ciclos for, listas).

Passo 1: Criar o recurso Language no portal Azure

No portal do Azure, procure por Language e crie um recurso do Language service. Escolha a subscrição, um grupo de recursos, a região mais próxima dos seus utilizadores e um escalão de preço — o escalão gratuito, quando disponível, é suficiente para aprender.

Depois de o recurso ficar criado, abra-o e vá a Keys and Endpoint. Copie uma das chaves e o endpoint: são os dois valores de que precisa para autenticar.

Passo 2: Guardar a chave e o endpoint em variáveis de ambiente

Nunca escreva a chave dentro do código. Guarde-a em variáveis de ambiente para não a expor em repositórios ou capturas de ecrã.

REM Windows (PowerShell ou CMD)
setx LANGUAGE_KEY "a-sua-chave"
setx LANGUAGE_ENDPOINT "https://o-seu-recurso.cognitiveservices.azure.com/"

# Linux ou macOS
export LANGUAGE_KEY="a-sua-chave"
export LANGUAGE_ENDPOINT="https://o-seu-recurso.cognitiveservices.azure.com/"

No Windows, feche e reabra o terminal depois do setx para as variáveis ficarem visíveis.

Passo 3: Instalar o SDK

O SDK oficial para Python chama-se azure-ai-textanalytics e é o que dá acesso ao reconhecimento de entidades.

pip install azure-ai-textanalytics

Passo 4: Autenticar e criar o cliente

O cliente precisa apenas do endpoint e da chave. Este bloco é a base de todos os exemplos seguintes.

import os
from azure.core.credentials import AzureKeyCredential
from azure.ai.textanalytics import TextAnalyticsClient

endpoint = os.environ["LANGUAGE_ENDPOINT"]
key = os.environ["LANGUAGE_KEY"]

client = TextAnalyticsClient(
    endpoint=endpoint,
    credential=AzureKeyCredential(key)
)

Passo 5: Extrair entidades de um texto

O método recognize_entities recebe uma lista de documentos (strings) e devolve, para cada um, as entidades encontradas. Repare no parâmetro language: indicar o idioma correto melhora bastante a qualidade do resultado.

documentos = [
    "A Maria Silva comprou 3 licenças do Power BI em Lisboa por 500 euros."
]

resultado = client.recognize_entities(documents=documentos, language="pt")

for doc in resultado:
    if doc.is_error:
        print("Erro:", doc.error.code, doc.error.message)
        continue
    for entidade in doc.entities:
        print(entidade.text, "|", entidade.category, "|",
              entidade.subcategory, "|", round(entidade.confidence_score, 2))

Cada entidade traz três informações úteis: o texto detetado, a categoria (por exemplo Person, Location, Quantity, DateTime, Organization), uma eventual subcategoria e um grau de confiança entre 0 e 1. É este último valor que lhe permite decidir em que resultados confiar.

Passo 6: Processar vários documentos e filtrar por confiança

Na prática, raramente analisamos uma frase isolada. Envie os textos em lote e junte tudo numa tabela, para depois filtrar as entidades com confiança baixa.

import pandas as pd

documentos = [
    "A Maria Silva comprou 3 licenças do Power BI em Lisboa por 500 euros.",
    "O contrato com a Contoso termina a 31 de dezembro.",
    "Enviámos o relatório ao João Barros na terça-feira."
]

resultado = client.recognize_entities(documents=documentos, language="pt")

linhas = []
for i, doc in enumerate(resultado):
    if doc.is_error:
        print("Documento", i, "falhou:", doc.error.code)
        continue
    for e in doc.entities:
        linhas.append({
            "documento": i,
            "texto": e.text,
            "categoria": e.category,
            "subcategoria": e.subcategory,
            "confianca": e.confidence_score
        })

df = pd.DataFrame(linhas)
df_fiavel = df[df["confianca"] >= 0.8]
print(df_fiavel)

O serviço tem um limite máximo de documentos por chamada, por isso, se tiver milhares de textos, divida a lista em blocos pequenos e faça uma chamada por bloco.

Passo 7: Resolver os erros mais comuns

401 Unauthorized: a chave está errada ou foi regenerada. Copie-a outra vez de Keys and Endpoint.
404 Not Found: o endpoint está incompleto. Deve terminar com uma barra e corresponder ao recurso e à região certos.
Poucas entidades detetadas: verifique o código de idioma. Enviar texto em português com language="en" degrada muito o resultado.
InvalidDocumentBatch: enviou documentos a mais (ou demasiado longos) numa só chamada. Reduza o tamanho do lote.

Verificar o resultado

Execute o script com a frase de exemplo. Deve ver a Maria Silva reconhecida como Person, Lisboa como Location, "3" como Quantity e "500 euros" como Quantity com subcategoria de moeda. Se a lista vier vazia, imprima doc.is_error e doc.error.message: quase sempre é a chave, o endpoint ou o idioma. Um bom teste final é passar um texto real do seu negócio e confirmar se as entidades que lhe interessam aparecem com confiança acima de 0,8.

Conclusão

Com um recurso Language e menos de 20 linhas de Python já consegue transformar texto livre em entidades estruturadas, prontas para carregar num Lakehouse ou num modelo de Power BI. O passo seguinte natural é combinar isto com a deteção de informação pessoal (PII) para anonimizar dados antes da análise, ou treinar um modelo de NER personalizado quando as categorias predefinidas não chegarem. Que entidades do seu próprio negócio — códigos de produto, números de contrato — gostaria de ensinar ao modelo?