Como criar um serviço de anotação semântica de texto em Azure AI & Machine Learning

Este guia mostra como construir um serviço simples de anotação semântica de texto em Azure AI & Machine Learning para identificar entidades, categorias e relações numa colecção de documentos — útil para pesquisa, extracção de conhecimento e preparação de dados para modelos.

Pré-requisitos

• Conta Azure com permissões para criar recursos (Cognitive Services, Azure Machine Learning).
• Azure CLI e Azure ML SDK for Python instalados.
• Python 3.8+ e pip; editor de texto (VS Code sugerido).
• Conjunto de documentos em formato .txt ou .csv para anotação.
• Noções básicas de JSON e HTTP (para testar a API).

Passo 1: Conceito e preparação dos dados

Explica-se o que é anotação semântica: marcar tokens com etiquetas (entidades) e definir relações (por exemplo, Pessoa–Organização). Prepare um ficheiro CSV com colunas: id, text. Se quiseres relações, cria um ficheiro JSON com exemplos de spans e relações.

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

Passo 2: Criar recursos Azure

Cria um recurso Azure Cognitive Services ou Azure OpenAI se necessário, e um workspace Azure Machine Learning. O recurso Cognitive Services dá-te APIs de linguagem; o Azure ML ajuda a gerir pipelines e 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

Passo 3: Explorar APIs de Language para anotação inicial

Usa Azure AI Language (Text Analytics) para extracção automática de entidades como ponto de partida. Isto acelera as anotações humanas: corrige e acrescenta relações.

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)

Passo 4: Construir um esquema de anotação e uma ferramenta simples

Define etiquetas (ex.: Pessoa, Organização, Local, Data) e tipo de relações (ex.: trabalha_em). Para anotar em equipa, cria um script Flask minimal para exibir texto e gravar anotações JSON. Assim padronizas formato para treino.

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

Passo 5: Treinar um modelo simples em Azure Machine Learning

Transforma as anotações num formato de treino (conll/JSONL). Cria um experimento no Azure ML que corre um script de treino local usando uma biblioteca como spaCy ou Hugging Face Transformers para NER e relações.

# 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

Passo 6: Implantar o modelo como serviço de inferência

Depois de treinar, regista o modelo no Azure ML e cria um Endpoint para inferência. Isto permite enviar texto via HTTP e receber entidades e relações preditas.

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

Passo 7: Pipeline de pós-processamento e integração

Implementa um wrapper que combina as predições do modelo com regras simples (dicionários, regex) para melhorar precisão e extrair relações. Guarda resultados em JSONL ou numa tabela no Azure SQL/Storage para consumo.

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

Verificar o resultado

Testa a API enviando textos de exemplo e confirma se as entidades e relações retornadas fazem sentido. Compara com anotações humanas num conjunto de validação e calcula métricas NER (Precision, Recall, F1) ou uma revisão 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"}, ...]

Conclusão

Fizeste um fluxo completo: preparação de dados, anotação humana assistida por Azure AI Language, treino em Azure ML e implantação de um serviço de anotação semântica. Próximos passos: adicionar active learning para recolher correcções automáticas, melhorar relações com modelos de relação, ou integrar com Power BI para explorar resultados. Dica: começa com poucas etiquetas bem definidas para reduzir ambiguidade nas anotações — que etiqueta irias priorizar primeiro?