Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Extração de Entidades Estruturadas

Aula 13 de 16 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Extração de Entidades Estruturadas
  2. Pipeline de Extração Básica
  3. Exemplo 1: Extração de Currículo
  4. Exemplo 2: Extração de E-mail Comercial
  5. Extração em Lote
  6. Avaliação da Qualidade da Extração
  7. Construa a Sua Referência Antes de Otimizar
  8. Pontos-chave

Lição atualizada em 3 de novembro de 2026 com base na documentação da OpenAI: temperature e top_p só são aceites com um esforço de raciocínio de none, enquanto os modelos GPT-5.6 raciocinam por padrão (medium). As chamadas que definem estes parâmetros devem, portanto, especificar reasoning={"effort": "none"} (API de Respostas) ou reasoning_effort="none" (Chat Completions). Fontes: Using GPT-6 · GPT-5.6 Terra.

Extração de Entidades Estruturadas

A extração de entidades estruturadas é um dos casos de uso mais solicitados em produção: transformar texto livre (e-mails, documentos, páginas web) em dados que a sua aplicação possa realmente utilizar. Ao combinar Saída Estruturada com prompts especializados, pode construir pipelines de extração fiáveis sem treinar um modelo NER dedicado.

Pipeline de Extração Básica

Toda a especificidade da extração reside no prompt de sistema da função abaixo, e este merece atenção redobrada. Três instruções sobrepõem-se aqui: extrair apenas o que está presente, usar null para dados em falta e nunca inferir informações que não sejam explicitamente mencionadas.

Essa última frase é a mais importante na prática. Deixado à sua sorte, um modelo preencherá alegremente um número SIRET plausível ou adivinhará uma cidade com base num código postal, com as melhores intenções. Para uma extração destinada a um sistema empresarial, esta prestatividade é uma falha grave: uma vez os dados na base de dados, não há forma de distinguir o que foi lido do que foi assumido. Definir temperature como 0.0 serve o mesmo propósito — entre duas execuções do mesmo documento, quer a mesma saída, se não for para reproduzir um incidente.

import json
from openai import OpenAI

client = OpenAI()

def extract_entities(text: str, schema: dict,
                     instructions: str = "") -> dict:
    """Extrai entidades estruturadas de texto livre."""
    system = (
        "You are a specialized entity extractor. "
        "Extract ONLY information present in the text. "
        "If information is missing, use null. "
        "NEVER infer information not explicitly mentioned."
    )
    if instructions:
        system += f"\n\nAdditional instructions: {instructions}"

    response = client.responses.create(
        model="gpt-5.6-terra",
        reasoning={"effort": "none"},  # temperature requires effort none
        instructions=system,
        input=f"Text to analyze:\n\n{text}",
        text={
            "format": {
                "type": "json_schema",
                "name": "extraction",
                "schema": schema,
                "strict": True
            }
        },
        temperature=0.0
    )
    return json.loads(response.output_text)

Exemplo 1: Extração de Currículo

Um currículo é um excelente terreno de teste porque combina secções estáveis com um layout completamente livre. O esquema abaixo agrupa os detalhes de contacto num objeto identity onde quase todos os campos são anuláveis — um candidato pode não fornecer um número de telefone, e tornar esse campo obrigatório seria essencialmente convidar o modelo a inventar um.

As competências não são simples cadeias de caracteres, mas objetos com três atributos, o que permite preservar o nível declarado e categorizar cada competência. Sem estes enums, “Scrum” e “Python” acabariam lado a lado na mesma lista plana, inúteis para um filtro que tente isolar linguagens. Note também o campo end_date nas experiências, que é anulável, ao contrário de start_date: é assim que codifica uma posição atual sem inventar uma convenção caseira como “presente” ou “9999”. No currículo de teste, esta subtilidade manifesta-se na linha da TechCorp.

