Ir al contenido principal
Español— Elegir un idioma
Menú

Extracción estructurada de entidades

Lección 13 de 16 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. Extracción estructurada de entidades
  2. Canalización básica de extracción
  3. Ejemplo 1: Extracción de currículums
  4. Ejemplo 2: Extracción de correos comerciales
  5. Extracción por lotes
  6. Evaluación de la calidad de la extracción
  7. Construye tu referencia antes de optimizar
  8. Puntos clave

Lección actualizada el 3 de noviembre de 2026 según la documentación de OpenAI: temperature y top_p solo se aceptan con un esfuerzo de razonamiento de none, mientras que los modelos GPT-5.6 razonan por defecto (medium). Por tanto, las llamadas que establezcan estos parámetros deben especificar reasoning={"effort": "none"} (API de Responses) o reasoning_effort="none" (Chat Completions). Fuentes: Uso de GPT-6 · GPT-5.6 Terra.

Extracción estructurada de entidades

La extracción estructurada de entidades es uno de los casos de uso más solicitados en producción: transformar texto libre (correos electrónicos, documentos, páginas web) en datos que tu aplicación pueda utilizar realmente. Combinando la Salida Estructurada con indicaciones especializadas, puedes construir canalizaciones de extracción fiables sin necesidad de entrenar un modelo NER dedicado.

Canalización básica de extracción

Toda la especificidad de la extracción reside en la indicación del sistema de la función siguiente, y merece una atención especial. Aquí se superponen tres instrucciones: extraer solo lo que esté presente, usar null para los datos faltantes y nunca inferir información que no se mencione explícitamente.

Esa última frase es la más importante en la práctica. Si se le deja actuar por su cuenta, un modelo rellenará gustosamente un número SIRET plausible o adivinará una ciudad a partir de un código postal, con la mejor de las intenciones. Para una extracción destinada a un sistema empresarial, esta servicialidad es un defecto grave: una vez que los datos están en la base de datos, no hay forma de distinguir lo que se leyó de lo que se asumió. Establecer temperature en 0,0 sirve al mismo propósito: en dos ejecuciones del mismo documento, quieres la misma salida, si no es para otra cosa, para poder reproducir un incidente.

import json
from openai import OpenAI

client = OpenAI()

def extract_entities(text: str, schema: dict,
                     instructions: str = "") -> dict:
    """Extrae entidades estructuradas a partir de texto libre."""
    system = (
        "Eres un extractor de entidades especializado. "
        "Extrae SOLO la información presente en el texto. "
        "Si falta información, usa null. "
        "NUNCA infieras información que no se mencione explícitamente."
    )
    if instructions:
        system += f"\n\nInstrucciones adicionales: {instructions}"

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

Ejemplo 1: Extracción de currículums

Un currículum es un terreno de prueba excelente porque combina secciones estables con un diseño completamente libre. El esquema siguiente agrupa los datos de contacto en un objeto identity donde casi todos los campos son anulables: un candidato podría no proporcionar un número de teléfono, y hacer que ese campo sea obligatorio invitaría esencialmente al modelo a inventar uno.

Las habilidades no son simples cadenas, sino objetos con tres atributos, lo que te permite preservar el nivel declarado y categorizar cada habilidad. Sin estas enumeraciones, «Scrum» y «Python» acabarían uno al lado del otro en la misma lista plana, inútil para un filtro que intente aislar lenguajes. Observa también el campo end_date en las experiencias, que es anulable mientras que start_date no lo es: así es como codificas un puesto actual sin inventar una convención casera como «presente» o «9999». En el currículum de prueba, este matiz se manifiesta en la línea de 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)

Ejemplo 2: Extracción de correos comerciales

El segundo ejemplo cambia de naturaleza: ya no se trata solo de copiar información, sino de pedir al modelo que interprete. intent y urgency son juicios; ninguna frase del correo dice «esto es una solicitud de presupuesto, alta prioridad». Esto es precisamente lo que una canalización de extracción clásica basada en reglas o expresiones regulares no puede hacer, y es exactamente lo que justifica el uso de un LLM aquí y no en otro lugar.

