Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Strukturirano pridobivanje entitet

Lekcija 13 od 16 Posodobljeno 3. november 2026 Razvijalec
Na tej strani
  1. Strukturirano pridobivanje entitet
  2. Osnovni cevovod za pridobivanje
  3. Primer 1: Pridobivanje podatkov iz življenjepisa
  4. Primer 2: Pridobivanje podatkov iz poslovnega e-poštnega sporočila
  5. Serijsko pridobivanje
  6. Ocena kakovosti pridobivanja
  7. Pred optimizacijo zgradi svojo referenco
  8. Ključne ugotovitve

Lekcija posodobljena 3. novembra 2026 na podlagi dokumentacije OpenAI: parametra temperature in top_p sta sprejeta le pri naporu razmišljanja (reasoning effort) vrednosti none, medtem ko modeli GPT-5.6 privzeto razmišljajo (medium). Klici, ki nastavljajo te parametre, morajo zato določiti reasoning={"effort": "none"} (Responses API) ali reasoning_effort="none" (Chat Completions). Viri: Uporaba GPT-6 · GPT-5.6 Terra.

Strukturirano pridobivanje entitet

Strukturirano pridobivanje entitet je eden najbolj zahtevanih primerov uporabe v proizvodnem okolju: pretvorba prostega besedila (e-pošta, dokumenti, spletne strani) v podatke, ki jih tvoja aplikacija dejansko lahko uporabi. S kombinacijo strukturiranega izhoda in specializiranih pozivov lahko zgradiš zanesljive cevovode za pridobivanje podatkov, ne da bi moral trenirati namenski model NER.

Osnovni cevovod za pridobivanje

Vsa specifičnost pridobivanja leži v sistemskem pozivu spodnje funkcije in ta si zasluži posebno pozornost. Tu se prekrivajo tri navodila: izvleci samo tisto, kar je prisotno; za manjkajoče podatke uporabi null; in nikoli ne sklepay informacij, ki niso izrecno omenjene.

Zadnji stavek je v praksi najpomembnejši. Če ga prepustiš samemu sebi, bo model z veseljem izpolnil verjetno številko SIRET ali uganil mesto na podlagi telefonske predpone, in to z najboljšimi nameni. Za pridobivanje, namenjeno poslovnemu sistemu, je ta uslužnost resna pomanjkljivost: ko so enkrat podatki v zbirki, ni več mogoče razlikovati med tem, kar je bilo prebrano, in tem, kar je bilo predpostavljeno. Nastavitev temperature na 0,0 služi istemu namenu – pri dveh zagonih istega dokumenta želiš enak izhod, če že zaradi ničesar drugega, potem vsaj zaradi možnosti reproduciranja incidenta.

import json
from openai import OpenAI

client = OpenAI()

def extract_entities(text: str, schema: dict,
                     instructions: str = "") -> dict:
    """Izvleče strukturirane entitete iz prostega besedila."""
    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)

Primer 1: Pridobivanje podatkov iz življenjepisa

Življenjepis je odlično testno okolje, ker združuje stabilne razdelke s popolnoma prosto obliko. Spodnja shema združuje kontaktne podatke v objekt identity, kjer je skoraj vsako polje nullable – kandidat morda ne bo navedel telefonske številke in če bi to polje zahteval, bi model v bistvu povabil k izmišljanju.

Veščine niso preprosti nizi, temveč objekti s tremi atributi, kar ti omogoča ohranjanje navedene ravni in kategorizacijo vsake veščine. Brez teh enumeracij bi se „Scrum” in „Python” znašla drug ob drugem v istem ravnem seznamu, kar je neuporabno za filter, ki poskuša izolirati programske jezike. Opazi tudi polje end_date v izkušnjah, ki je nullable, medtem ko start_date ni: tako kodiraš trenutno delovno mesto, ne da bi izmišljal domače konvencije, kot sta „present” ali „9999”. Pri testnem življenjepisu se ta subtilnost pokaže pri vrstici 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)

Primer 2: Pridobivanje podatkov iz poslovnega e-poštnega sporočila

Drugi primer spremeni naravo: ne kopiramo več le informacij, temveč od modela zahtevamo interpretacijo. intent (namen) in urgency (nujnost) sta sodbi – noben stavek v e-pošti ne pravi „to je zahtevek za ponudbo, visoka prioriteta”. To je ravno tisto, česar klasični cevovod za pridobivanje, temelječ na pravilih ali regularnih izrazih, ne zmore, in to je točno tisto, kar upravičuje uporabo LLM tukaj in ne drugje.

