Štruktúrovaná extrakcia entít
Na tejto strane
Lekcia aktualizovaná 3. novembra 2026 na základe dokumentácie OpenAI: parametre
temperatureatop_psú akceptované len pri úsilí o logické uvažovanie (reasoning effort) nastavenom nanone, zatiaľ čo modely GPT-5.6 štandardne uvažujú (medium). Volania, ktoré nastavujú tieto parametre, preto musia špecifikovaťreasoning={"effort": "none"}(Responses API) aleboreasoning_effort="none"(Chat Completions). Zdroje: Používanie GPT-6 · GPT-5.6 Terra.
Štruktúrovaná extrakcia entít
Štruktúrovaná extrakcia entít je jedným z najžiadanejších prípadov použitia v produkcii: transformácia voľného textu (e-maily, dokumenty, webové stránky) na údaje, ktoré môže tvoja aplikácia reálne využiť. Kombináciou štruktúrovaného výstupu so špecializovanými promptmi môžeš zostaviť spoľahlivé extrakčné pipeline bez potreby trénovať vyhradený model NER.
Základná extrakčná pipeline
Celá špecifičnosť extrakcie spočíva v systémovom prompte nižšie uvedenej funkcie a táto časť si zaslúži pozornosť. Prekrývajú sa tu tri inštrukcie: extrahuj len to, čo je prítomné, pre chýbajúce údaje použi null a nikdy neinferuj informácie, ktoré nie sú explicitne uvedené.
Posledná veta je v praxi najdôležitejšia. Ak ho necháš na vlastné zariadenie, model rád doplní pravdepodobné číslo SIRET alebo uhádne mesto podľa predvoľby telefónneho čísla, a to s tým najlepším úmyslom. Pri extrakcii určenej pre business systém je táto ochota vážnou chybou: keď sa údaje dostanú do databázy, niet spôsobu, ako rozlíšiť, čo bolo prečítané a čo bolo domyslené. Nastavenie temperature na 0,0 slúži rovnakému účelu – pri dvoch spusteniach toho istého dokumentu chceš rovnaký výstup, aspoň kvôli možnosti reprodukcie incidentu.
import json
from openai import OpenAI
client = OpenAI()
def extract_entities(text: str, schema: dict,
instructions: str = "") -> dict:
"""Extrahuje štruktúrované entity z voľného textu."""
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)
Príklad 1: Extrakcia z životopisu
Životopis je vynikajúcim testovacím prostredím, pretože kombinuje stabilné sekcie s úplne voľným rozložením. Nižšie uvedená schéma zoskupuje kontaktné údaje do objektu identity, kde je takmer každé pole nullable – kandidát nemusí uviesť telefónne číslo a učinienie tohto poľa povinným by v podstate vyzvalo model, aby si ho vymyslel.
Zručnosti nie sú jednoduché reťazce, ale objekty s tromi atribútmi, čo ti umožňuje zachovať uvedenú úroveň a kategorizovať každú zručnosť. Bez týchto enumov by sa „Scrum“ a „Python“ ocitli vedľa seba v rovnakom plochom zozname, čo je nepoužiteľné pre filter snažiaci sa izolovať programovacie jazyky. Všimni si aj pole end_date v skúsenostiach, ktoré je nullable, zatiaľ čo start_date nie je: takto zakóduješ aktuálnu pozíciu bez vymýšľania vlastnej konvencie, ako sú „present“ alebo „9999“. Pri testovacom životopise sa táto jemnosť prejaví na riadku 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)
Príklad 2: Extrakcia z obchodného e-mailu
Druhý príklad mení povahu: už len nekopírujeme informácie, žiadame model, aby interpretoval. intent (zámer) a urgency (urgencia) sú úsudky – žiadna veta v e-maile nehovorí „toto je žiadosť o cenovú ponuku, vysoká priorita“. To je presne to, čo klasická extrakčná pipeline založená na pravidlách alebo regulárnych výrazoch nedokáže, a je to presne to, čo odôvodňuje použitie LLM tu a nie inde.
Zvyšok schémy sa vracia k overiteľným faktom: spomenuté produkty, sumy s ich kontextom, dátumy a ich význam, požadované akcie. Pole summary uzatvára objekt a slúži človeku, ktorý bude kontrolovať frontu, nie kódu. Jeden bod opatrnosti pri tejto zmiešanej schéme: chyba v úsudku pri urgency neinvaliduje sumy, ale opačne sa to stať môže, pretože model, ktorý nepochopí zámer, niekedy číta zvyšok cez túto mylnú predstavu. Ak je klasifikácia kritická pre tvoje smerovanie, oddeľ ju do samostatného volania.
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
}
Dávková extrakcia
Na spracovanie veľkých objemov paralelizuj svoje extrakcie. Sekvenčná slučka cez tisíc dokumentov trávi väčšinu času čakáním na sieť; s asyncio sa tieto čakania prekrývajú a dávka sa spracuje v zlomku času.
Semafór nie je ozdobný detail. Bez neho by spustenie tisíce úloh naraz nasýtilo tvoju kvótu a spustilo chyby limitu rýchlosti (rate limit), ktoré stoja pri opakovaných pokusoch viac, než ušetria na rýchlosti. Hodnotu max_concurrent nastav podľa pozorovania vlastných limitov, pričom desať je opatrným východiskovým bodom. Všimni si aj return_exceptions=True: zabraňuje tomu, aby jeden chybný dokument zhodil celú dávku, čo ti umožní triediť zlyhania až následne.
import asyncio
from openai import AsyncOpenAI
async_client = AsyncOpenAI()
async def extract_batch(texts: list[str], schema: dict,
max_concurrent: int = 10) -> list[dict]:
"""Paralelná extrakcia s kontrolou súbežnosti."""
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)
Hodnotenie kvality extrakcie
Extrakčná pipeline bez anotovanej testovacej sady je pipeline, ktorej spoľahlivosť nepozná nikto, a dojem z troch príkladov prečítaných ručne sa takmer vždy ukáže ako príliš optimistický. Funkcia nižšie porovnáva získanú extrakciu pole po poli s manuálne stanovenou referenciou a vracia celkovú presnosť spolu s rozpisom nezrovnalostí.
Tento rozpis je tou užitočnou časťou: chyby sú takmer nikdy rozdelené rovnomerne. Jedno pole sústreďuje problémy – často nejednoznačný dátum, implicitná úroveň zručnosti alebo zle definovaná kategória – a jedna veta pridaná do systémového promptu to opraví. Bez tohto merania by si ladil prompt naslepo a možno by si zhoršil pole, ktoré už fungovalo.
def evaluate_extraction(expected: dict, obtained: dict,
fields: list[str]) -> dict:
"""Porovná získanú extrakciu s referenciou."""
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
}
Pred optimalizáciou si vytvor referenčnú sadu
Vyber si typ dokumentu zo svojej domény – zmluvy, faktúry, správy – a definuj extrakčnú schému aspoň desiatich polí, pričom zámerne zmiešaj ľahké polia s tými, o ktorých vieš, že sú nejednoznačné. Zostav päť ukážkových dokumentov s ich očakávanými extrakciami, napísanými ručne: tento krok je zdĺhavý, zaberie hodinu, a práve on dáva všetkej následnej práci hodnotu.
Potom spusti pipeline, zmeraj presnosť a prečítaj si zoznam chýb pole po poli. Najchybovejšie pole ti povie, čo opraviť v prompte; druhé meranie ti povie, či oprava skutočne pomohla – alebo či nezhoršila iné pole v procese, čo sa stáva častejšie, než by si čakal, hneď ako dodatočná inštrukcia posunie pozornosť modelu.
Kľúčové poznatky
- Štruktúrovaná extrakcia nahrádza vyhradené modely NER vo väčšine prípadov použitia
- Použi
temperature=0.0na maximalizáciu konzistencie - Urob voliteľné polia nullable namiesto toho, aby boli len voliteľné
- Pre veľké objemy paralelizuj pomocou asyncio
- Systematicky hodnot kvalitu pomocou anotovanej testovacej sady
- Inštrukcie v systémovom prompte usmerňujú obsah, schéma obmedzuje štruktúru