Cómo extraer entidades de texto con Azure AI Language

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

Extraer entidades de texto — personas, organizaciones, lugares, fechas y cantidades — es una de las formas más rápidas de convertir comentarios, correos o descripciones libres en datos estructurados. Con Azure AI Language se hace con un recurso en el portal y unas pocas líneas de Python, sin entrenar ningún modelo.

Requisitos previos

Una suscripción de Azure activa.
Permisos para crear un recurso Language (Azure AI services) en el portal.
Python 3.8 o superior instalado.
Conocimientos básicos de Python (variables, bucles for, listas).

Paso 1: Crear el recurso Language en el portal de Azure

En el portal de Azure, busque Language y cree un recurso del Language service. Elija la suscripción, un grupo de recursos, la región más cercana a sus usuarios y un nivel de precios — el nivel gratuito, cuando esté disponible, es suficiente para aprender.

Una vez creado el recurso, ábralo y vaya a Keys and Endpoint. Copie una de las claves y el endpoint: son los dos valores que necesita para autenticarse.

Paso 2: Guardar la clave y el endpoint en variables de entorno

Nunca escriba la clave dentro del código. Guárdela en variables de entorno para no exponerla en repositorios ni en capturas de pantalla.

REM Windows (PowerShell o CMD)
setx LANGUAGE_KEY "su-clave"
setx LANGUAGE_ENDPOINT "https://su-recurso.cognitiveservices.azure.com/"

# Linux o macOS
export LANGUAGE_KEY="su-clave"
export LANGUAGE_ENDPOINT="https://su-recurso.cognitiveservices.azure.com/"

En Windows, cierre y vuelva a abrir el terminal después del setx para que las variables sean visibles.

Paso 3: Instalar el SDK

El SDK oficial para Python se llama azure-ai-textanalytics y es el que da acceso al reconocimiento de entidades.

pip install azure-ai-textanalytics

Paso 4: Autenticarse y crear el cliente

El cliente solo necesita el endpoint y la clave. Este bloque es la base de todos los ejemplos siguientes.

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)
)

Paso 5: Extraer las entidades de un texto

El método recognize_entities recibe una lista de documentos (cadenas) y devuelve, para cada uno, las entidades encontradas. Fíjese en el parámetro language: indicar el idioma correcto mejora bastante la calidad del resultado.

documentos = [
    "María Silva compró 3 licencias de Power BI en Lisboa por 500 euros."
]

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

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

Cada entidad trae tres informaciones útiles: el texto detectado, la categoría (por ejemplo Person, Location, Quantity, DateTime, Organization), una posible subcategoría y un grado de confianza entre 0 y 1. Ese último valor es el que le permite decidir en qué resultados confiar.

Paso 6: Procesar varios documentos y filtrar por confianza

En la práctica raramente se analiza una frase aislada. Envíe los textos en lote y reúna todo en una tabla para después filtrar las entidades con confianza baja.

import pandas as pd

documentos = [
    "María Silva compró 3 licencias de Power BI en Lisboa por 500 euros.",
    "El contrato con Contoso termina el 31 de diciembre.",
    "Enviamos el informe a João Barros el martes."
]

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

filas = []
for i, doc in enumerate(resultado):
    if doc.is_error:
        print("El documento", i, "falló:", doc.error.code)
        continue
    for e in doc.entities:
        filas.append({
            "documento": i,
            "texto": e.text,
            "categoria": e.category,
            "subcategoria": e.subcategory,
            "confianza": e.confidence_score
        })

df = pd.DataFrame(filas)
df_fiable = df[df["confianza"] >= 0.8]
print(df_fiable)

El servicio tiene un límite máximo de documentos por llamada, así que, si tiene miles de textos, divida la lista en bloques pequeños y haga una llamada por bloque.

Paso 7: Resolver los errores más comunes

401 Unauthorized: la clave es incorrecta o se ha regenerado. Cópiela de nuevo desde Keys and Endpoint.
404 Not Found: el endpoint está incompleto. Debe terminar con una barra y corresponder al recurso y a la región correctos.
Pocas entidades detectadas: revise el código de idioma. Enviar texto en español con language="en" degrada mucho el resultado.
InvalidDocumentBatch: ha enviado demasiados documentos (o demasiado largos) en una sola llamada. Reduzca el tamaño del lote.

Verificar el resultado

Ejecute el script con la frase de ejemplo. Debería ver a María Silva reconocida como Person, Lisboa como Location, "3" como Quantity y "500 euros" como Quantity con subcategoría de moneda. Si la lista sale vacía, imprima doc.is_error y doc.error.message: casi siempre es la clave, el endpoint o el idioma. Una buena prueba final es usar un texto real de su negocio y confirmar que las entidades que le interesan aparecen con una confianza superior a 0,8.

Conclusión

Con un recurso Language y menos de 20 líneas de Python ya puede convertir texto libre en entidades estructuradas, listas para cargar en un Lakehouse o en un modelo de Power BI. El siguiente paso natural es combinarlo con la detección de información personal (PII) para anonimizar los datos antes del análisis, o entrenar un modelo de NER personalizado cuando las categorías predefinidas no basten. ¿Qué entidades de su propio negocio — códigos de producto, números de contrato — le gustaría enseñar al modelo?