response_format manuel

Plus de contrôle avec response_format

La méthode manuelle via response_format vous donne un contrôle total sur le parsing. Contrairement à parse() qui retourne un objet typé, cette approche retourne une chaîne JSON que vous parsez vous-même — le modèle Pydantic ne sert alors qu’à fournir le schéma (model_json_schema()) et à valider après coup. C’est la méthode à privilégier quand vous avez besoin de flexibilité ou quand vous travaillez dans un environnement sans Pydantic.

Le flux de travail

Avec response_format, le processus est en deux temps :

1. L’API retourne le JSON sous forme de string dans response.choices[0].message.content
2. Vous parsez cette string avec la méthode de votre choix

Exemple complet

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 = client.chat.completions.create(
    model="grok-4.20-0309-reasoning",
    messages=[{
        "role": "user",
        "content": "Fais une critique du film Inception"
    }],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "movie_review",
            "schema": MovieReview.model_json_schema()
        }
    }
)

# Le contenu est une string JSON
json_string = response.choices[0].message.content
print(type(json_string))  # <class 'str'>
print(json_string)
# {"title": "Inception", "rating": 9.2, "summary": "...", "recommend": true}

# Parsing manuel avec Pydantic
parsed = MovieReview.model_validate_json(json_string)
print(parsed.title)  # "Inception"

Différences avec parse()

Parsing sans Pydantic

Vous n’êtes pas obligé d’utiliser Pydantic pour parser le résultat. Le module json standard fonctionne aussi :

import json

response = client.chat.completions.create(
    model="grok-4.20-0309-reasoning",
    messages=[{
        "role": "user",
        "content": "Analyse ce texte et extrais les entités"
    }],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "entities",
            "schema": {
                "type": "object",
                "properties": {
                    "personnes": {
                        "type": "array",
                        "items": { "type": "string" }
                    },
                    "lieux": {
                        "type": "array",
                        "items": { "type": "string" }
                    }
                }
            }
        }
    }
)

data = json.loads(response.choices[0].message.content)
print(data["personnes"])  # ["Marie Curie", "Pierre Curie"]
print(data["lieux"])      # ["Paris", "Varsovie"]

Quand choisir response_format

response_format reprend l’avantage dès que vous avez besoin de voir ou de toucher le JSON avant qu’il ne devienne un objet. Le cas le plus courant est le logging : en production, conserver le JSON brut avant transformation est souvent une exigence d’audit ou de débogage, et parse() ne vous laisse pas ce point d’interception. Vient ensuite la question du schéma : si votre contrat d’interface est un schéma JSON brut — partagé avec d’autres équipes, généré par un outil, versionné indépendamment du code Python — l’imposer directement est plus fidèle que de le reconstruire en modèle Pydantic. Enfin, tous les projets ne vivent pas dans l’écosystème Pydantic : si votre validation passe par un autre framework, ou par une étape de traitement intermédiaire propre à votre pipeline, response_format vous rend le JSON tel quel et vous laisse la main sur la suite.

Gestion d’erreur

Avec la méthode manuelle, vous devez gérer les erreurs de parsing vous-même :

import json

try:
    data = json.loads(response.choices[0].message.content)
except json.JSONDecodeError as e:
    print(f"Erreur de parsing : {e}")

En pratique, cette erreur ne devrait jamais se produire puisque l’API garantit un JSON valide. Mais une gestion défensive reste une bonne pratique en production.

Points clés à retenir

• response_format retourne une string JSON dans response.choices[0].message.content
• Le parsing est à votre charge : json.loads(), model_validate_json(), ou autre
• Vous pouvez utiliser un schéma JSON brut au lieu d’un modèle Pydantic
• Plus de flexibilité que parse(), mais plus de code à écrire
• Le JSON retourné est garanti valide — les erreurs de parsing ne devraient pas survenir