Méthode parse() automatique

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

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

# 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 :

response, parsed = client.chat.parse(...)

# Accéder aux métadonnées
print(response.usage.total_tokens)
print(response.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]

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

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

Quand utiliser parse()

parse() est le bon choix quand :

• Vous travaillez en Python avec Pydantic
• Vous voulez un objet directement utilisable sans étape intermédiaire
• Vous n’avez pas besoin de contrôle fin sur le parsing
• Vous voulez le code le plus concis possible

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