resume_schema = {
    "type": "object",
    "properties": {
        "identity": {
            "type": "object",
            "properties": {
                "full_name": {"type": "string"},
                "email": {"type": ["string", "null"]},
                "phone": {"type": ["string", "null"]},
                "location": {"type": ["string", "null"]},
                "linkedin": {"type": ["string", "null"]}
            },
            "required": ["full_name", "email", "phone",
                          "location", "linkedin"],
            "additionalProperties": False
        },
        "current_title": {"type": ["string", "null"]},
        "years_experience": {"type": ["integer", "null"]},
        "skills": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "level": {
                        "type": "string",
                        "enum": ["beginner", "intermediate",
                                 "advanced", "expert"]
                    },
                    "category": {
                        "type": "string",
                        "enum": ["language", "framework", "tool",
                                 "methodology", "soft_skill"]
                    }
                },
                "required": ["name", "level", "category"],
                "additionalProperties": False
            }
        },
        "experiences": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "company": {"type": "string"},
                    "title": {"type": "string"},
                    "start_date": {"type": "string"},
                    "end_date": {"type": ["string", "null"]},
                    "description": {"type": "string"}
                },
                "required": ["company", "title", "start_date",
                              "end_date", "description"],
                "additionalProperties": False
            }
        },
        "education": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "institution": {"type": "string"},
                    "degree": {"type": "string"},
                    "year": {"type": ["string", "null"]}
                },
                "required": ["institution", "degree", "year"],
                "additionalProperties": False
            }
        },
        "languages": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "language": {"type": "string"},
                    "level": {
                        "type": "string",
                        "enum": ["a1", "a2", "b1", "b2",
                                 "c1", "c2", "native"]
                    }
                },
                "required": ["language", "level"],
                "additionalProperties": False
            }
        }
    },
    "required": ["identity", "current_title", "years_experience",
                  "skills", "experiences", "education", "languages"],
    "additionalProperties": False
}

resume_text = """
Marie Dupont - Senior Full Stack Developer
Email: [email protected] | Tel: +33 6 12 34 56 78
Paris, France | linkedin.com/in/mariedupont

8 years of experience in web development.

Skills: Python (expert), TypeScript (advanced), React (advanced),
Django (expert), PostgreSQL (advanced), Docker (intermediate),
Scrum (advanced)

Experience:
- TechCorp (2022-present): Lead Full Stack Developer
  Principal architect of a B2B SaaS platform, team of 6 devs.
- StartupAI (2019-2022): Senior Developer
  Development of ML APIs in Python/FastAPI.

Education:
- EPITECH Paris, Master in Computer Science (2017)

Languages: French (native), English (C1), Spanish (B1)
"""

result = extract_entities(resume_text, resume_schema)

Exemplo 2: Extração de E-mail Comercial

O segundo exemplo muda de natureza: já não estamos apenas a copiar informações, estamos a pedir ao modelo que interprete. intent e urgency são julgamentos — nenhuma frase no e-mail diz “isto é um pedido de orçamento, alta prioridade”. É precisamente isto que um pipeline de extração clássico baseado em regras ou expressões regulares não consegue fazer, e é exatamente o que justifica o uso de um LLM aqui e não noutro lugar.

O resto do esquema retorna a factos verificáveis: produtos mencionados, valores com o seu contexto, datas e o seu significado, ações necessárias. O campo summary fecha o objeto e serve o humano que irá rever a fila, não o código. Um ponto de vigilância com este esquema misto: um erro de julgamento em urgency não invalida os valores, mas o inverso pode acontecer, porque um modelo que não compreende a intenção às vezes lê o resto através desse equívoco. Se a classificação for crítica para o seu encaminhamento, separe-a numa chamada dedicada.

email_schema = {
    "type": "object",
    "properties": {
        "intent": {
            "type": "string",
            "enum": ["quote_request", "complaint", "information",
                     "order", "partnership", "other"]
        },
        "urgency": {
            "type": "string",
            "enum": ["critical", "high", "normal", "low"]
        },
        "sender": {
            "type": "object",
            "properties": {
                "name": {"type": ["string", "null"]},
                "company": {"type": ["string", "null"]},
                "email": {"type": ["string", "null"]}
            },
            "required": ["name", "company", "email"],
            "additionalProperties": False
        },
        "mentioned_products": {
            "type": "array",
            "items": {"type": "string"}
        },
        "mentioned_amounts": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "value": {"type": "number"},
                    "currency": {"type": "string"},
                    "context": {"type": "string"}
                },
                "required": ["value", "currency", "context"],
                "additionalProperties": False
            }
        },
        "key_dates": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "date": {"type": "string"},
                    "significance": {"type": "string"}
                },
                "required": ["date", "significance"],
                "additionalProperties": False
            }
        },
        "required_actions": {
            "type": "array",
            "items": {"type": "string"}
        },
        "summary": {"type": "string"}
    },
    "required": ["intent", "urgency", "sender",
                  "mentioned_products", "mentioned_amounts",
                  "key_dates", "required_actions", "summary"],
    "additionalProperties": False
}

