Ekstrakcija strukturiranih entiteta
Na ovoj stranici
Lekcija ažurirana 3. studenog 2026. na temelju OpenAI dokumentacije:
temperatureitop_pprihvaćeni su samo uz napor razmišljanja (reasoning effort) odnone, dok modeli GPT-5.6 prema zadanim postavkama razmišljaju (medium). Pozivi koji postavljaju ove parametre stoga moraju specificiratireasoning={"effort": "none"}(Responses API) ilireasoning_effort="none"(Chat Completions). Izvori: Korištenje GPT-6 · GPT-5.6 Terra.
Ekstrakcija strukturiranih entiteta
Ekstrakcija strukturiranih entiteta jedan je od najtraženijih slučajeva uporabe u proizvodnji: pretvaranje slobodnog teksta (e-poruka, dokumenata, web stranica) u podatke koje tvoja aplikacija zapravo može koristiti. Kombiniranjem strukturiranog izlaza sa specijaliziranim upitima možeš izgraditi pouzdane cjevovode za ekstrakciju bez potrebe za treniranjem namjenskog NER modela.
Osnovni cjevovod za ekstrakciju
Cjelokupna specifičnost ekstrakcije leži u sistemskom upitu funkcije u nastavku, i on zaslužuje pomnu pozornost. Ovdje se preklapaju tri upute: ekstrahiraj samo ono što je prisutno, koristi null za podatke koji nedostaju i nikada ne zaključuj informacije koje nisu eksplicitno spomenute.
Ta posljednja rečenica u praksi je najvažnija. Prepušten sam sebi, model će s veseljem popuniti uvjerljiv SIRET broj ili pogoditi grad na temelju pozivnog broja, s najboljim namjerama. Za ekstrakciju namijenjenu poslovnom sustavu, ta uslužnost ozbiljan je nedostatak: jednom kada su podaci u bazi, nema načina razlikovati ono što je pročitano od onoga što je pretpostavljeno. Postavljanje temperature na 0.0 služi istoj svrsi—kroz dva pokretanja istog dokumenta želiš isti izlaz, barem kako bi reproducirao incident.
import json
from openai import OpenAI
client = OpenAI()
def extract_entities(text: str, schema: dict,
instructions: str = "") -> dict:
"""Ekstrahira strukturirane entitete iz slobodnog teksta."""
system = (
"Ti si specijalizirani ekstraktor entiteta. "
"Ekstrahiraj SAMO informacije prisutne u tekstu. "
"Ako informacija nedostaje, koristi null. "
"NIKADA ne zaključuj informacije koje nisu eksplicitno spomenute."
)
if instructions:
system += f"\n\nDodatne upute: {instructions}"
response = client.responses.create(
model="gpt-5.6-terra",
reasoning={"effort": "none"}, # temperature requires effort none
instructions=system,
input=f"Tekst za analizu:\n\n{text}",
text={
"format": {
"type": "json_schema",
"name": "extraction",
"schema": schema,
"strict": True
}
},
temperature=0.0
)
return json.loads(response.output_text)
Primjer 1: Ekstrakcija životopisa
Životopis je izvrsno polje za testiranje jer kombinira stabilne odjeljke s potpuno slobodnim rasporedom. Shema u nastavku grupira kontakt podatke u objekt identity gdje je gotovo svako polje nullable—kandidat možda neće navesti broj telefona, a činjenje tog polja obaveznim u suštini bi pozvalo model da ga izmisli.
Vještine nisu jednostavni nizovi znakova već objekti s tri atributa, što ti omogućuje očuvanje navedene razine i kategorizaciju svake vještine. Bez ovih enum vrijednosti, „Scrum“ i „Python“ završili bi jedan do drugoga u istom ravnom popisu, beskorisnom za filtar koji pokušava izolirati jezike. Također obrati pozornost na polje end_date u iskustvima, koje je nullable dok start_date nije: tako kodiraš trenutnu poziciju bez izmišljanja vlastite konvencije poput „present“ ili „9999“. Na testnom životopisu ta se suptilnost očituje u retku za 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)
Primjer 2: Ekstrakcija poslovnih e-poruka
Drugi primjer mijenja prirodu: više ne kopiramo samo informacije, već tražimo od modela da interpretira. intent (namjera) i urgency (hitnost) su prosudbe—nijedna rečenica u e-poruci ne kaže „ovo je zahtjev za ponudu, visok prioritet“. To je upravo ono što klasični cjevovod za ekstrakciju temeljen na pravilima ili regularnim izrazima ne može učiniti, i to je točno ono što ovdje opravdava korištenje LLM-a, a ne negdje drugdje.
Ostatak sheme vraća se na provjerljive činjenice: spomenuti proizvodi, iznosi s njihovim kontekstom, datumi i njihovo značenje, potrebne radnje. Polje summary zatvara objekt i služi čovjeku koji će pregledavati red čekanja, a ne kodu. Jedna točka opreza s ovom mješovitom shemom: pogreška u prosudbi za urgency ne poništava iznose, ali obrnuto se može dogoditi, jer model koji pogrešno shvati namjeru ponekad čita ostatak kroz tu zabludu. Ako je klasifikacija kritična za tvoje usmjeravanje, odvoji je u zaseban poziv.
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
}
Grupna ekstrakcija
Za obradu velikih volumena paraleliziraj svoje ekstrakcije. Sekvencijalna petlja preko tisuću dokumenata većinu vremena provodi čekajući mrežu; s asyncio, ta se čekanja preklapaju i grupa se obrađuje u djeliću vremena.
Semaforski mehanizam nije ukrasni detalj. Bez njega, pokretanje tisuću zadataka odjednom zasitit će tvoju kvotu i pokrenuti pogreške ograničenja stope (rate limit) koje koštaju više u ponovnim pokušajima nego što štede na brzini. Postavi vrijednost max_concurrent promatranjem vlastitih ograničenja, pri čemu je deset oprezna početna točka. Također obrati pozornost na return_exceptions=True: to sprječava da jedan neispravan dokument sruši cijelu grupu, ostavljajući te da naknadno razvrstaš neuspjehe.
import asyncio
from openai import AsyncOpenAI
async_client = AsyncOpenAI()
async def extract_batch(texts: list[str], schema: dict,
max_concurrent: int = 10) -> list[dict]:
"""Paralelna ekstrakcija s kontrolom konkurentnosti."""
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="Ekstrahiraj entitete iz priloženog teksta. "
"Koristi null za polja koja nedostaju.",
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)
Evaluacija kvalitete ekstrakcije
Cjevovod za ekstrakciju bez anotiranog testnog skupa je cjevovod čiju pouzdanost nitko ne poznaje, a dojam koji ostave tri primjera pročitana ručno gotovo se uvijek pokaže previše optimističnim. Funkcija u nastavku uspoređuje dobivenu ekstrakciju polje po polje s ručno utvrđenom referencom, vraćajući ukupnu preciznost zajedno s raščlambom odstupanja.
Ta raščlamba je korisni dio: pogreške gotovo nikada nisu ravnomjerno raspoređene. Jedno polje koncentrira probleme—često dvosmislen datum, implicitna razina vještine ili loše definirana kategorija—i jedna jedina rečenica dodana u sistemski uput popravlja to. Bez ovog mjerenja nasumično bi prilagođavao upit, moguće pogoršavajući polje koje je već radilo.
def evaluate_extraction(expected: dict, obtained: dict,
fields: list[str]) -> dict:
"""Uspoređuje dobivenu ekstrakciju s referencom."""
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
}
Izgradi svoju referencu prije optimizacije
Odaberi vrstu dokumenta iz svoje domene—ugovore, račune, izvješća—i definiraj shemu ekstrakcije od najmanje deset polja, namjerno miješajući jednostavna polja s onima za koja znaš da su dvosmislena. Sastavi pet primjera dokumenata s njihovim očekivanim ekstrakcijama, napisanim ručno: ovaj je korak dosadan, traje sat vremena, i to je ono što daje vrijednost svom daljnjem radu.
Zatim pokreni cjevovod, izmjeri preciznost i pročitaj popis pogrešaka polje po polje. Najneispravnije polje reći će ti što ispraviti u upitu; drugo mjerenje reći će ti je li ispravak zapravo pomogao—ili je li degradirao drugo polje u procesu, što se događa češće nego što bi mogao pomisliti čim dodatna uputa pomakne pažnju modela.
Ključne točke
- Strukturirana ekstrakcija zamjenjuje namjenske NER modele za većinu slučajeva uporabe
- Koristi
temperature=0.0za maksimiziranje dosljednosti - Učini opcionalna polja nullable umjesto optional
- Paraleliziraj s asyncio za velike volumene
- Sustavno evaluiraj kvalitetu s anotiranim testnim skupom
- Upute u sistemskom upitu usmjeravaju sadržaj, shema ograničava strukturu