El resto del esquema vuelve a hechos verificables: productos mencionados, importes con su contexto, fechas y su significado, acciones requeridas. El campo summary cierra el objeto y sirve a la persona humana que revisará la cola, no al código. Un punto de vigilancia con este esquema mixto: un error de juicio en urgency no invalida los importes, pero lo contrario puede ocurrir, porque un modelo que no entiende la intención a veces lee el resto a través de ese malentendido. Si la clasificación es crítica para tu enrutamiento, sepárala en una llamada 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
}

Extracción por lotes

Para procesar grandes volúmenes, paraleliza tus extracciones. Un bucle secuencial sobre mil documentos pasa la mayor parte del tiempo esperando a la red; con asyncio, estas esperas se solapan y el lote se procesa en una fracción del tiempo.

El semáforo no es un detalle decorativo. Sin él, lanzar mil tareas a la vez saturará tu cuota y desencadenará errores de límite de tasa que cuestan más en reintentos de lo que ahorran en velocidad. Establece el valor de max_concurrent observando tus propios límites, siendo diez un punto de partida prudente. Observa también return_exceptions=True: evita que un único documento mal formado haga caer todo el lote, dejándote ordenar los fallos después.

import asyncio
from openai import AsyncOpenAI

async_client = AsyncOpenAI()

async def extract_batch(texts: list[str], schema: dict,
                          max_concurrent: int = 10) -> list[dict]:
    """Extracción paralela con control de concurrencia."""
    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 requiere effort none
                instructions="Extrae entidades del texto proporcionado. "
                             "Usa null para los campos faltantes.",
                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)

Evaluación de la calidad de la extracción

Una canalización de extracción sin un conjunto de pruebas anotado es una canalización cuya fiabilidad nadie conoce, y la impresión que dejan tres ejemplos leídos a mano casi siempre resulta demasiado optimista. La función siguiente compara una extracción obtenida campo por campo frente a una referencia establecida manualmente, devolviendo la precisión global junto con un desglose de las discrepancias.

Este desglose es la parte útil: los errores casi nunca se distribuyen uniformemente. Un campo concentra los problemas —a menudo una fecha ambigua, un nivel de habilidad implícito o una categoría mal definida— y una sola frase añadida a la indicación del sistema lo soluciona. Sin esta medición, estarías ajustando la indicación al azar, posiblemente empeorando un campo que ya funcionaba.

def evaluate_extraction(expected: dict, obtained: dict,
                       fields: list[str]) -> dict:
    """Compara la extracción obtenida con la referencia."""
    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
    }

Construye tu referencia antes de optimizar

Elige un tipo de documento de tu dominio —contratos, facturas, informes— y define un esquema de extracción de al menos diez campos, mezclando deliberadamente campos fáciles con otros que sabes que son ambiguos. Reúne cinco documentos de ejemplo con sus extracciones esperadas, escritas a mano: este paso es tedioso, lleva una hora, y es lo que da valor a todo el trabajo posterior.

A continuación, ejecuta la canalización, mide la precisión y lee la lista de errores campo por campo. El campo más defectuoso te dirá qué corregir en la indicación; una segunda medición te dirá si la corrección ayudó realmente —o si degradó otro campo en el proceso, algo que ocurre más a menudo de lo que podrías pensar en cuanto una instrucción adicional desplaza la atención del modelo.

Puntos clave

  • La extracción estructurada sustituye a los modelos NER dedicados en la mayoría de los casos de uso
  • Usa temperature=0.0 para maximizar la consistencia
  • Haz que los campos opcionales sean anulables en lugar de opcionales
  • Paraleliza con asyncio para grandes volúmenes
  • Evalúa sistemáticamente la calidad con un conjunto de pruebas anotado
  • Las instrucciones de la indicación del sistema guían el contenido, el esquema restringe la estructura