Preostanek sheme se vrača k preverljivim dejstvom: omenjeni proizvodi, zneski z njihovim kontekstom, datumi in njihov pomen, zahtevana dejanja. Polje summary zaključuje objekt in služi človeku, ki bo pregledal čakalno vrsto, ne kodi. Ena točka previdnosti pri tej mešani shemi: napaka pri presoji urgency ne razveljavi zneskov, lahko pa se zgodi obratno, saj model, ki napačno razume namen, včasih skozi to zmoto bere tudi ostalo. Če je razvrščanje ključno za tvoje usmerjanje, ga loči v namenski klic.

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
}

Serijsko pridobivanje

Za obdelavo velikih količin paraleliziraj svoja pridobivanja. Zaporedna zanka čez tisoč dokumentov večino časa porabi za čakanje na omrežje; z asyncio se ta čakanja prekrivajo in serija se obdela v delčku časa.

Semaforski mehanizem ni okrasna podrobnost. Brez njega bo zagon tisočih opravil hkrati zasičil tvojo kvoto in sprožil napake omejitve hitrosti, ki stanejo več pri ponovnih poskusih, kot prihranijo pri hitrosti. Vrednost max_concurrent nastavi tako, da opazuješ svoje lastne omejitve, pri čemer je deset previden začetni korak. Opazi tudi return_exceptions=True: prepreči, da bi en sam nepravilno oblikovan dokument sesul celotno serijo, tebi pa prepusti razvrščanje napak naknadno.

import asyncio
from openai import AsyncOpenAI

async_client = AsyncOpenAI()

async def extract_batch(texts: list[str], schema: dict,
                          max_concurrent: int = 10) -> list[dict]:
    """Paralelno pridobivanje z nadzorom sočasnosti."""
    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)

Ocena kakovosti pridobivanja

Cevovod za pridobivanje brez anotiranega testnega niza je cevovod, katerega zanesljivosti nihče ne pozna, in vtis, ki ga pustijo trije ročno prebrani primeri, se skoraj vedno izkaže za preveč optimističen. Spodnja funkcija primerja dobljeno pridobivanje polje za poljem z ročno določeno referenco in vrne splošno natančnost ter razčlenitev neskladij.

Ta razčlenitev je uporabni del: napake skoraj nikoli niso enakomerno porazdeljene. Eno polje koncentrira težave – pogosto dvoumen datum, implicitna raven veščine ali slabo opredeljena kategorija – in en sam stavek, dodan sistemskemu pozivu, to popravi. Brez tega merjenja bi naključno prilagajal poziv in morda poslabšal polje, ki je že delovalo.

def evaluate_extraction(expected: dict, obtained: dict,
                       fields: list[str]) -> dict:
    """Primerja dobljeno pridobivanje z referenco."""
    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 optimizacijo zgradi svojo referenco

Izberi vrsto dokumenta iz svoje domene – pogodbe, računi, poročila – in opredeli shemo za pridobivanje z vsaj desetimi polji, pri čemer namerno pomešaj enostavna polja s tistimi, za katera veš, da so dvoumna. Zberi pet primerov dokumentov z njihovimi pričakovanimi pridobitvami, napisanimi ročno: ta korak je dolgočasen, traja uro in prav on daje vrednost vsemu nadaljnjemu delu.

Nato zaženi cevovod, izmeri natančnost in preberi seznam napak polje za poljem. Najbolj pomanjkljivo polje ti bo povedalo, kaj popraviti v pozivu; druga meritev ti bo povedala, ali je popravek dejansko pomagal – ali pa je poslabšal drugo polje v procesu, kar se zgodi pogosteje, kot si misliš, takoj ko dodatno navodilo premakne pozornost modela.

Ključne ugotovitve

  • Strukturirano pridobivanje nadomešča namenske modele NER za večino primerov uporabe
  • Uporabi temperature=0.0 za maksimiranje doslednosti
  • Polja, ki niso obvezna, naj bodo nullable, ne pa opcijska
  • Za velike količine uporabi paralelizacijo z asyncio
  • Sistematično ocenjuj kakovost z anotiranim testnim nizom
  • Navodila v sistemskem pozivu usmerjajo vsebino, shema omejuje strukturo