Gestructureerde entiteitsextractie
Op deze pagina
Les bijgewerkt op 3 november 2026 op basis van OpenAI-documentatie:
temperatureentop_pworden alleen geaccepteerd met een redeneerinspanning vannone, terwijl GPT-5.6-modellen standaard redeneren (medium). Aanroepen die deze parameters instellen, moeten daaromreasoning={"effort": "none"}(Responses API) ofreasoning_effort="none"(Chat Completions) specificeren. Bronnen: Using GPT-6 · GPT-5.6 Terra.
Gestructureerde entiteitsextractie
Gestructureerde entiteitsextractie is een van de meest gevraagde use cases in productie: het omzetten van vrije tekst (e-mails, documenten, webpagina’s) in data die uw applicatie daadwerkelijk kan gebruiken. Door Gestructureerde Output te combineren met gespecialiseerde prompts, kunt u betrouwbare extractiepijplijnen bouwen zonder een specifiek NER-model te trainen.
Basis extractiepijplijn
De hele specificiteit van extractie zit in de systeemprompt van de onderstaande functie, en deze verdient nauwkeurige aandacht. Drie instructies overlappen hier: extraheer alleen wat aanwezig is, gebruik null voor ontbrekende gegevens, en leid nooit informatie af die niet expliciet wordt vermeld.
Die laatste zin is in de praktijk het belangrijkst. Als u een model zijn gang laat gaan, vult het met de beste bedoelingen graag een plausibel SIRET-nummer in of raadt het een stad op basis van een netnummer. Voor extractie bestemd voor een bedrijfssysteem is deze behulpzaamheid een ernstig gebrek: zodra de gegevens in de database staan, is er geen manier meer om te onderscheiden wat gelezen is en wat aangenomen. Het instellen van temperature op 0.0 dient hetzelfde doel: over twee runs van hetzelfde document heen wilt u dezelfde output, al was het maar om een incident te reproduceren.
import json
from openai import OpenAI
client = OpenAI()
def extract_entities(text: str, schema: dict,
instructions: str = "") -> dict:
"""Extraheert gestructureerde entiteiten uit vrije tekst."""
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)
Voorbeeld 1: CV-extractie
Een cv is een uitstekend testterrein omdat het stabiele secties combineert met een volledig vrij vormgegeven lay-out. Het onderstaande schema groepeert contactgegevens in een identity-object waar bijna elk veld nullable is; een kandidaat geeft misschien geen telefoonnummer op, en dat veld als verplicht markeren zou het model eigenlijk uitnodigen er een te verzinnen.
Vaardigheden zijn geen simpele strings maar objecten met drie attributen, waardoor u het opgegeven niveau kunt behouden en elke vaardigheid kunt categoriseren. Zonder deze enums zouden “Scrum” en “Python” naast elkaar in dezelfde platte lijst belanden, nutteloos voor een filter dat talen probeert te isoleren. Let ook op het veld end_date bij ervaringen, dat nullable is terwijl start_date dat niet is: zo codeert u een huidige functie zonder een zelfbedachte conventie als “present” of “9999” te verzinnen. Bij het test-cv speelt deze subtiliteit zich af op de regel van 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)
Voorbeeld 2: Extractie van commerciële e-mails
Het tweede voorbeeld verandert van aard: we kopiëren niet langer alleen informatie, we vragen het model te interpreteren. intent en urgency zijn oordelen; geen enkele zin in de e-mail zegt “dit is een offerteaanvraag, hoge prioriteit”. Dit is precies wat een klassieke extractiepijplijn op basis van regels of reguliere expressies niet kan, en het is exact wat het gebruik van een LLM hier rechtvaardigt in plaats van elders.
De rest van het schema keert terug naar verifieerbare feiten: genoemde producten, bedragen met hun context, data en hun betekenis, vereiste acties. Het veld summary sluit het object af en dient de mens die de wachtrij zal beoordelen, niet de code. Één aandachtspunt bij dit gemengde schema: een beoordelingsfout op urgency ongeldigt de bedragen niet, maar het omgekeerde kan wel gebeuren, omdat een model dat de intentie verkeerd begrijpt soms de rest door die misvatting leest. Als classificatie cruciaal is voor uw routing, splits dit dan af in een aparte aanroep.
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
}
Batch-extractie
Om grote volumes te verwerken, parallelleert u uw extracties. Een sequentiële loop over duizend documenten besteedt het grootste deel van de tijd aan wachten op het netwerk; met asyncio overlappen deze wachttijden en wordt de batch verwerkt in een fractie van de tijd.
De semaphore is geen decoratief detail. Zonder dit zal het tegelijk starten van duizend taken uw quota verzadigen en rate limit-fouten triggeren die bij retry’s meer kosten dan ze aan snelheid besparen. Stel de waarde max_concurrent in door uw eigen limieten te observeren, waarbij tien een voorzichtig startpunt is. Let ook op return_exceptions=True: dit voorkomt dat één slecht gevormd document de hele batch doet crashen, waardoor u fouten afterward kunt sorteren.
import asyncio
from openai import AsyncOpenAI
async_client = AsyncOpenAI()
async def extract_batch(texts: list[str], schema: dict,
max_concurrent: int = 10) -> list[dict]:
"""Parallelle extractie met concurrentiebeheersing."""
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)
Kwaliteit van extractie evalueren
Een extractiepijplijn zonder een geannoteerde testset is een pijplijn waarvan niemand de betrouwbaarheid kent, en de indruk die drie met de hand gelezen voorbeelden achterlaten, blijkt bijna altijd te optimistisch. De onderstaande functie vergelijkt een verkregen extractie veld per veld met een handmatig vastgestelde referentie, en retourneert de algehele precisie samen met een uitsplitsing van discrepanties.
Deze uitsplitsing is het nuttige deel: fouten zijn bijna nooit uniform verdeeld. Eén veld concentreert de problemen—vaak een ambiguë datum, een impliciet vaardigheidsniveau of een slecht gedefinieerde categorie—en één zin toegevoegd aan de systeemprompt lost het op. Zonder deze meting zou u de prompt willekeurig aanpassen, mogelijk ten koste van een veld dat al werkte.
def evaluate_extraction(expected: dict, obtained: dict,
fields: list[str]) -> dict:
"""Vergelijkt verkregen extractie met de referentie."""
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
}
Bouw uw referentie voordat u optimaliseert
Kies een documenttype uit uw domein—contracten, facturen, rapporten—en definieer een extractieschema van minimaal tien velden, waarbij u bewust makkelijke velden mengt met velden waarvan u weet dat ze ambigu zijn. Stel vijf voorbeelddocumenten samen met hun verwachte extracties, met de hand geschreven: deze stap is vervelend, kost een uur, en het is wat al het volgende werk zijn waarde geeft.
Voer vervolgens de pijplijn uit, meet de precisie en lees de lijst met fouten veld per veld. Het meest foutieve veld zal u vertellen wat u in de prompt moet corrigeren; een tweede meting zal u vertellen of de correctie daadwerkelijk heeft geholpen—of dat het een ander veld heeft verslechterd in het proces, wat vaker gebeurt dan u denkt zodra een extra instructie de aandacht van het model verschuift.
Belangrijkste punten
- Gestructureerde extractie vervangt gespecialiseerde NER-modellen voor de meeste use cases
- Gebruik
temperature=0.0om consistentie te maximaliseren - Maak optionele velden nullable in plaats van optioneel
- Parallelleer met asyncio voor grote volumes
- Evalueer kwaliteit systematisch met een geannoteerde testset
- Instructies in de systeemprompt sturen de inhoud, het schema beperkt de structuur