Cómo crear un servicio de anotación semántica de texto en Azure AI & Machine Learning

Esta guía muestra cómo construir un servicio simple de anotación semántica de texto en Azure AI & Machine Learning para identificar entidades, categorías y relaciones en una colección de documentos —útil para búsqueda, extracción de conocimiento y preparación de datos para modelos.

Requisitos previos

• Cuenta Azure con permisos para crear recursos (Cognitive Services, Azure Machine Learning).
• Azure CLI y Azure ML SDK for Python instalados.
• Python 3.8+ y pip; editor de texto (se recomienda VS Code).
• Conjunto de documentos en formato .txt o .csv para anotación.
• Conocimientos básicos de JSON y HTTP (para probar la API).

Paso 1: Concepto y preparación de los datos

Se explica qué es la anotación semántica: marcar tokens con etiquetas (entidades) y definir relaciones (por ejemplo, Persona–Organización). Prepara un archivo CSV con columnas: id, text. Si quieres relaciones, crea un archivo JSON con ejemplos de spans y relaciones.

# Exemplo mínimo CSV (documents.csv)
id,text
1,"João trabalha na Contoso desde 2020."
2,"A Maria visitou o Porto em Junho."

Paso 2: Crear recursos Azure

Crea un recurso Azure Cognitive Services o Azure OpenAI si es necesario, y un workspace Azure Machine Learning. El recurso Cognitive Services te proporciona APIs de lenguaje; Azure ML ayuda a gestionar pipelines y modelos personalizados.

# Exemplo Azure CLI (resumo)
az login
az group create -n rg-annotation -l westeurope
az cognitiveservices account create -n cs-annotation -g rg-annotation -l westeurope --kind TextAnalytics --sku S0 --yes
az ml workspace create -w aml-annotation -g rg-annotation

Paso 3: Explorar APIs de Language para anotación inicial

Usa Azure AI Language (Text Analytics) para extracción automática de entidades como punto de partida. Esto acelera las anotaciones humanas: corrige y añade relaciones.

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

endpoint = "https://.cognitiveservices.azure.com/"
key = ""
client = TextAnalyticsClient(endpoint=endpoint, credential=AzureKeyCredential(key))

docs = ["João trabalha na Contoso desde 2020."]
resp = client.recognize_entities(docs)
for doc in resp:
    for ent in doc.entities:
        print(ent.text, ent.category, ent.offset, ent.length)

Paso 4: Construir un esquema de anotación y una herramienta sencilla

Define etiquetas (ej.: Persona, Organización, Lugar, Fecha) y tipos de relaciones (ej.: trabaja_en). Para anotar en equipo, crea un script Flask mínimo para mostrar texto y guardar anotaciones JSON. Así estandarizas el formato para entrenamiento.

# app.py (exemplo mínimo Flask)
from flask import Flask, request, jsonify, render_template_string
import json

app = Flask(__name__)

TEMPLATE = """


{{text}}



Guardar


"""

@app.route('/', methods=['GET','POST'])
def index():
    if request.method == 'POST':
        text = request.form['text']
        anns = request.form['annotations']
        with open('annotations.json','a') as f:
            f.write(json.dumps({'text':text,'annotations':json.loads(anns)})+'\n')
        return 'Saved'
    return render_template_string(TEMPLATE, text='')

if __name__ == '__main__':
    app.run(debug=True)

Paso 5: Entrenar un modelo sencillo en Azure Machine Learning

Convierte las anotaciones a un formato de entrenamiento (conll/JSONL). Crea un experimento en Azure ML que ejecute un script de entrenamiento local usando una biblioteca como spaCy o Hugging Face Transformers para NER y relaciones.

# train.py (esqueleto)
import json
# carregar annotations.json, converter para formato spaCy/HF
# treinar modelo NER e salvar em outputs/model

if __name__=='__main__':
    # código de treino mínimo
    pass

Paso 6: Desplegar el modelo como servicio de inferencia

Tras entrenar, registra el modelo en Azure ML y crea un Endpoint para inferencia. Esto permite enviar texto vía HTTP y recibir entidades y relaciones predichas.

# Exemplo de publicação conceptual (Azure ML SDK)
from azureml.core import Workspace, Model
ws = Workspace.from_config()
model = Model.register(ws, model_path='outputs/model', model_name='ner-annotator')
# cria image e deploy para ACI ou AKS (resumido)

Paso 7: Pipeline de postprocesamiento e integración

Implementa un wrapper que combine las predicciones del modelo con reglas simples (diccionarios, regex) para mejorar la precisión y extraer relaciones. Guarda resultados en JSONL o en una tabla en Azure SQL/Storage para consumo.

# pseudo-código de pós-processamento
preds = model.predict(text)
# aplicar reglas: normalizar datas, mapear abreviaturas
# ligar entidades por proximidade ou heurísticas

Verificar el resultado

Prueba la API enviando textos de ejemplo y confirma si las entidades y relaciones devueltas tienen sentido. Compara con anotaciones humanas en un conjunto de validación y calcula métricas NER (Precision, Recall, F1) o realiza una revisión manual.

# ex. testar endpoint (curl)
curl -X POST https:///score -H "Content-Type: application/json" -d '{"text":"João trabalha na Contoso."}'

# Espera JSON com spans: [{"start":0,"end":4,"label":"Pessoa"}, ...]

Conclusión

Has realizado un flujo completo: preparación de datos, anotación humana asistida por Azure AI Language, entrenamiento en Azure ML y despliegue de un servicio de anotación semántica. Próximos pasos: añadir active learning para recoger correcciones automáticas, mejorar relaciones con modelos de relación, o integrar con Power BI para explorar resultados. Consejo: comienza con pocas etiquetas bien definidas para reducir la ambigüedad en las anotaciones — ¿qué etiqueta priorizarías primero?