Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

xAI SDK: client.chat.create

Oppitunti 4 / 12 Päivitetty 3. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Le SDK xAI natif
  2. Installation et authentification
  3. Une conversation, pas une requête
  4. Paramètres de génération
  5. Réponses en flux continu
  6. Gestion des erreurs
  7. Appels asynchrones
  8. Keskeiset asiat

Mise à jour du 3 novembre 2026. La version précédente partait du principe que xai-sdk utilisait l’interface du SDK OpenAI : messages sous forme de dictionnaires, response.choices[0].message.content, le paramètre stream=True et un module xai_sdk.errors inexistant. Avec le SDK réel (version 1.21.0), ce code échoue dès le premier appel : ValueError: unknown enum label "user". Cette leçon suit désormais le README officiel du SDK, et chaque exemple a été exécuté contre l’API xAI (avec une clé factice, pour vérifier le chemin d’appel et les erreurs). Sources : xAI Python SDK · Bonnes pratiques (xAI) · Débogage des erreurs (xAI).

Le SDK xAI natif

Le SDK officiel xAI pour Python, xai-sdk, n’utilise pas le point de terminaison REST Chat Completions : c’est une bibliothèque gRPC, dotée d’un client synchrone (Client) et d’un client asynchrone (AsyncClient), pour Python 3.10 et versions ultérieures. Il ne cherche pas à imiter le SDK OpenAI, et c’est la première chose à garder en tête : ses objets, méthodes et erreurs ont leur propre structure. Pour réutiliser du code écrit pour OpenAI, la prochaine leçon montrera l’autre voie, le SDK OpenAI configuré pour l’API xAI.

Installation et authentification

pip install xai-sdk

L’authentification utilise une clé API créée dans la console xAI. Place-la dans la variable d’environnement XAI_API_KEY, que le client lit automatiquement :

export XAI_API_KEY="your-api-key"

Une conversation, pas une requête

Avec ce SDK, client.chat.create() n’envoie rien : il crée un objet conversation (chat), auquel tu ajoutes des messages avec append, puis tu demandes une réponse avec sample(). Les messages sont construits avec les fonctions system, user et assistant du module xai_sdk.chat, et non avec des dictionnaires.

from xai_sdk import Client
from xai_sdk.chat import system, user

client = Client()  # lit XAI_API_KEY

chat = client.chat.create(
    model="grok-4.7",
    messages=[system("You are a helpful assistant. Respond in French.")],
)
chat.append(user("Explain deep learning in 3 sentences."))

response = chat.sample()
print(response.content)

La réponse expose son texte directement dans response.content, aux côtés de finish_reason, usage (jetons consommés), reasoning_content pour les modèles qui l’exposent, et citations lorsqu’une recherche a été effectuée.

L’API reste sans état : l’objet chat conserve l’historique pour toi. Pour une conversation multi-tours, ajoute la réponse au fil avant la prochaine question :

chat.append(response)
chat.append(user("Give a concrete example of an application."))
print(chat.sample().content)

Paramètres de génération

Les paramètres sont passés à client.chat.create() et s’appliquent à toute la conversation :

chat = client.chat.create(
    model="grok-4.7",
    messages=[system("Respond only in JSON.")],
    temperature=0.7,
    top_p=0.95,
    reasoning_effort="medium",
)
  • model : l’identifiant du modèle. xAI recommande grok-4.7 pour tous les usages.
  • messages : les messages initiaux, construits avec system, user et assistant.
  • temperature : l’API accepte de 0 à 2, mais xAI la plafonne à 1 au-delà et recommande 0,7, avec top_p à 0,95.
  • max_tokens : le nombre maximal de jetons générés. Les bonnes pratiques xAI recommandent de le régler au-dessus de la réponse la plus longue attendue, ou de laisser la valeur par défaut.
  • reasoning_effort : la profondeur de raisonnement, de none à high (et xhigh sur certains modèles). La valeur par défaut dépend du modèle : xAI recommande de la définir explicitement sur chaque requête et de la noter avec chaque résultat.
  • response_format, tools, tool_choice : sorties structurées et appel d’outils, abordés plus tard dans le cours.

