Tutoriel Migration OpenAI → Claude (2026)

Les deux SDK acceptent maintenant la même forme de tableau `messages: [{role, content}]`. Les différences : nom de méthode, structure réponse, et comment les prompts système sont passés. Voici le diff canonique pour une simple completion.

```python # OpenAI (avant) from openai import OpenAI client = OpenAI() resp = client.chat.completions.create( model="gpt-5.5", messages=[ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Summarize: ..."} ], max_tokens=500, ) answer = resp.choices[0].message.content ```

```python # Anthropic (après) import anthropic client = anthropic.Anthropic() resp = client.messages.create( model="claude-sonnet-4-6", max_tokens=500, system="You are a helpful assistant.", messages=[ {"role": "user", "content": "Summarize: ..."} ], ) answer = resp.content[0].text ```

Trois différences. **Le prompt système est son propre champ** chez Claude (`system=`), pas un message dans le tableau. **`max_tokens` est requis** chez Claude (OpenAI par défaut au max du modèle). **La forme réponse** est `resp.content[0].text` (un tableau de blocs contenu) au lieu de `resp.choices[0].message.content`.

Le streaming fonctionne de la même façon conceptuellement — les deux exposent les context managers `with client.<x>.stream(...)`. Les événements d'Anthropic sont plus structurés (`content_block_start`, `content_block_delta`, `content_block_stop`) où le stream OpenAI est une séquence plate de chunks completion. La plupart du code production itère simplement le stream et concatène `delta.text` (Claude) ou `delta.content` (OpenAI) — les deux fonctionnent.

Les modèles GPT performent bien avec des prompts système structurés en markdown (`# Heading`, `**bold**`, listes numérotées). Les modèles Claude performent notablement mieux avec structure tags XML. Le guide prompt engineering d'Anthropic recommande les tags XML comme le moyen canonique de délimiter sections — `<context>`, `<instructions>`, `<example>`, `<output_format>`, `<constraints>`.

Avant (accordé GPT) :

``` You are a senior product analyst. ## Task Write a competitive analysis of X. ## Context The customer is... ## Output Return JSON with... ```

Après (accordé Claude) :

``` You are a senior product analyst. <task> Write a competitive analysis of X. </task> <context> The customer is... </context> <output_format> Return JSON with... </output_format> ```

Pourquoi c'est important : le pattern d'attention de Claude est accordé pour reconnaître les limites tags XML et peser le contenu à l'intérieur de manière appropriée. Les headings markdown fonctionnent mais demandent à Claude d'inférer la structure de la convention. Les tags XML rendent la structure explicite et améliorent substantiellement la qualité output sur prompts complexes. Sur une eval 50-prompts qu'on a menée en mai 2026 sur des tâches de classification support client, le même prompt restructuré de markdown à XML a relevé la précision Sonnet 4.6 de 7-12 points de pourcentage.

Les exemples few-shot sont aussi meilleurs quand enrobés en tags `<example>...</example>`. Le tag de fermeture importe — les tags incomplets (`<example>` sans `</example>`) confondent le parsing de Claude.

Le prompt caching d'OpenAI est opportuniste et prefix-only — vous obtenez des économies automatiquement si votre prompt système est stable. Le prompt caching de Claude est *explicite* — vous marquez les points de rupture dans le tableau messages et payez une prime sur l'écriture cache (1.25x pour 5-min TTL, 2x pour 1-hour TTL) en échange d'un coût lecture de 10% (économies 90%) sur hits suivants.

Le modèle explicite est plus puissant parce que vous pouvez cacher n'importe quelle portion d'input, pas seulement le prefix littéral. Cache prompt système + tools + premier exemple few-shot ; variez la requête user librement. Exemple :

```python # Cache le prefix stable (système + tools + few-shot) resp = client.messages.create( model="claude-sonnet-4-6", max_tokens=500, system=[ { "type": "text", "text": SYSTEM_PROMPT, # stable across calls "cache_control": {"type": "ephemeral"} } ], tools=TOOL_DEFINITIONS, # also cached via the system breakpoint above messages=[ {"role": "user", "content": user_input} # not cached ], ) ```

L'équilibre sur l'écriture cache 1-hour (premium 2x) se fait après exactement 2 hits — trivial à atteindre pour agents production. Sur un prompt système 2,000-token + 1,500-token tools (3,500 tokens cachés) sur Sonnet 4.6 lu 100 fois en une heure :

