L'échec le plus fréquent d'une intégration de l'API Llama ne vient pas des capacités du modèle, mais de trois paramètres mal alignés : l'URL de base, le mode d'authentification et le nom du modèle. Depuis le retrait de la préversion publique de l'API Llama de Meta en juillet 2026, les points d'entrée Llama se répartissent entre fournisseurs cloud, plateformes d'inférence, services auto-hébergés et passerelles compatibles OpenAI. La forme des requêtes est proche, mais les détails ne sont pas identiques.

Cet article suit l'ordre « confirmer l'entrée, construire l'URL, trouver le nom du modèle, envoyer la première requête, gérer streaming et appels d'outils, diagnostiquer les erreurs, migrer depuis l'ancienne interface ». Les exemples utilisent l'interface compatible OpenAI ; la liste des modèles et les tarifs font foi sur la page Tarifs des modèles.

Remarque : Meta et Llama sont des marques de Meta Platforms, Inc. ; Groq, OpenRouter, AWS, Google Cloud et les autres noms cités sont des marques de leurs détenteurs respectifs. Cet article est purement technique et n'implique aucune affiliation, relation d'agence ou approbation avec ces plateformes.

1. Trois choses à confirmer avant l'intégration

Quelle que soit la plateforme, commencez par inscrire trois éléments dans la configuration :

  • URL de base : protocole, domaine et préfixe de chemin, se terminant généralement par /v1.
  • Authentification : jeton Bearer, signature IAM ou compte de service, sans mélange possible.
  • Nom du modèle : l'identifiant interne de la plateforme, pas le nom produit de la page marketing.

Ajoutez deux vérifications non techniques : les régions et nœuds traversés par les données, et le cycle de vie de la version du modèle. La première concerne la conformité, la seconde détermine si vous devrez migrer dans six mois.

2. URL de base : le SDK ajoute le chemin

Le base_url du SDK OpenAI s'arrête au préfixe de version ; le SDK ajoute ensuite /chat/completions. Donc :

  • correct : https://api.groq.com/openai/v1
  • incorrect : https://api.groq.com/openai/v1/chat/completions (double chemin)
  • incorrect : https://api.groq.com/openai (/v1 manquant, la plupart des plateformes renvoient 404)

Les préfixes diffèrent selon la plateforme : /openai/v1 chez Groq, /api/v1 chez OpenRouter, /v1 par défaut sur un vLLM auto-hébergé. Les points d'entrée cloud sont plus complexes : l'adresse compatible OpenAI de Vertex AI contient le projet, la région et le chemin du point d'entrée, on ne peut pas recopier le seul domaine. La méthode la plus sûre est de copier l'URL de base complète depuis l'« exemple de requête » de la console, puis de la valider avec une requête minimale.

3. Noms de modèles : différents sur chaque plateforme

Un même modèle Llama peut s'écrire très différemment selon la plateforme :

Entrée Exemple d'URL de base Exemple de nom de modèle Remarque
Groq https://api.groq.com/openai/v1 llama-3.3-70b-versatile Voir la liste de modèles actuelle
OpenRouter https://openrouter.ai/api/v1 meta-llama/llama-3.3-70b-instruct Routage agrégé, attention au préfixe
vLLM auto-hébergé http://localhost:8000/v1 défini par --served-model-name Sinon le chemin des poids est utilisé
AWS Bedrock https://bedrock-runtime.us-east-1.amazonaws.com us.meta.llama4-scout-17b-instruct-v1:0 API Invoke/Converse, pas compatible OpenAI
Passerelle compatible https://ai.zhongshangqihang.com/v1 voir la liste de la console Une clé pour plusieurs modèles

Les noms de modèles distinguent la casse, le numéro de version, la quantification et la variante d'inférence. Llama-3.3-70B-Instruct, llama-3.3-70b-versatile et meta-llama/llama-3.3-70b-instruct ne désignent pas forcément le même déploiement. Ne recopiez pas un identifiant trouvé dans un blog pour passer en production : vérifiez dans la console ou via GET /models.

Surveillez aussi le cycle de vie. Google Cloud a annoncé le retrait de llama-3.3-70b-instruct-maas le 21 octobre 2026 ; Llama 4 Scout sur AWS est en phase Legacy, avec une fin de support annoncée au 30 mars 2027. Placez les identifiants de modèles dans la configuration plutôt que dispersés dans le code métier, pour éviter une recherche dans tout le dépôt lors d'une migration.

