Extragerea structurată a entităților
Pe această pagină
Lecție actualizată la 3 noiembrie 2026 pe baza documentației OpenAI: parametrii
temperatureșitop_psunt acceptați doar cu un efort de raționament denone, în timp ce modelele GPT-5.6 raționează implicit (medium). Apelurile care setează acești parametri trebuie, prin urmare, să specificereasoning={"effort": "none"}(API-ul Responses) saureasoning_effort="none"(Chat Completions). Surse: Utilizarea GPT-6 · GPT-5.6 Terra.
Extragerea structurată a entităților
Extragerea structurată a entităților este unul dintre cele mai solicitate cazuri de utilizare în producție: transformarea textului liber (e-mailuri, documente, pagini web) în date pe care aplicația dumneavoastră le poate utiliza efectiv. Prin combinarea ieșirii structurate cu prompturi specializate, puteți construi fluxuri de extragere fiabile fără a antrena un model NER dedicat.
Fluxul de bază de extragere
Întreaga specificitate a extragerii rezidă în promptul de sistem al funcției de mai jos, iar acesta merită o atenție deosebită. Trei instrucțiuni se suprapun aici: extrageți doar ceea ce este prezent, utilizați null pentru datele lipsă și nu deduceți niciodată informații care nu sunt menționate explicit.
Această ultimă propoziție este cea mai importantă în practică. Lăsat să acționeze singur, un model va completa cu plăcere un număr SIRET plauzibil sau va ghici un oraș pe baza unui cod poștal, cu cele mai bune intenții. Pentru o extragere destinată unui sistem de afaceri, această solicitudine reprezintă un defect grav: odată ce datele se află în baza de date, nu există nicio modalitate de a distinge ceea ce a fost citit de ceea ce a fost presupus. Setarea parametrului temperature la 0.0 servește aceluiași scop—pentru două rulări ale aceluiași document, doriți aceeași ieșire, dacă doar pentru a reproduce un incident.
import json
from openai import OpenAI
client = OpenAI()
def extract_entities(text: str, schema: dict,
instructions: str = "") -> dict:
"""Extrage entități structurate din text liber."""
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)
Exemplul 1: Extragerea din CV-uri
Un CV este un teren de testare excelent deoarece combină secțiuni stabile cu o structură complet liberă. Schema de mai jos grupează detaliile de contact într-un obiect identity în care aproape fiecare câmp poate fi nul—un candidat ar putea să nu furnizeze un număr de telefon, iar definirea acelui câmp ca obligatoriu ar invita, în esență, modelul să inventeze unul.
Competențele nu sunt șiruri simple, ci obiecte cu trei atribute, ceea ce vă permite să păstrați nivelul declarat și să categorisiți fiecare competență. Fără aceste enumerații, „Scrum“ și „Python“ ar ajunge unul lângă altul în aceeași listă plată, fiind inutile pentru un filtru care încearcă să izoleze limbajele. De asemenea, remarcați câmpul end_date din experiențe, care poate fi nul, spre deosebire de start_date care nu este: așa codificați o poziție actuală fără a inventa o convenție proprie precum „prezent“ sau „9999“. În CV-ul de test, această subtilitate se manifestă la linia 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)
Exemplul 2: Extragerea din e-mailuri comerciale
Al doilea exemplu schimbă natura: nu mai copiem doar informații, ci cerem modelului să interpreteze. intent (intenția) și urgency (urgența) sunt judecăți—nicio propoziție din e-mail nu spune „aceasta este o cerere de ofertă, prioritate ridicată“. Acesta este exact ceea ce un flux clasic de extragere bazat pe reguli sau expresii regulate nu poate face și este exact ceea ce justifică utilizarea unui LLM aici și nu în altă parte.
Restul schemei revine la fapte verificabile: produsele menționate, sumele cu contextul lor, datele și semnificația lor, acțiunile necesare. Câmpul summary închide obiectul și servește omului care va revizui coada de așteptare, nu codului. Un punct de vigilență cu această schemă mixtă: o eroare de judecată asupra urgency nu invalidează sumele, dar inversul se poate întâmpla, deoarece un model care înțelege greșit intenția citește uneori restul prin prisma acelei concepții greșite. Dacă clasificarea este critică pentru rutarea dumneavoastră, separați-o într-un apel dedicat.
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
}
Extragerea în loturi
Pentru a procesa volume mari, paralelizați extragerile. O buclă secvențială peste o mie de documente își petrece cea mai mare parte a timpului așteptând rețeaua; cu asyncio, aceste așteptări se suprapun, iar lotul se procesează într-o fracțiune din timp.
Semaforul nu este un detaliu decorativ. Fără el, lansarea a o mie de sarcini simultan vă va satura cota și va declanșa erori de limitare a ratei care costă mai mult în reîncercări decât economisesc în viteză. Stabiliți valoarea max_concurrent observând propriile limite, zece fiind un punct de plecare prudent. De asemenea, remarcați return_exceptions=True: acest lucru împiedică un singur document malformat să blocheze întregul lot, lăsându-vă să sortați eșecurile ulterior.
import asyncio
from openai import AsyncOpenAI
async_client = AsyncOpenAI()
async def extract_batch(texts: list[str], schema: dict,
max_concurrent: int = 10) -> list[dict]:
"""Extragere paralelă cu controlul concurenței."""
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)
Evaluarea calității extragerii
Un flux de extragere fără un set de test anotat este un flux a cărui fiabilitate nu este cunoscută de nimeni, iar impresia lăsată de trei exemple citite manual se doovește aproape întotdeauna prea optimistă. Funcția de mai jos compară un câmp de extragere obținut cu o referință stabilită manual, returnând precizia globală împreună cu o defalcare a discrepanțelor.
Această defalcare este partea utilă: erorile nu sunt aproape niciodată distribuite uniform. Un câmp concentrează problemele—adesea o dată ambiguă, un nivel de competență implicit sau o categorie slab definită—iar o singură propoziție adăugată la promptul de sistem o remediază. Fără această măsurătoare, ați ajusta promptul la întâmplare, riscând posibil să înrăutățiți un câmp care funcționa deja.
def evaluate_extraction(expected: dict, obtained: dict,
fields: list[str]) -> dict:
"""Compară extragerea obținută cu referința."""
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
}
Construiți-vă referința înainte de a optimiza
Alegeți un tip de document din domeniul dumneavoastră—contracte, facturi, rapoarte—și definiți o schemă de extragere de cel puțin zece câmpuri, amestecând deliberat câmpuri ușoare cu unele despre care știți că sunt ambigue. Asamblați cinci documente exemplu cu extragerile lor așteptate, scrise de mână: acest pas este anevoios, durează o oră, dar este ceea ce conferă valoare întregii munci ulterioare.
Apoi rulați fluxul, măsurați precizia și citiți lista de erori câmp cu câmp. Câmpul cel mai defectuos vă va spune ce să corectați în prompt; o a doua măsurătoare vă va spune dacă corecția a ajutat efectiv—sau dacă a degradat un alt câmp în proces, ceea ce se întâmplă mai des decât ați putea crede imediat ce o instrucțiune suplimentară schimbă atenția modelului.
Puncte cheie
- Extragerea structurată înlocuiește modelele NER dedicate pentru majoritatea cazurilor de utilizare
- Utilizați
temperature=0.0pentru a maximiza consistența - Faceți câmpurile opționale să accepte valori nule în loc să fie opționale
- Paralelizați cu asyncio pentru volume mari
- Evaluați sistematic calitatea cu un set de test anotat
- Instrucțiunile din promptul de sistem ghidează conținutul, schema constrânge structura