Écriture cache : 3,500 / 1M × $6 = $0.021 (une fois). Lectures cache : 99 × 3,500 / 1M × $0.30 = $0.10395. Coût total caché : $0.125. Sans cache : 100 × 3,500 / 1M × $3 = $1.05. **Économie : $0.925 — 88% off sur la portion prefix de la facture**.

C'est le plus grand levier coût de la migration. Les équipes qui passent de OpenAI à Claude sans setup de points de rupture cache explicites finissent souvent à payer *plus* — parce que l'hypothèse « Claude est moins cher » était basée sur pricing caché qu'elles n'ont pas activé. Le setup cache n'est pas optionnel pour migrations production.

Les deux API supportent tool use (function calling). Les schémas diffèrent légèrement. Les tools OpenAI sont `{type: 'function', function: {name, description, parameters}}`. Les tools Claude sont `{name, description, input_schema}` — plus plat, pas de wrapper `function` englobant.

OpenAI (avant) :

```python tools = [ { "type": "function", "function": { "name": "get_weather", "description": "Get current weather", "parameters": { "type": "object", "properties": { "location": {"type": "string"} } } } } ] ```

Claude (après) :

```python tools = [ { "name": "get_weather", "description": "Get current weather", "input_schema": { "type": "object", "properties": { "location": {"type": "string"} } } } ] ```

Les réponses tool diffèrent aussi. OpenAI retourne `tool_calls` sur le message assistant. Claude retourne `tool_use` blocs contenu dans le tableau messages. Construction boucle :

```python # Claude tool loop while True: resp = client.messages.create(model="claude-sonnet-4-6", tools=tools, messages=messages) if resp.stop_reason == "end_turn": break messages.append({"role": "assistant", "content": resp.content}) for block in resp.content: if block.type == "tool_use": result = run_tool(block.name, block.input) messages.append({"role": "user", "content": [ {"type": "tool_result", "tool_use_id": block.id, "content": result} ]}) ```

Deux pièges. Premièrement, Claude requiert que le résultat tool soit un message `user` avec bloc contenu `tool_result` — pas un rôle `tool` séparé comme OpenAI. Deuxièmement, les appels tool parallèles sont retournés comme multiples blocs `tool_use` dans le même tour assistant — votre outil runner doit les gérer en parallèle, puis retourner tous résultats dans un seul message user.

Maintenant les maths coût réels pour votre workload. Prenez une forme production représentative : 1M appels/mois, moyenne 2,000 tokens entrée, 500 tokens sortie, avec un prefix système stable 1,500-token (candidat caching).