4. Premier appel : valider d'abord avec curl

Préparez une clé de test dans une variable d'environnement, pour qu'elle n'apparaisse pas dans l'historique des commandes :

export LLAMA_API_KEY="votre_clé"

curl -s https://api.groq.com/openai/v1/chat/completions \
  -H "Authorization: Bearer $LLAMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama-3.3-70b-versatile",
    "messages": [{"role": "user", "content": "Expliquez en une phrase ce qu'est une interface compatible OpenAI"}],
    "max_tokens": 128
  }'

Dans le JSON retourné, examinez quatre champs : le contenu de choices[0].message.content, la valeur de finish_reason (stop ou length), la présence des tokens d'entrée et de sortie dans usage, et la concordance du champ model avec votre requête. Si le model retourné diffère, un routage ou un alias a pu s'appliquer, ce qui affecte la facturation et l'évaluation.

5. SDK Python : mettre les différences dans la configuration

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["LLAMA_API_KEY"],
    base_url=os.environ["LLAMA_BASE_URL"],
)

resp = client.chat.completions.create(
    model=os.environ["LLAMA_MODEL"],
    messages=[{"role": "user", "content": "Expliquez en une phrase ce qu'est une interface compatible OpenAI"}],
    max_tokens=128,
    timeout=60,
)
print(resp.choices[0].message.content)

Trois habitudes d'ingénierie évitent bien des écueils : fixer explicitement le timeout ; plafonner les tentatives et ne réessayer que les erreurs réessayables ; placer base_url, model et max_tokens dans la configuration. N'utilisez pas de tentatives infinies et ne réessayez pas une erreur de paramètre comme un 400.

Attention aussi aux noms de paramètres. Certaines plateformes n'acceptent que max_tokens, d'autres sont passées à max_completion_tokens ; certaines limitent la plage de temperature, le nombre de stop ou les rôles de message. Suivez la documentation de la plateforme cible et ne supposez pas que les paramètres OpenAI passent tels quels.

6. Streaming : traiter par blocs, sans attendre le texte complet

Avec stream=True, le serveur renvoie généralement des Server-Sent Events, chaque ligne commençant par data: et se terminant par data: [DONE]. Le client doit lire choices[0].delta.content bloc par bloc et gérer les blocs vides, les heartbeats et les coupures. Trois problèmes fréquents :

  • supposer que delta.content existe toujours et échouer sur None ;
  • un proxy ou une passerelle qui tamponne la réponse : le front-end croit qu'il n'y a pas de streaming alors que tout arrive d'un coup ;
  • le client se déconnecte mais le serveur continue de générer, gaspillant du quota ; prévoyez annulation et timeout au niveau métier.

Si vous passez par une passerelle, vérifiez d'abord qu'elle transmet bien le SSE et ne réécrit pas les événements d'erreur. La compatibilité du streaming est plus fragile que celle du non-streaming : testez-la séparément avant la mise en production.

7. Appels d'outils : confirmer que la plateforme les prend en charge

Le paramètre tools au format OpenAI n'est pas pleinement pris en charge par tous les hébergeurs Llama. Avant d'appeler, vérifiez trois choses : le modèle prend en charge les appels d'outils, la plateforme transmet tools et tool_choice, et le finish_reason retourné peut valoir tool_calls.

Les paramètres d'outil renvoyés par le modèle sont généralement une chaîne JSON, pas un objet. Le backend doit d'abord analyser le JSON et valider le schéma, puis exécuter la fonction réelle ; ne concaténez jamais directement la sortie du modèle dans du SQL, un shell ou une interface interne. L'exécution doit avoir timeout, idempotence et limites de permissions ; le résultat d'échec doit être renvoyé au modèle pour qu'il décide de réessayer ou de modifier les paramètres. Les appels parallèles, le schéma strict et les appels d'outils en streaming varient le plus selon les plateformes : validez-les un par un.

