Hoppa till huvudinnehåll
Svenska— Välj ett språk
Meny

Migration graduelle vers l'API Responses

Lektion 12 av 12 Uppdaterad 3 november 2026 Utvecklare
På denna sida
  1. Pourquoi et quand migrer
  2. Étape 1 : Identifier les fonctionnalités que tu utilises
  3. Étape 2 : Migrer les appels basiques
  4. Étape 3 : Migrer les conversations multi-tours
  5. Étape 4 : Profiter des nouvelles fonctionnalités
  6. Stratégie de migration recommandée
  7. Viktiga punkter
  8. Teste tes connaissances

Mis à jour le 3 novembre 2026 : Le mappage des paramètres indiquait précédemment que max_tokens conservait son nom dans l’API Responses ; le tableau de xAI le change en max_output_tokens, et les compteurs d’utilisation changent également de nom. Source : Comparaison avec Chat Completions.

Pourquoi et quand migrer

Le point de terminaison Chat Completions est marqué comme hérité. Il continuera de fonctionner, mais aucune nouvelle fonctionnalité ne lui sera ajoutée. Si ton application a besoin d’outils côté serveur (recherche web, exécution de code), de stockage de conversations ou de raisonnement chiffré, la migration vers l’API Responses devient nécessaire.

La bonne nouvelle : cette migration peut se faire progressivement. Tu n’as pas besoin de tout réécrire d’un coup.

Étape 1 : Identifier les fonctionnalités que tu utilises

Avant de migrer, fais l’inventaire de ce que ton application utilise avec Chat Completions :

# Audit your existing code
# Look for these patterns:

# 1. Basic calls (simple text)
client.chat.completions.create(model=..., messages=...)

# 2. Streaming
client.chat.completions.create(..., stream=True)

# 3. Function calling
client.chat.completions.create(..., tools=[...])

# 4. Vision (images)
# messages with content as array [text, image_url]

# 5. Generation parameters
# temperature, max_tokens, top_p, stop, seed

Les appels basiques et le streaming sont les plus simples à migrer. L’appel de fonctions nécessite d’adapter le format. La vision fonctionne de manière similaire.

Étape 2 : Migrer les appels basiques

La migration d’un appel simple suit ce schéma :

# BEFORE — Chat Completions
response = client.chat.completions.create(
    model="grok-4.20-0309-reasoning",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello!"}
    ]
)
texte = response.choices[0].message.content

# AFTER — Responses API
response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    instructions="You are a helpful assistant.",
    input="Hello!"
)
texte = response.output_text

Mappage des champs

Les principaux changements sont :

  • messages avec le rôle system → instructions (paramètre dédié)
  • messages avec le rôle user → input (chaîne simple)
  • response.choices[0].message.content → response.output_text
  • max_tokens → max_output_tokens, selon le tableau de mappage de xAI ; temperature conserve son nom
  • response.usage.prompt_tokens et completion_tokens → input_tokens et output_tokens (détails : input_tokens_details.cached_tokens, output_tokens_details.reasoning_tokens)

Étape 3 : Migrer les conversations multi-tours

C’est ici que l’API Responses simplifie les choses. Au lieu de reconstruire l’historique à chaque requête, tu les enchaînes par ID :

# BEFORE — Chat Completions (manage history yourself)
historique = [
    {"role": "system", "content": "You are a helpful assistant."}
]

def envoyer_message(texte: str) -> str:
    historique.append({"role": "user", "content": texte})
    response = client.chat.completions.create(
        model="grok-4.20-0309-reasoning",
        messages=historique
    )
    reponse = response.choices[0].message.content
    historique.append({"role": "assistant", "content": reponse})
    return reponse

# AFTER — Responses API (server manages history)
dernier_id = None

def envoyer_message(texte: str) -> str:
    response = client.responses.create(
        model="grok-4.20-0309-reasoning",
        instructions="You are a helpful assistant.",
        input=texte,
        previous_response_id=dernier_id
    )
    dernier_id = response.id
    return response.output_text

