Rakenteinen entiteettien poiminta
Tällä sivulla
Oppitunti päivitetty 3. marraskuuta 2026 OpenAI:n dokumentaation perusteella:
temperaturejatop_phyväksytään vain, kun päättelypyrkimys onnone, kun taas GPT-5.6-mallit käyttävät oletusarvoisesti päättelyä (medium). Näitä parametreja asettavien kutsujen on siksi määritettäväreasoning={"effort": "none"}(Responses API) taireasoning_effort="none"(Chat Completions). Lähteet: Using GPT-6 · GPT-5.6 Terra.
Rakenteinen entiteettien poiminta
Rakenteinen entiteettien poiminta on yksi tuotantoympäristöjen kysytyimmistä käyttötarkoituksista: vapaan tekstin (sähköpostit, asiakirjat, verkkosivut) muuntaminen dataksi, jota sovelluksesi voi todella hyödyntää. Yhdistämällä rakenteisen tulostuksen erikoistuneisiin kehotteisiin voit rakentaa luotettavia poimintaputkia ilman erillisen NER-mallin kouluttamista.
Peruspoimintaputki
Poiminnan koko erityispiirre piilee alla olevan funktion järjestelmäkehotteessa, ja se ansaitsee tarkkaa huomiota. Tässä limittyvät kolme ohjetta: poimi vain se, mitä tekstissä on, käytä arvoa null puuttuvalle datalle, äläkä koskaan päättele tietoa, jota ei ole nimenomaisesti mainittu.
Viimeinen lause on käytännössä tärkein. Omissa oloissaan malli täyttää mielellään uskottavan SIRET-numeron tai arvaa kaupungin suuntanumeron perusteella parhaalla tarkoituksella. Liiketoimintajärjestelmään tarkoitetussa poiminnassa tämä avuliaisuus on vakava virhe: kun data on tietokannassa, ei ole tapaa erottaa luettua oletetusta. Arvon temperature asettaminen nollaan (0.0) palvelee samaa tarkoitusta – saman asiakirjan kahdessa ajossa haluat saman tulosteen, jos vain siksi, että voit toistaa vikatilanteen.
import json
from openai import OpenAI
client = OpenAI()
def extract_entities(text: str, schema: dict,
instructions: str = "") -> dict:
"""Poimii rakenteisia entiteettejä vapaasta tekstistä."""
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)
Esimerkki 1: Ansioluettelon poiminta
Ansioluettelo on erinomainen testialusta, koska se yhdistää vakaita osioita täysin vapaamuotoiseen asetteluun. Alla oleva skeema ryhmittää yhteystiedot identity-objektiin, jossa lähes jokainen kenttä voi olla null-arvoinen – ehdokas ei välttämättä anna puhelinnumeroa, ja kentän pakolliseksi tekeminen kutsuisi mallia keksimään sellaisen.
Taidot eivät ole pelkkiä merkkijonoja, vaan objekteja, joissa on kolme attribuuttia. Tämä mahdollistaa ilmoitetun tason säilyttämisen ja kunkin taidon luokittelun. Ilman näitä enum-arvoja “Scrum” ja “Python” päätyisivät vierekkäin samaan litteään listaan, mikä on hyödytöntä suodattimelle, joka yrittää eristää ohjelmointikieliä. Huomaa myös end_date-kenttä kokemuksissa: se voi olla null, kun taas start_date ei voi. Näin koodaat nykyisen tehtävän ilman, että keksit omia käytäntöjä kuten “present” tai “9999”. Testiansioluettelossa tämä hienovaraisuus näkyy TechCorp-rivillä.
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)
Esimerkki 2: Kaupallisen sähköpostin poiminta
Toinen esimerkki muuttaa luonnetta: emme enää vain kopioi tietoa, vaan pyydämme mallia tulkitsemaan. intent (tarkoitus) ja urgency (kiireellisyys) ovat arvioita – mikään lause sähköpostissa ei sano “tämä on tarjouspyyntö, korkea prioriteetti”. Tämä on juuri se, mitä sääntöihin tai säännöllisiin lausekkeisiin perustuva klassinen poimintaputki ei pysty tekemään, ja se on täsmälleen se, mikä oikeuttaa LLM:n käytön tässä eikä muualla.
Skeeman loppuosa palaa varmennettaviin faktoihin: mainitut tuotteet, summat konteksteineen, päivämäärät ja niiden merkitys, vaaditut toimet. summary-kenttä päättää objektin ja palvelee ihmistä, joka tarkistaa jonon, ei koodia. Yksi tarkkailun aihe tämäntyyppisessä sekaskeemassa: virheellinen arvio urgency-kentästä ei mitätöi summia, mutta päinvastoin voi tapahtua, koska malli, joka ei ymmärrä tarkoitusta, saattaa lukea loput tämän väärinkäsityksen läpi. Jos luokittelu on reitityksellesi kriittistä, erota se omaan kutsuunsa.
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
}
Eräpoiminta
Käsitelläksesi suuria määriä, rinnakkaista poimintasi. Tuhat asiakirjaa läpikäyvä sekvenssiluuppi käyttää suurimman osan ajastaan verkon odotteluun; asyncio:n avulla nämä odotukset limittyvät ja erä käsitellään murto-osassa ajasta.
Semafori ei ole koriste. Ilman sitä tuhannen tehtävän käynnistäminen kerralla kyllästää kiintiösi ja laukaisee nopeusrajoitusvirheitä, jotka maksavat uudelleenyrityksissä enemmän kuin säästävät nopeudessa. Aseta max_concurrent-arvo tarkkailemalla omia rajojasi; kymmenen on varovainen lähtökohta. Huomaa myös return_exceptions=True: se estää yhtä vioittunutta asiakirjaa kaatamasta koko erää, jolloin voit selvittää epäonnistumiset jälkikäteen.
import asyncio
from openai import AsyncOpenAI
async_client = AsyncOpenAI()
async def extract_batch(texts: list[str], schema: dict,
max_concurrent: int = 10) -> list[dict]:
"""Rinnakkainen poiminta samanaikaisuuden hallinnalla."""
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)
Poiminnan laadun arviointi
Poimintaputki, jolla ei ole annotoitua testijoukkoa, on putki, jonka luotettavuudesta kukaan ei tiedä mitään, ja kolmen käsin luetun esimerkin jättämä vaikutelma osoittautuu lähes aina liian optimistiseksi. Alla oleva funktio vertaa saatua poimintaa kenttä kerrallaan manuaalisesti laadittuun vertailukohtaan ja palauttaa yleisen tarkkuuden sekä poikkeamien erittelyn.
Tämä erittely on hyödyllinen osa: virheet eivät jakaudu lähes koskaan tasaisesti. Yksi kenttä keskittää ongelmat – usein monitulkintainen päivämäärä, implisiittinen taitotaso tai huonosti määritelty kategoria – ja yksi järjestelmäkehotteeseen lisätty lause korjaa sen. Ilman tätä mittausta hienosäätäisit kehotetta sattumanvaraisesti ja saattaisit jopa heikentää kenttää, joka jo toimi.
def evaluate_extraction(expected: dict, obtained: dict,
fields: list[str]) -> dict:
"""Vertaa saatua poimintaa vertailukohtaan."""
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
}
Rakenna vertailukohtasi ennen optimointia
Valitse toimialaltasi asiakirjatyyppi – sopimukset, laskut, raportit – ja määrittele vähintään kymmenen kentän poimintaskaema sekoittaen tarkoituksellisesti helppoja kenttiä sellaisiin, joiden tiedät olevan monitulkintaisia. Kokoa viisi esimerkkiasiakirjaa niiden odotetuilla poiminnoilla, kirjoitettuna käsin: tämä vaihe on työläs, se vie tunnin, ja se on se, mikä antaa kaiken myöhemmän työn arvon.
Suorita sitten putki, mittaa tarkkuus ja lue virhelista kenttä kerrallaan. Eniten virheitä tuottava kenttä kertoo, mitä kehotteessa pitää korjata; toinen mittaus kertoo, auttoiko korjaus todella – vai heikensikö se toista kenttää prosessin aikana, mitä tapahtuu useammin kuin luulisi heti, kun lisäohje siirtää mallin huomion.
Keskeiset asiat
- Rakenteinen poiminta korvaa omistetut NER-mallit useimmissa käyttötarkoituksissa
- Käytä arvoa
temperature=0.0maksimoidaksesi johdonmukaisuuden - Tee valinnaisista kentistä null-arvoisia äläkä valinnaisia
- Rinnakkaista
asyncio:lla suurten määrien käsittely - Arvioi laatua systemaattisesti annotoidulla testijoukolla
- Järjestelmäkehotteen ohjeet ohjaavat sisältöä, skeema rajoittaa rakennetta