8. Erreurs courantes : le statut d'abord, le corps ensuite

  • 401 : clé absente, mal formée, issue d'une autre plateforme ou révoquée.
  • 404 : /v1 en trop ou manquant dans l'URL de base, ou nom de modèle inexistant.
  • 400 : paramètre non pris en charge, par exemple max_tokens et max_completion_tokens mélangés, ou rôle de message invalide.
  • 403 : clé valide, mais pas de droit sur le modèle, le projet ou la région visés.
  • 429 : limitation de débit ou de concurrence. Lisez Retry-After, appliquez un backoff exponentiel avec gigue, sans réessayer à intervalle fixe.
  • 5xx : panne ou timeout amont. Ne réessayez que les requêtes idempotentes et journalisez l'identifiant de requête.
  • 200 mais contenu vide : peut venir d'un finish_reason=length, d'un filtrage de contenu ou d'une erreur d'analyse du streaming.

L'ordre de diagnostic va de l'extérieur vers l'intérieur : contournez d'abord le code métier avec curl, puis changez de SDK officiel, et n'accusez le prompt qu'en dernier. Journalisez identifiant de requête, code de statut, nom de modèle et URL de base, sinon un problème inter-plateformes est difficile à reproduire.

9. Migrer depuis l'ancienne API Llama : dans l'ordre

  1. Recherchez api.llama.com, /compat/v1 et les anciens noms de modèles dans le code et la configuration, et listez tous les points d'appel.
  2. Créez une clé sur la nouvelle plateforme, confirmez l'URL de base et le nom du modèle, puis validez une requête minimale avec curl.
  3. Établissez une table de correspondance des modèles : nouvel identifiant, limite de contexte, limite de sortie, prise en charge du streaming et des outils.
  4. Remplacez l'URL de base et l'authentification en conservant timeouts, tentatives et champs de journal, sans modifier la logique métier au passage.
  5. Testez séparément le streaming et les appels d'outils, qui produisent le plus souvent des échecs « non-streaming correct, streaming en panne ».
  6. Évaluez sur un petit échantillon de requêtes réelles, puis basculez 5 % à 10 % du trafic en surveillant le taux d'erreur et la latence p95.
  7. Conservez l'ancien canal ou un hébergeur de secours et faites un exercice de retour arrière avant la bascule complète.

La migration n'est pas terminée quand « le texte sort », mais quand qualité, latence, limitation et facturation sont acceptables, et qu'un incident peut être rattaché à une requête précise.

Questions fréquentes

L'URL de base de l'API Llama est-elle fixe ?

Non. L'ancien point d'entrée de l'API Llama de Meta est retiré ; l'URL de base dépend désormais de la plateforme choisie. Les préfixes de Groq, OpenRouter, vLLM auto-hébergé et des passerelles compatibles diffèrent : suivez l'exemple de la console.

Pourquoi le même modèle Llama porte-t-il des noms différents selon la plateforme ?

Chaque plateforme ajoute son préfixe, sa version, sa quantification et son identifiant de déploiement. Le nom de modèle est un identifiant interne, pas le nom générique de la famille. En changeant de plateforme, il faut généralement changer de nom.

Le SDK OpenAI peut-il appeler Llama directement ?

Oui, à condition que la plateforme cible expose une interface /chat/completions compatible OpenAI. Pointez base_url vers l'adresse de la plateforme, remplacez api_key et model, et l'appel minimal fonctionne. Les appels d'outils, le streaming et la structure des erreurs restent à valider un par un.

Faut-il changer de SDK pour le streaming ?

La plupart des SDK OpenAI prennent en charge stream=True sans changement de SDK. Vérifiez toutefois que la plateforme renvoie du SSE standard, que le marqueur de fin est [DONE] et que la passerelle ne tamponne pas la réponse.

Que vérifier en premier quand un appel d'outil échoue ?

Confirmez que le modèle et la plateforme déclarent prendre en charge les appels d'outils, puis que le JSON Schema de tools est valide et que tool_choice est accepté, et enfin que le finish_reason et le JSON des paramètres sont analysables. Réduisez couche par couche, sans commencer par modifier le prompt.

Pour aller plus loin

Choisissez une entrée, validez curl avec l'URL de base et le nom de modèle de l'exemple de la console, puis branchez le SDK Python ; le streaming et les appels d'outils exigent une acceptation séparée. Pour une entrée unifiée, des journaux et le changement de modèle, commencez par créer un compte sur ZSQH AI Gateway ; la liste des modèles et la facturation font foi sur la page Tarifs des modèles.

Articles liés :