Le code est plus simple et tu n’as plus à gérer manuellement le tableau de messages.

Étape 4 : Profiter des nouvelles fonctionnalités

Une fois migré, tu peux exploiter les fonctionnalités exclusives à l’API Responses :

Recherche web intégrée

response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="What are the latest developments in generative AI?",
    tools=[{"type": "web_search"}]
)
# The response includes citations with source URLs

Stockage des réponses

response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="Analyze this document...",
    store=True  # Keeps for 30 days
)

# Retrieve later
stored = client.responses.retrieve(response.id)

Raisonnement chiffré

response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="Solve this complex problem...",
    include=["reasoning.encrypted_content"]
)
# The encrypted reasoning can be reused in subsequent requests

Stratégie de migration recommandée

Plutôt que de tout migrer d’un coup, procède par étapes :

  1. Identifie les appels Chat Completions dans ton code
  2. Classe-les par complexité (basique → streaming → appel de fonctions)
  3. Migre en premier les nouveaux points de terminaison ou fonctionnalités (greenfield)
  4. Migre ensuite les appels existants les plus simples
  5. Conserve Chat Completions pour les intégrations tierces qui l’exigent (LangChain, etc.)

Coexistence temporaire

Il est tout à fait acceptable d’exécuter les deux points de terminaison côte à côte pendant la transition :

# Wrapper that abstracts the endpoint used
class GrokClient:
    def __init__(self, use_responses: bool = False):
        self.use_responses = use_responses
        self.client = OpenAI(
            api_key=os.getenv("XAI_API_KEY"),
            base_url="https://api.x.ai/v1"
        )

    def generate(self, system: str, user_message: str) -> str:
        if self.use_responses:
            response = self.client.responses.create(
                model="grok-4.20-0309-reasoning",
                instructions=system,
                input=user_message
            )
            return response.output_text
        else:
            response = self.client.chat.completions.create(
                model="grok-4.20-0309-reasoning",
                messages=[
                    {"role": "system", "content": system},
                    {"role": "user", "content": user_message}
                ]
            )
            return response.choices[0].message.content

Cette approche te permet de basculer progressivement en testant chaque migration individuellement.

Viktiga punkter

  • La migration peut être graduelle : pas besoin de tout réécrire d’un coup
  • Changements principaux : messages → input/instructions, choices[0].message.content → output_text
  • Les conversations multi-tours passent d’un tableau de messages à un simple previous_response_id
  • L’API Responses donne accès à des fonctionnalités exclusives (web_search, stockage, raisonnement chiffré)
  • Exécute les deux points de terminaison côte à côte pendant la transition et migre par ordre de complexité

Teste tes connaissances

L’API héritée est comprise et la migration préparée.

1. Que signifie le statut hérité et sans état de Chat Completions ?

Réponse : Le point de terminaison reste pris en charge mais n’évolue plus : sans état, il exige de renvoyer l’intégralité de l’historique à chaque appel — l’API Responses est la voie moderne.

2. Quels rôles structurent les messages ?

Réponse : system (et developer), user, assistant — le cadre, les requêtes, les réponses : l’historique complet redémarre à chaque requête.

3. Comment utiliser du code OpenAI existant avec Grok ?

Réponse : En changeant base_url vers https://api.x.ai/v1 et la clé API — la compatibilité de format gère le reste, y compris le SDK OpenAI et le Vercel AI SDK.

4. Que lis-tu dans la réponse et l'utilisation ?

Réponse : choices porte les réponses avec finish_reason ; usage détaille les tokens, y compris reasoning_tokens pour les modèles de raisonnement — la base pour le suivi des coûts.

5. Comment migrer proprement vers l'API Responses ?

Réponse : Progressivement : nouveaux développements dans Responses, points de terminaison existants convertis un par un avec re-test des prompts — comparer les deux formats guide la conversion.

Comprends l’héritage, construis pour le moderne : le plan de migration graduelle du cours est ta feuille de route — sans big bang.