**Avant — gpt-5.5 sans cache** (le cache opportuniste OpenAI peut aider mais n'est pas modélisé ici) :

Entrée : 1M × 2,000 / 1M = 2,000M tokens × $5/1M = $10,000. Sortie : 1M × 500 / 1M = 500M tokens × $30/1M = $15,000. **Total : $25,000/mois**.

**Après — Claude Sonnet 4.6 sans cache** :

Entrée : 2,000M × $3/1M = $6,000. Sortie : 500M × $15/1M = $7,500. **Total : $13,500/mois** — une économie de 46% même sans caching.

**Après — Claude Sonnet 4.6 avec caching explicite** (1-hour TTL sur prefix 1,500-token, taux hit cache 90%) :

Écritures cache : 0.1M (cache miss) × 1,500/1M × $6 = $900. Lectures cache : 0.9M × 1,500/1M × $0.30 = $405. Portion entrée non-cachée (500 tokens restants × 1M) = 500M × $3/1M = $1,500. Sortie : $7,500. **Total : $10,305/mois** — une économie de 59% vs OpenAI.

**Delta annuel** : $25,000 × 12 - $10,305 × 12 = $300,000 - $123,660 = **$176,340/an économisés** sur ce workload.

Caveat important : gpt-5.5 → Sonnet 4.6 est la migration haut levier. gpt-5.4 → Sonnet 4.6 coûte réellement *plus* par appel ($3 entrée vs $2.50). gpt-5.4-mini → Haiku 4.5 coûte aussi plus (+33% entrée). Au tier petit / nano, OpenAI gagne en prix. Migrez les tiers premium et mid ; gardez le tier petit et nano sur OpenAI. Le calculateur delta coût devient par-workload, pas par-organisation.

**Eval parity d'abord**. Lancez les deux providers sur votre ensemble eval retenu avant de basculer. Le même prompt restructuré pour Claude doit égaler ou battre la baseline GPT ; s'il ne le fait pas, vous avez un problème prompt, pas un problème modèle.

**Trafic shadow une semaine**. Routez 5-10% du trafic production vers Claude aux côtés d'OpenAI, loguez les deux outputs, comparez la qualité. Attrapez les régressions silencieuses avant qu'elles n'arrivent aux utilisateurs.

**Configurez votre monitoring avant cutover**. Nombres tokens, latence, taux d'erreur, taux hit cache. Le taux hit cache est la métrique qui détermine si vos maths migration se concrétisent en production — trackez-la explicitement.

**Planifiez un chemin rollback**. Feature-flag le choix modèle dans votre code ; basculez vers OpenAI en secondes si la qualité baisse. Ne supprimez pas OpenAI de votre liste dépendances le jour 1 de la cutover.

**Communiquez aux utilisateurs seulement quand pertinent**. La plupart des features AI face-utilisateur n'ont pas besoin d'annoncer les changements de modèle. Les outils internes oui (les développeurs se soucient quel modèle suggère leur code).

Les deux API stream les tokens. La forme événement est assez différente que le copy-paste naïf du code streaming échoue subtilement. OpenAI stream une séquence plate de chaînes `chunk.choices[0].delta.content` ; Claude stream des événements structurés avec limites explicites start/delta/stop sur chaque bloc contenu.

Pattern streaming OpenAI :

```python stream = client.chat.completions.create( model="gpt-5.5", messages=messages, stream=True, ) for chunk in stream: if chunk.choices[0].delta.content: print(chunk.choices[0].delta.content, end="") ```

Pattern streaming Claude :

```python with client.messages.stream( model="claude-sonnet-4-6", max_tokens=500, messages=messages, ) as stream: for text in stream.text_stream: print(text, end="") ```

Le helper `text_stream` chez Claude aplatit les événements structurés en simple stream chaîne — la plupart du code production l'utilise. Si vous besoin de contrôle plus fin (par ex. gérer les blocs tool_use mid-stream, surfer le contenu reasoning séparément), descendez à l'API niveau événement et pattern-match sur `event.type`.

Le streaming tool-use est sensiblement différent chez Claude. L'input tool JSON stream en deltas JSON partiels dans les événements `content_block_delta` avec `delta.type === 'input_json_delta'`. La concaténation chaîne naïve marche mais vous devez attendre l'événement `content_block_stop` avant parser le JSON complet. Le streaming tool calls OpenAI a un pattern JSON partiel similaire ; les noms champs diffèrent.

**Erreur 1 : supposer Claude est moins cher sans vérifier le tier.** Sonnet 4.6 vs gpt-5.4 est à peu près égal, et Haiku 4.5 est réellement *plus cher* que gpt-5.4-mini. Les économies viennent du tier premium (Opus 4.8 vs gpt-5.5-pro) et du tier mid avec caching (Sonnet 4.6 + 1-hour cache vs gpt-5.5).

**Erreur 2 : copier les prompts verbatim.** La structure markdown marche sur Claude mais la structure tags XML marche mieux. Sauter la restructuration prompt laisse de la qualité sur la table.

**Erreur 3 : sauter les points de rupture cache explicites.** La revendication « Claude est moins cher » dépend du caching. Sans points de rupture explicites, vous pouvez payer plus par appel que l'équivalent OpenAI. Configurez le caching comme partie de la migration, pas comme suivi.

**Erreur 4 : ne pas gérer les appels tool parallèles.** Claude retourne plusieurs blocs `tool_use` par tour quand il fait des appels tool parallèles. Votre outil runner doit les gérer concurremment et retourner tous résultats dans un seul message user.

**Erreur 5 : garder `max_tokens` défini sur les defaults OpenAI.** Claude requiert `max_tokens` d'être explicite. L'ancien code qui reposait sur le default OpenAI (model max) doit mettre un plafond réel — typiquement 500-2,000 pour usages chat. Ne le mettez pas trop haut ; vous payerez pour output dont vous n'avez pas besoin.