Extraction structurée d'entités
På denna sida
Leçon mise à jour le 3 novembre 2026 sur la base de la documentation OpenAI :
temperatureettop_pne sont acceptés qu’avec un effort de raisonnement denone, tandis que les modèles GPT-5.6 raisonnent par défaut (medium). Les appels définissant ces paramètres doivent donc spécifierreasoning={"effort": "none"}(API Responses) oureasoning_effort="none"(Chat Completions). Sources : Utilisation de GPT-6 · GPT-5.6 Terra.
Extraction structurée d’entités
L’extraction structurée d’entités est l’un des cas d’usage les plus demandés en production : transformer du texte libre (e-mails, documents, pages web) en données que ton application peut réellement exploiter. En combinant la sortie structurée avec des invites spécialisées, tu peux construire des pipelines d’extraction fiables sans entraîner de modèle NER dédié.
Pipeline d’extraction de base
Toute la spécificité de l’extraction réside dans l’invite système de la fonction ci-dessous, et elle mérite une attention particulière. Trois instructions se superposent ici : extraire uniquement ce qui est présent, utiliser null pour les données manquantes et ne jamais déduire d’informations qui ne sont pas explicitement mentionnées.
Cette dernière phrase est la plus importante en pratique. Livré à lui-même, un modèle remplira volontiers un numéro SIRET plausible ou devinera une ville à partir d’un indicatif téléphonique, avec les meilleures intentions du monde. Pour une extraction destinée à un système métier, cette serviabilité est un défaut grave : une fois les données dans la base, impossible de distinguer ce qui a été lu de ce qui a été supposé. Définir temperature à 0.0 sert le même objectif : sur deux exécutions du même document, tu veux la même sortie, ne serait-ce que pour reproduire un incident.
import json
from openai import OpenAI
client = OpenAI()
def extract_entities(text: str, schema: dict,
instructions: str = "") -> dict:
"""Extrait des entités structurées à partir de texte libre."""
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)
Exemple 1 : Extraction de CV
Un CV est un excellent terrain de test car il combine des sections stables avec une mise en page totalement libre. Le schéma ci-dessous regroupe les coordonnées dans un objet identity où presque chaque champ est nullable : un candidat pourrait ne pas fournir de numéro de téléphone, et rendre ce champ obligatoire inviterait essentiellement le modèle à en inventer un.
Les compétences ne sont pas de simples chaînes mais des objets avec trois attributs, ce qui te permet de préserver le niveau déclaré et de catégoriser chaque compétence. Sans ces énumérations, « Scrum » et « Python » se retrouveraient côte à côte dans la même liste plate, inutilisables pour un filtre tentant d’isoler les langages. Note également le champ end_date dans les expériences, qui est nullable alors que start_date ne l’est pas : c’est ainsi que tu encodes un poste actuel sans inventer une convention maison comme « present » ou « 9999 ». Sur le CV de test, cette subtilité se joue sur la ligne 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)
Exemple 2 : Extraction d’e-mails commerciaux
Le deuxième exemple change de nature : nous ne faisons plus que copier des informations, nous demandons au modèle d’interpréter. intent et urgency sont des jugements : aucune phrase dans l’e-mail ne dit « ceci est une demande de devis, haute priorité ». C’est précisément ce qu’un pipeline d’extraction classique basé sur des règles ou des expressions régulières ne peut pas faire, et c’est exactement ce qui justifie l’utilisation d’un LLM ici plutôt qu’ailleurs.
Le reste du schéma revient à des faits vérifiables : produits mentionnés, montants avec leur contexte, dates et leur signification, actions requises. Le champ summary clôture l’objet et sert l’humain qui examinera la file d’attente, pas le code. Un point de vigilance avec ce schéma mixte : une erreur de jugement sur urgency n’invalide pas les montants, mais l’inverse peut arriver, car un modèle qui comprend mal l’intention lit parfois le reste à travers ce malentendu. Si la classification est critique pour ton routage, sépare-la dans un appel dédié.
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
}
Extraction par lots
Pour traiter de gros volumes, parallélise tes extractions. Une boucle séquentielle sur mille documents passe le plus clair de son temps à attendre le réseau ; avec asyncio, ces attentes se chevauchent et le lot se traite en une fraction du temps.
Le sémaphore n’est pas un détail décoratif. Sans lui, lancer mille tâches d’un coup saturera ton quota et déclenchera des erreurs de limite de débit qui coûtent plus cher en nouvelles tentatives qu’elles n’économisent en vitesse. Définis la valeur max_concurrent en observant tes propres limites, dix étant un point de départ prudent. Note également return_exceptions=True : cela empêche un seul document mal formé de faire planter tout le lot, te laissant trier les échecs afterward.
import asyncio
from openai import AsyncOpenAI
async_client = AsyncOpenAI()
async def extract_batch(texts: list[str], schema: dict,
max_concurrent: int = 10) -> list[dict]:
"""Extraction parallèle avec contrôle de la concurrence."""
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)
Évaluation de la qualité de l’extraction
Un pipeline d’extraction sans jeu de test annoté est un pipeline dont personne ne connaît la fiabilité, et l’impression laissée par trois exemples lus à la main s’avère presque toujours trop optimiste. La fonction ci-dessous compare une extraction obtenue champ par champ avec une référence établie manuellement, renvoyant la précision globale ainsi qu’une ventilation des écarts.
Cette ventilation est la partie utile : les erreurs ne sont presque jamais réparties uniformément. Un champ concentre les problèmes — souvent une date ambiguë, un niveau de compétence implicite ou une catégorie mal définie — et une seule phrase ajoutée à l’invite système le corrige. Sans cette mesure, tu ajusterais l’invite au hasard, risquant possiblement de détériorer un champ qui fonctionnait déjà.
def evaluate_extraction(expected: dict, obtained: dict,
fields: list[str]) -> dict:
"""Compare l'extraction obtenue avec la référence."""
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
}
Construis ta référence avant d’optimiser
Choisis un type de document de ton domaine — contrats, factures, rapports — et définis un schéma d’extraction d’au moins dix champs, en mélangeant délibérément des champs faciles avec ceux dont tu sais qu’ils sont ambigus. Assemble cinq exemples de documents avec leurs extractions attendues, rédigées à la main : cette étape est fastidieuse, elle prend une heure, et c’est ce qui donne toute sa valeur au travail ultérieur.
Ensuite, exécute le pipeline, mesure la précision et lis la liste des erreurs champ par champ. Le champ le plus défaillant te dira quoi corriger dans l’invite ; une seconde mesure te dira si la correction a vraiment aidé — ou si elle a dégradé un autre champ au passage, ce qui arrive plus souvent qu’on ne le pense dès qu’une instruction supplémentaire déplace l’attention du modèle.
Viktiga punkter
- L’extraction structurée remplace les modèles NER dédiés pour la plupart des cas d’usage
- Utilise
temperature=0.0pour maximiser la cohérence - Rends les champs optionnels nullable plutôt qu’optionnels
- Parallélise avec asyncio pour les gros volumes
- Évalue systématiquement la qualité avec un jeu de test annoté
- Les instructions de l’invite système guident le contenu, le schéma contraint la structure