Méthode parse() automatique

Leçon corrigée le 3 novembre 2026 d’après la documentation Structured Outputs de xAI et le SDK openai 3.42.1 : avec le SDK OpenAI pointé vers xAI, la méthode est client.chat.completions.parse, qui renvoie une complétion dont l’objet typé se lit dans choices[0].message.parsed ; client.chat.parse n’existe pas (le SDK xAI propose, lui, chat.parse(Schema) sur une conversation, qui renvoie un couple réponse-objet). Source : Structured Outputs.

La voie rapide : parse()

La méthode parse() est la manière la plus simple d’utiliser les sorties structurées avec l’API Grok. Elle prend un modèle Pydantic en entrée et retourne directement un objet typé — pas de JSON à parser, pas de validation manuelle.

Exemple complet

Voici comment extraire une critique de film structurée :

from openai import OpenAI
from pydantic import BaseModel

client = OpenAI(
    api_key="votre-cle-xai",
    base_url="https://api.x.ai/v1"
)

class MovieReview(BaseModel):
    title: str
    rating: float
    summary: str
    recommend: bool

completion = client.chat.completions.parse(
    model="grok-4.20-0309-reasoning",
    messages=[{
        "role": "user",
        "content": "Fais une critique du film Inception"
    }],
    response_format=MovieReview
)
parsed = completion.choices[0].message.parsed

# parsed est un objet MovieReview typé
print(parsed.title)      # "Inception"
print(parsed.rating)     # 9.2
print(parsed.recommend)  # True
print(type(parsed))      # <class 'MovieReview'>

Ce que retourne parse()

La méthode parse() retourne un tuple de deux éléments :

1. response : l’objet Response complet de l’API (avec les métadonnées, tokens utilisés, etc.)
2. parsed : votre modèle Pydantic instancié avec les données extraites

Vous pouvez accéder aux deux selon vos besoins :

completion = client.chat.completions.parse(...)
parsed = completion.choices[0].message.parsed

# Accéder aux métadonnées
print(completion.usage.total_tokens)
print(completion.model)

# Accéder aux données structurées
print(parsed.title)
print(parsed.rating)

Modèles imbriqués

parse() gère les structures complexes sans effort. Vous pouvez imbriquer des modèles Pydantic :

class Acteur(BaseModel):
    nom: str
    role: str

class Critique(BaseModel):
    titre: str
    realisateur: str
    annee: int
    note: float
    acteurs_principaux: list[Acteur]
    genres: list[str]
    points_forts: list[str]
    points_faibles: list[str]

completion = client.chat.completions.parse(
    model="grok-4.20-0309-reasoning",
    messages=[{
        "role": "user",
        "content": "Analyse complète du film Interstellar"
    }],
    response_format=Critique
)
parsed = completion.choices[0].message.parsed

for acteur in parsed.acteurs_principaux:
    print(f"{acteur.nom} joue {acteur.role}")

Quand utiliser parse()

parse() est le chemin le plus court entre une réponse du modèle et un objet Python exploitable : si vous travaillez avec Pydantic, c’est le choix par défaut. La méthode encapsule tout — l’envoi du schéma, la validation de la réponse, l’instanciation de l’objet — et vous rend directement une instance typée, sans json.loads ni vérification manuelle. C’est le code le plus concis possible, et pour l’immense majorité des cas, cette simplicité ne coûte rien : vous ne renoncez au contrôle fin du parsing que si vous en aviez réellement besoin, ce qui est rare. La leçon suivante couvre précisément ces cas où un contrôle manuel se justifie.

Points clés à retenir

• parse() retourne un tuple (Response, ParsedModel) — parsing automatique
• L’objet retourné est une instance Pydantic typée et validée
• Les modèles imbriqués et les listes d’objets fonctionnent nativement
• C’est la méthode recommandée pour la majorité des cas d’usage en Python
• Pas besoin de json.loads() ni de validation manuelle