Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Estrazzjoni Strutturata ta' Entitajiet

Lezzjoni 13 / 16 Aġġornat 3 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. Estrazzjoni Strutturata ta’ Entitajiet
  2. Pipeline Bażika ta’ Estrazzjoni
  3. Eżempju 1: Estrazzjoni ta’ Kurrikulum Vitae
  4. Eżempju 2: Estrazzjoni ta’ Email Kummerċjali
  5. Estrazzjoni f’Lotti
  6. Evalwazzjoni tal-Kwalità tal-Estrazzjoni
  7. Ibni r-Referenza Tiegħek Qabel ma Toptimizza
  8. Punti Ewlenin

Lezzjoni aġġornata fit-3 ta’ Novembru 2026 abbażi tad-dokumentazzjoni ta’ OpenAI: temperature u top_p huma 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ċifikaw reasoning={"effort": "none"} (Responses API) jew reasoning_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.0 biex 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