Extração em Lote

Para processar grandes volumes, paralelize as suas extrações. Um loop sequencial sobre mil documentos passa a maior parte do tempo à espera da rede; com asyncio, estas esperas sobrepõem-se e o lote é processado numa fração do tempo.

O semáforo não é um detalhe decorativo. Sem ele, lançar mil tarefas de uma vez saturará a sua quota e desencadeará erros de limite de taxa que custam mais em novas tentativas do que poupam em velocidade. Defina o valor max_concurrent observando os seus próprios limites, sendo dez um ponto de partida cauteloso. Note também return_exceptions=True: impede que um único documento mal formatado derrube todo o lote, deixando-lhe a tarefa de resolver as falhas posteriormente.

import asyncio
from openai import AsyncOpenAI

async_client = AsyncOpenAI()

async def extract_batch(texts: list[str], schema: dict,
                          max_concurrent: int = 10) -> list[dict]:
    """Extração paralela com controlo de concorrência."""
    semaphore = asyncio.Semaphore(max_concurrent)

    async def extract_one(text: str) -> dict:
        async with semaphore:
            response = await async_client.responses.create(
                model="gpt-5.6-terra",
                reasoning={"effort": "none"},  # temperature requires effort none
                instructions="Extract entities from the provided text. "
                             "Use null for missing fields.",
                input=text,
                text={
                    "format": {
                        "type": "json_schema",
                        "name": "extraction",
                        "schema": schema,
                        "strict": True
                    }
                },
                temperature=0.0
            )
            return json.loads(response.output_text)

    tasks = [extract_one(t) for t in texts]
    return await asyncio.gather(*tasks, return_exceptions=True)

Avaliação da Qualidade da Extração

Um pipeline de extração sem um conjunto de teste anotado é um pipeline cuja fiabilidade ninguém conhece, e a impressão deixada por três exemplos lidos à mão revela-se quase sempre demasiado otimista. A função abaixo compara uma extração obtida campo por campo com uma referência estabelecida manualmente, devolvendo a precisão global juntamente com uma desagregação das discrepâncias.

Esta desagregação é a parte útil: os erros quase nunca são distribuídos uniformemente. Um campo concentra os problemas — muitas vezes uma data ambígua, um nível de competência implícito ou uma categoria mal definida — e uma única frase adicionada ao prompt de sistema resolve-o. Sem esta medição, estaria a ajustar o prompt ao acaso, possivelmente piorando um campo que já funcionava.

def evaluate_extraction(expected: dict, obtained: dict,
                       fields: list[str]) -> dict:
    """Compara a extração obtida com a referência."""
    correct = 0
    total = len(fields)
    errors = []

    for field in fields:
        val_expected = expected.get(field)
        val_obtained = obtained.get(field)

        if val_expected == val_obtained:
            correct += 1
        else:
            errors.append({
                "field": field,
                "expected": val_expected,
                "obtained": val_obtained
            })

    return {
        "precision": correct / total if total > 0 else 0,
        "correct": correct,
        "total": total,
        "errors": errors
    }

Construa a Sua Referência Antes de Otimizar

Escolha um tipo de documento do seu domínio — contratos, faturas, relatórios — e defina um esquema de extração de pelo menos dez campos, misturando deliberadamente campos fáceis com outros que sabe serem ambíguos. Reúna cinco documentos de exemplo com as suas extrações esperadas, escritas à mão: este passo é tedioso, demora uma hora, e é o que dá valor a todo o trabalho subsequente.

Depois, execute o pipeline, meça a precisão e leia a lista de erros campo por campo. O campo com mais falhas dir-lhe-á o que corrigir no prompt; uma segunda medição dir-lhe-á se a correção realmente ajudou — ou se degradou outro campo no processo, o que acontece mais frequentemente do que possa pensar assim que uma instrução adicional desvia a atenção do modelo.

Pontos-chave

  • A extração estruturada substitui modelos NER dedicados na maioria dos casos de uso
  • Use temperature=0.0 para maximizar a consistência
  • Torne os campos opcionais anuláveis em vez de opcionais
  • Paralelize com asyncio para grandes volumes
  • Avalie sistematicamente a qualidade com um conjunto de teste anotado
  • As instruções do prompt de sistema guiam o conteúdo, o esquema restringe a estrutura