Estrazzjoni Strutturata ta' Entitajiet
F'din il-paġna
Lezzjoni aġġornata fit-3 ta’ Novembru 2026 abbażi tad-dokumentazzjoni ta’ OpenAI:
temperatureutop_phuma aċċettati biss b’sforz ta’ raġunar ta’none, filwaqt li l-mudelli GPT-5.6 jirraġunaw b’mod awtomatiku (medium). Għalhekk, is-sejħiet li jistabbilixxu dawn il-parametri jridu jispeċifikawreasoning={"effort": "none"}(Responses API) jewreasoning_effort="none"(Chat Completions). Sorsi: L-użu ta’ GPT-6 · GPT-5.6 Terra.
Estrazzjoni Strutturata ta’ Entitajiet
L-estrazzjoni strutturata ta’ entitajiet hija waħda mill-każijiet ta’ użu l-aktar mitluba fil-produzzjoni: it-trasformazzjoni ta’ test liberu (emails, dokumenti, paġni tal-web) f’data li l-applikazzjoni tiegħek tista’ tuża verament. Billi tgħaqqad l-Output Strutturat ma’ prompts speċjalizzati, tista’ tibni pipelines ta’ estrazzjoni affidabbli mingħajr ma tħarreġ mudell NER iddedikat.
Pipeline Bażika ta’ Estrazzjoni
L-ispeċifiċità kollha tal-estrazzjoni tinsab fil-prompt tas-sistema tal-funzjoni hawn taħt, u din tiġbor attenzjoni mill-qrib. Hawnhekk jikkoinċidu tliet istruzzjonijiet: estraj biss dak li huwa preżenti, uża null għad-data nieqsa, u qatt ma tiddeduċi informazzjoni li mhijiex imsemmija b’mod espliċitu.
Dik l-aħħar sentenza hija l-aktar waħda importanti fil-prattika. Jekk jitħalla għal rasu, mudell jimla b’mod ferħan numru SIRET plawżibbli jew jissuspetta belt minn kodiċi postali, bl-aħjar intenzjonijiet. Għal estrazzjoni maħsuba għal sistema tan-negozju, din l-għajnuna hija difett serju: ladarba d-data tkun fid-database, ma jkun hemm l-ebda mod biex tiddistingwi x’inhu moqri minn x’inhu preżunt. Li tistabbilixxi temperature għal 0.0 jservi l-istess skop—fuq żewġ ġirjiet tal-istess dokument, trid l-istess output, anki biss biex tirriproduċi inċident.
import json
from openai import OpenAI
client = OpenAI()
def extract_entities(text: str, schema: dict,
instructions: str = "") -> dict:
"""Testraġġi entitajiet strutturati minn test liberu."""
system = (
"Inti estrattur speċjalizzat ta' entitajiet. "
"Estraj BISS informazzjoni preżenti fit-test. "
"Jekk informazzjoni tkun nieqsa, uża null. "
"QATT ma tiddeduċi informazzjoni mhux imsemmija b'mod espliċitu."
)
if instructions:
system += f"\n\nIstruzzjonijiet addizzjonali: {instructions}"
response = client.responses.create(
model="gpt-5.6-terra",
reasoning={"effort": "none"}, # temperature requires effort none
instructions=system,
input=f"Test biex jiġi analizzat:\n\n{text}",
text={
"format": {
"type": "json_schema",
"name": "extraction",
"schema": schema,
"strict": True
}
},
temperature=0.0
)
return json.loads(response.output_text)
Eżempju 1: Estrazzjoni ta’ Kurrikulum Vitae
Kurrikulum vitae huwa post eċċellenti għall-ittestjar għax jgħaqqad taqsimiet stabbli ma’ layout kompletament liberu. L-iskema hawn taħt tiġbor id-dettalji tal-kuntatt f’oġġett identity fejn kważi kull qasam huwa nullable—kandidat jista’ ma jipprovdix numru tat-telefon, u li tagħmel dak il-qasam meħtieġ essenzjalment tistieden lill-mudell biex jinventa wieħed.
Il-ħiliet mhumiex sekwenzi sempliċi iżda oġġetti b’tliet attributi, li jippermettilek li tippreserva l-livell iddikjarat u tikkategorizza kull ħila. Mingħajr dawn l-enums, “Scrum” u “Python” jispiċċaw ħdejn xulxin fl-istess lista ċatta, inutli għal filtru li jipprova jiżola l-lingwi. Innota wkoll il-qasam end_date fl-esperjenzi, li huwa nullable filwaqt li start_date mhux hekk: hekk tikkodifika pożizzjoni attwali mingħajr ma tinventa konvenzjoni homemade bħal “present” jew “9999”. Fuq il-CV tat-test, din is-sottilezza tidher fil-linja ta’ 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)
Eżempju 2: Estrazzjoni ta’ Email Kummerċjali
It-tieni eżempju jbiddel in-natura: m’aħniex biss qed nikkupjaw informazzjoni, qed nitolbu lill-mudell jinterpreta. intent u urgency huma ġudizzji—l-ebda sentenza fl-email ma tgħid “din hija talba għal kwotazzjoni, prijorità għolja”. Dan huwa preċiżament dak li pipeline klassika ta’ estrazzjoni bbażata fuq regoli jew espressjonijiet regolari ma tistax tagħmel, u huwa eżattament dak li jiġġustifika l-użu ta’ LLM hawnhekk minflok f’postijiet oħra.
Il-bqija tal-iskema terġa’ lura għal fatti verifikabbli: prodotti msemmija, ammonti bil-kuntest tagħhom, dati u s-sinifikat tagħhom, azzjonijiet meħtieġa. Il-qasam summary jagħlaq l-oġġett u jservi lill-bniedem li se jirrevedi l-kju, mhux lill-kodiċi. Punt ta’ viġilanza ma’ din l-iskema mħallta: żball ta’ ġudizzju fuq urgency ma jinvalidax l-ammonti, iżda l-maqlub jista’ jiġri, għax mudell li jifhem ħażin l-intent xi kultant jaqra l-bqija permezz ta’ dik il-fehma żbaljata. Jekk il-klassifikazzjoni hija kritika għar-routing tiegħek, ifredha f’sejħa ddedikata.
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
}
Estrazzjoni f’Lotti
Biex tipproċessa volumi kbar, parallellizza l-estrazzjonijiet tiegħek. Loop sekwenzjali fuq elf dokument iqatta’ ħafna mill-ħin jistenna n-netwerk; b’asyncio, dawn l-istenji jikkoinċidu u l-lott jiġi pproċessat f’frazzjoni tal-ħin.
Is-semaforu mhux dettall dekorattiv. Mingħajru, it-tnedija ta’ elf kompitu f’daqqa waħda tissatura l-kwota tiegħek u tikkawża żbalji ta’ limitu tar-rata li jiswew aktar fir-ritentattivi milli jiffrankaw fil-veloċità. Stabbilixxi l-valur max_concurrent billi tosserva l-limiti tiegħek stess, b’għaxra tkun punt tat-tluq kawt. Innota wkoll return_exceptions=True: dan jipprevjeni dokument wieħed bil-ħsara milli jwaqqa’ l-lott kollu, u jħallik issolvi l-fallimenti wara.
import asyncio
from openai import AsyncOpenAI
async_client = AsyncOpenAI()
async def extract_batch(texts: list[str], schema: dict,
max_concurrent: int = 10) -> list[dict]:
"""Estrazzjoni parallela b'kontroll tal-konkorrenza."""
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="Estraj entitajiet mit-test ipprovdut. "
"Uża null għall-oqsma nieqsa.",
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)
Evalwazzjoni tal-Kwalità tal-Estrazzjoni
Pipeline ta’ estrazzjoni mingħajr sett ta’ test annotat hija pipeline li l-ebda ħadd ma jaf kemm hija affidabbli, u l-impressjoni li jħallu tliet eżempji moqrija bl-idejn kważi dejjem tirriżulta ottimista wisq. Il-funzjoni hawn taħt tqabbel kamp b’kamp estrazzjoni miksuba ma’ referenza stabbilita manwalment, u tirritorna preċiżjoni ġenerali flimkien ma’ breakdown tad-diskrepanzi.
Dan il-breakdown huwa l-parti utli: l-iżbalji kważi qatt ma huma mqassma b’mod uniformi. Qasam wieħed jikkonċentra l-problemi—spiss data ambigwa, livell ta’ ħila impliċitu, jew kategorija definita ħażin—u sentenza waħda miżjuda fil-prompt tas-sistema tirranġaha. Mingħajr din il-kejl, tkun qed ittajjar il-prompt b’mod każwali, u possibbilment taggrava qasam li diġà kien qed jaħdem.
def evaluate_extraction(expected: dict, obtained: dict,
fields: list[str]) -> dict:
"""Tqabbel l-estrazzjoni miksuba mar-referenza."""
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
}
Ibni r-Referenza Tiegħek Qabel ma Toptimizza
Agħżel tip ta’ dokument mid-dominju tiegħek—kuntratti, fatturi, rapporti—u ddefinixxi skema ta’ estrazzjoni ta’ mill-inqas għaxar oqsam, li tħallat b’mod deliberat oqsma faċli ma’ dawk li taf li huma ambigwi. Assembla ħames dokumenti eżempju bl-estrazzjonijiet mistennija tagħhom, miktuba bl-idejn: dan il-pass huwa tedjanti, jieħu siegħa, u huwa dak li jagħti valur lix-xogħol kollu sussegwenti.
Imbagħad ġarri l-pipeline, kejjel il-preċiżjoni, u aqra l-lista ta’ żbalji qasam b’qasam. Il-qasam l-aktar difettuż jgħidlek x’għandek tikkoreġi fil-prompt; kejl it-tieni jgħidlek jekk il-korrezzjoni għinitx verament—jew jekk iddegradatx qasam ieħor fil-proċess, li jiġri aktar spiss milli taħseb hekk kif istruzzjoni addizzjonali tbiddel l-attenzjoni tal-mudell.
Punti Ewlenin
- L-estrazzjoni strutturata tissostitwixxi mudelli NER iddedikati għall-biċċa l-kbira tal-każijiet ta’ użu
- Uża
temperature=0.0biex timmassimizza l-konsistenza - Agħmel l-oqsma opzjonali nullable minflok opzjonali
- Parallellizza b’asyncio għal volumi kbar
- Evalwa sistematikament il-kwalità b’sett ta’ test annotat
- L-istruzzjonijiet tal-prompt tas-sistema jiggwidaw il-kontenut, l-iskema tillimita l-istruttura