Struktureeritud üksuste ekstraheerimine
Sellel lehel
Õppetund uuendatud 3. novembril 2026 OpenAI dokumentatsiooni põhjal: parameetreid
temperaturejatop_paktsepteeritakse ainult arutluskäigu tasemelnone, samas kui GPT-5.6 mudelid kasutavad vaikimisi arutluskäiku (medium). Seetõttu peavad need parameetrid määravad päringud sisaldamareasoning={"effort": "none"}(Responses API) võireasoning_effort="none"(Chat Completions). Allikad: GPT-6 kasutamine · GPT-5.6 Terra.
Struktureeritud üksuste ekstraheerimine
Struktureeritud üksuste ekstraheerimine on tootmiskeskkonnas üks nõutumaid kasutusjuhte: vaba teksti (meilid, dokumendid, veebilehed) teisendamine andmeteks, mida sinu rakendus tegelikult kasutada saab. Kombineerides struktureeritud väljundi spetsiaalsete vihjetega, saad luua usaldusväärseid ekstraheerimise torustikke ilma spetsiaalset NER-mudelit treenimata.
Põhiline ekstraheerimise torustik
Kogu ekstraheerimise eripära peitub allpool oleva funktsiooni süsteemivihjes ja see väärib põhjalikku tähelepanu. Siin kattuvad kolm juhist: ekstraheeri ainult see, mis on olemas; kasuta puuduvate andmete korral null ja ära kunagi järelda teavet, mida ei ole sõnaselgelt mainitud.
Viimane lause on praktikas kõige olulisem. Omapead jäetuna täidab mudel hea meelega usutava SIRET-numbri või arvab piirkonnakoodi põhjal linna, parimate kavatsustega. Ärisüsteemi mõeldud ekstraheerimisel on see abivalmidus tõsine viga: kui andmed on andmebaasis, pole võimalik eristada, mis loeti ja mis oletati. Parameetri temperature väärtuseks 0.0 seadmine teenib sama eesmärki – sama dokumendi kahe töötluskorra puhul soovid sama väljundit, kasvõi intsidenti reprodutseerimiseks.
import json
from openai import OpenAI
client = OpenAI()
def extract_entities(text: str, schema: dict,
instructions: str = "") -> dict:
"""Ekstraheerib struktureeritud üksused vabast tekstist."""
system = (
"Oled spetsialiseerunud üksuste ekstraheerija. "
"Ekstraheeri AINULT tekstis leiduvat teavet. "
"Kui teave puudub, kasuta null. "
"ÄRA KUNAGI järelda teavet, mida ei ole sõnaselgelt mainitud."
)
if instructions:
system += f"\n\nLisajuhised: {instructions}"
response = client.responses.create(
model="gpt-5.6-terra",
reasoning={"effort": "none"}, # temperature nõuab effort none
instructions=system,
input=f"Analüüsitav tekst:\n\n{text}",
text={
"format": {
"type": "json_schema",
"name": "extraction",
"schema": schema,
"strict": True
}
},
temperature=0.0
)
return json.loads(response.output_text)
Näide 1: CV ekstraheerimine
CV on suurepärane katsepolügoon, kuna see ühendab stabiilsed lõigud täiesti vabas vormingus paigutusega. Allpool olev skeem rühmitab kontaktandmed objektiks identity, kus peaaegu iga väli võib olla nullväärtusega – kandidaat võib jätta telefoninumbri esitamata ja selle välja kohustuslikuks muutmine kutsuks mudelit sisuliselt seda välja mõtlema.
Oskused ei ole lihtsalt stringid, vaid kolme atribuudiga objektid, mis võimaldab säilitada deklareeritud taseme ja kategoriseerida iga oskuse. Ilma nende loenditeta oleksid „Scrum“ ja „Python“ kõrvuti samas lamedas loetelus, mis on filtrile keelte eraldamiseks kasutu. Pane tähele ka välja end_date kogemuste puhul, mis võib olla null, samas kui start_date ei saa: nii kodeerid praeguse ametikoha ilma omaloodud kokkuleppeid nagu „present“ või „9999“ leiutamata. Test-CV puhul mängib see peenus välja TechCorp real.
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)
Näide 2: Ärikirja ekstraheerimine
Teine näide muudab olemust: me ei kopeeri enam lihtsalt teavet, vaid palume mudelil tõlgendada. intent (eesmärk) ja urgency (kiireloomulisus) on hinnangud – üheski kirja lauses ei öelda „see on hinnapakkumise taotlus, kõrge prioriteet“. See on täpselt see, mida reeglitel või regulaaravaldistel põhinev klassikaline ekstraheerimise torustik teha ei suuda, ja see ongi põhjus, miks kasutada siin LLM-i, mitte mujal.
Ülejäänud skeem pöördub tagasi kontrollitavate faktide juurde: mainitud tooted, summad koos kontekstiga, kuupäevad ja nende tähendus, nõutavad tegevused. Väli summary sulgeb objekti ja teenib inimest, kes järjekorda üle vaatab, mitte koodi. Selle segaskeemi puhul on üks valvsust nõudev punkt: vea tegemine urgency hindamisel ei muuda summasid kehtetuks, kuid vastupidine võib juhtuda, sest mudel, mis ei mõista eesmärki õigesti, loeb mõnikord ülejäänut läbi selle eksiarvamuse. Kui klassifitseerimine on sinu marsruutimise jaoks kriitiline, eralda see eraldi päringuks.
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
}
Pakktöötlus
Suurte mahtude töötlemiseks paralleliseeri oma ekstraheerimised. Järjestikune tsükkel tuhande dokumendi üle veedab suurema osa ajast võrgu ootamises; asyncio abil need ooteajad kattuvad ja partii töödeldakse murdosa ajaga.
Semaphor ei ole dekoratiivne detail. Ilma selma tuhande ülesande korraga käivitamine küllastab sinu kvoodi ja käivitab kiiruse piirangu vea, mille korduskatsed maksavad rohkem kui need kiiruses säästavad. Määra max_concurrent väärtus oma piiranguid jälgides, kusjuures kümme on ettevaatlik alguspunkt. Pane tähele ka return_exceptions=True: see takistab ühel vigasel dokumendil kogu partii kokku jooksmast, jättes sulle võimaluse tõrked hiljem lahendada.
import asyncio
from openai import AsyncOpenAI
async_client = AsyncOpenAI()
async def extract_batch(texts: list[str], schema: dict,
max_concurrent: int = 10) -> list[dict]:
"""Parallelne ekstraheerimine samaaegsuse kontrolliga."""
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 nõuab effort none
instructions="Ekstraheeri üksused esitatud tekstist. "
"Kasuta puuduvate väljade korral null.",
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)
Ekstraheerimise kvaliteedi hindamine
Ekstraheerimise torustik ilma annoteeritud testkomplektita on torustik, mille usaldusväärsust keegi ei tea, ja kolme käsitsi loetud näite jäetud mulje osutub peaaegu alati liiga optimistlikuks. Allpool olev funktsioon võrdleb saadud ekstraheerimist väljahaaval käsitsi koostatud võrdlusalusega, tagastades üldise täpsuse koos lahknevuste jaotusega.
See jaotus on kasulik osa: vead ei ole peaaegu kunagi ühtlaselt jaotunud. Üks väli koondab probleeme – sageli on see mitmetimõistetav kuupäev, varjatud oskuste tase või halvasti defineeritud kategooria – ja üks süsteemivihjele lisatud lause parandab selle. Ilma selle mõõtmiseta häälestaksid vihjet juhuslikult, võimalik, et halvendades välja, mis juba toimis.
def evaluate_extraction(expected: dict, obtained: dict,
fields: list[str]) -> dict:
"""Võrdleb saadud ekstraheerimist võrdlusalusega."""
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
}
Loo oma võrdlusalus enne optimeerimist
Vali oma valdkonnast dokumenditüüp – lepingud, arved, aruanded – ja defineeri vähemalt kümne väljaga ekstraheerimise skeem, segades tahtlikult lihtsaid välju nendega, mille puhul tead, et need on mitmetimõistetavad. Koosta viis näidisdokumenti koos nende oodatavate ekstraheerimistega, kirjutatuna käsitsi: see samm on tüütu, võtab aega tunni, kuid see annab kogu järgnevale tööle väärtuse.
Seejärel käivita torustik, mõõda täpsust ja loe vigade loendit väljahaaval. Kõige vigasem väli ütleb sulle, mida vihjes parandada; teine mõõtmine näitab, kas parandus tegelikult aitas – või kas see halvenes teist välja protsessi käigus, mis juhtub sagedamini, kui arvata oskad, niipea kui täiendav juhise nihutab mudeli tähelepanu.
Peamised punktid
- Struktureeritud ekstraheerimine asendab enamiku kasutusjuhtude puhul spetsiaalseid NER-mudeleid
- Kasuta
temperature=0.0, et maksimeerida järjepidevust - Tee valikulised väljad nullitavaks, mitte valikuliseks
- Paralleliseeri suurte mahtude jaoks
asyncioabil - Hinda kvaliteeti süstemaatiliselt annoteeritud testkomplektiga
- Süsteemivihje juhised suunavad sisu, skeem piirab struktuuri