stop existe aussi (jusqu’à quatre séquences), mais les bonnes pratiques xAI précisent que les modèles de raisonnement ne l’acceptent pas, pas plus que presence_penalty et frequency_penalty.

Réponses en flux continu

xAI recommande le flux continu, surtout avec les modèles de raisonnement, dont les réponses peuvent mettre longtemps à arriver. Cela n’utilise pas un paramètre : la conversation offre une seconde méthode, stream(), qui renvoie une paire (response, chunk) à chaque étape. chunk.content contient le fragment de texte qui vient d’arriver, et response accumule la réponse complète tout au long du flux.

chat = client.chat.create(model="grok-4.7")
chat.append(user("Write a short article on generative AI."))

for response, chunk in chat.stream():
    print(chunk.content, end="", flush=True)
print()

chat.append(response)  # la réponse complète rejoint l'historique

Gestion des erreurs

Puisque le SDK parle gRPC, ses erreurs sont des grpc.RpcError (de manière asynchrone, grpc.aio.AioRpcError, qui en héritent). Tu lis leur code avec .code() et le message avec .details() :

import grpc
from xai_sdk import Client
from xai_sdk.chat import user

client = Client()
chat = client.chat.create(model="grok-4.7")
chat.append(user("Hello"))

try:
    response = chat.sample()
    print(response.content)
except grpc.RpcError as error:
    if error.code() == grpc.StatusCode.DEADLINE_EXCEEDED:
        print("Timeout exceeded: the request took too long.")
    else:
        print(f"Error {error.code().name}: {error.details()}")

Trois comportements valent la peine d’être connus. Le SDK retente automatiquement les requêtes qui échouent avec UNAVAILABLE, jusqu’à cinq tentatives avec un délai croissant ; son README montre comment ajouter d’autres codes à cette liste, par exemple RESOURCE_EXHAUSTED, le code gRPC pour les quotas épuisés. Le délai d’attente par défaut est de 27 minutes pour toute requête et se définit à la création du client (Client(timeout=…), en secondes). Ne le réduis pas trop : xAI conseille de prévoir au moins 900 secondes par requête avec ses modèles de raisonnement. Enfin, une clé API invalide se manifeste par le code INVALID_ARGUMENT et le message “Incorrect API key provided” : c’est ce que renvoie l’API aujourd’hui, vérifié le 3 novembre 2026.

Appels asynchrones

Pour une application asyncio, remplace Client par AsyncClient. La création de la conversation reste synchrone ; ce sont sample() et stream() qui attendent :

import asyncio

from xai_sdk import AsyncClient
from xai_sdk.chat import user


async def main():
    client = AsyncClient()
    chat = client.chat.create(model="grok-4.7")
    chat.append(user("Hello"))

    response = await chat.sample()
    print(response.content)

    chat.append(response)
    chat.append(user("Summarize your response in one sentence."))
    async for response, chunk in chat.stream():
        print(chunk.content, end="", flush=True)


asyncio.run(main())

Keskeiset asiat

  • xai-sdk est un SDK gRPC, avec sa propre interface : il ne réutilise ni la forme ni les objets du SDK OpenAI
  • client.chat.create() crée une conversation ; chat.append(user(...)) ajoute un message, chat.sample() renvoie la réponse, lue dans response.content
  • Les messages sont construits avec system, user et assistant de xai_sdk.chat ; les dictionnaires font échouer l’appel
  • Le flux continu utilise chat.stream(), qui renvoie des paires (response, chunk)
  • Les erreurs sont des grpc.RpcError ; UNAVAILABLE est retenté automatiquement, le délai d’attente par défaut est de 27 minutes