Zum Hauptinhalt springen
Deutsch— Sprache auswählen
Menü

xAI SDK: client.chat.create

Lektion 4 von 12 Aktualisiert am 3. November 2026 Entwickler
Auf dieser Seite
  1. Das native xAI SDK
  2. Installation und Authentifizierung
  3. Ein Gespräch, keine Anfrage
  4. Generierungsparameter
  5. Streaming-Antworten
  6. Fehlerbehandlung
  7. Asynchrone Aufrufe
  8. Kernaussagen

Aktualisiert am 3. November 2026. Die vorherige Version ging davon aus, dass das xai-sdk die Schnittstelle des OpenAI SDKs verwendet: Nachrichten als Wörterbücher, response.choices[0].message.content, der Parameter stream=True und eine nicht existierende xai_sdk.errors-Modul. Mit dem tatsächlichen SDK (Version 1.21.0) schlägt dieser Code beim ersten Aufruf fehl: ValueError: unknown enum label "user". Diese Lektion folgt nun dem offiziellen SDK README, und jedes Beispiel wurde gegen die xAI-API ausgeführt (mit einem Dummy-Schlüssel, um den Aufrufpfad und Fehler zu verifizieren). Quellen: xAI Python SDK · Best Practices (xAI) · Debugging Errors (xAI).

Das native xAI SDK

Das offizielle xAI SDK für Python, xai-sdk, verwendet nicht den REST Chat Completions-Endpunkt: Es handelt sich um eine gRPC-Bibliothek mit einem synchronen Client (Client) und einem asynchronen Client (AsyncClient) für Python 3.10 und höher. Es versucht nicht, das OpenAI SDK nachzuahmen, und das ist der erste Punkt, den Sie beachten müssen: Seine Objekte, Methoden und Fehler haben ihre eigene Struktur. Um Code, der für OpenAI geschrieben wurde, wiederverwenden zu können, zeigt die nächste Lektion den anderen Weg: das OpenAI SDK, das für die xAI-API konfiguriert ist.

Installation und Authentifizierung

pip install xai-sdk

Die Authentifizierung erfolgt über einen API-Schlüssel, der in der xAI-Konsole erstellt wurde. Platzieren Sie ihn in der Umgebungsvariable XAI_API_KEY, die der Client automatisch liest:

export XAI_API_KEY="your-api-key"

Ein Gespräch, keine Anfrage

Mit diesem SDK sendet client.chat.create() nichts: Es erstellt ein Gesprächsobjekt (chat), zu dem Sie mit append Nachrichten hinzufügen, und Sie fordern mit sample() eine Antwort an. Nachrichten werden mit den Funktionen system, user und assistant aus dem Modul xai_sdk.chat erstellt, nicht mit Wörterbüchern.

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

client = Client()  # liest 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)

Die Antwort gibt ihren Text direkt in response.content aus, zusammen mit finish_reason, usage (verwendete Tokens), reasoning_content für Modelle, die es bereitstellen, und citations, wenn eine Suche durchgeführt wurde.

Die API bleibt zustandslos: Das chat-Objekt verwaltet die Historie für Sie. Für ein mehrstufiges Gespräch fügen Sie die Antwort dem Thread vor der nächsten Frage hinzu:

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

Generierungsparameter

Parameter werden an client.chat.create() übergeben und gelten für das gesamte Gespräch:

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: Die Modell-Identifizierung. xAI empfiehlt grok-4.7 für alle Anwendungen.
  • messages: Die initialen Nachrichten, erstellt mit system, user und assistant.
  • temperature: Die API akzeptiert Werte von 0 bis 2, aber xAI begrenzt sie ab diesem Wert auf 1 und empfiehlt 0,7, mit top_p bei 0,95.
  • max_tokens: Die maximale Anzahl generierter Tokens. Die Best Practices von xAI empfehlen, diesen Wert über die längste erwartete Antwort zu setzen oder den Standardwert zu belassen.
  • reasoning_effort: Die Tiefe der Reasoning-Fähigkeiten, von none bis high (und xhigh bei einigen Modellen). Der Standardwert hängt vom Modell ab: xAI empfiehlt, ihn bei jeder Anfrage explizit festzulegen und bei jedem Ergebnis zu notieren.
  • response_format, tools, tool_choice: Strukturierte Ausgaben und Tool-Aufrufe, die später im Kurs behandelt werden.

stop existiert ebenfalls (bis zu vier Sequenzen), aber die Best Practices von xAI geben an, dass Reasoning-Modelle dies nicht akzeptieren, ebenso wenig wie presence_penalty und frequency_penalty.

Streaming-Antworten

xAI empfiehlt Streaming, insbesondere bei Reasoning-Modellen, deren Antworten lange dauern können. Es wird kein Parameter verwendet: Das Gespräch bietet eine zweite Methode, stream(), die bei jedem Schritt ein Paar (response, chunk) zurückgibt. chunk.content enthält den Textfragment, das gerade eingetroffen ist, und response sammelt die vollständige Antwort während des Streams.

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)  # die vollständige Antwort geht in die Historie ein

Fehlerbehandlung

Da das SDK gRPC verwendet, sind seine Fehler grpc.RpcError (asynchron grpc.aio.AioRpcError, die von diesen vererbt werden). Sie lesen ihren Code mit .code() und die Nachricht mit .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()}")

Drei Verhaltensweisen sind zu beachten. Das SDK versucht von selbst Anfragen, die mit UNAVAILABLE fehlschlagen, bis zu fünfmal mit zunehmender Verzögerung; das README zeigt, wie Sie andere Codes zu dieser Liste hinzufügen können, beispielsweise RESOURCE_EXHAUSTED, der gRPC-Code für erschöpfte Quoten. Die Wartezeit-Timeout-Einstellung beträgt standardmäßig 27 Minuten für jede Anfrage und wird bei der Client-Erstellung festgelegt (Client(timeout=…), in Sekunden). Reduzieren Sie diesen Wert nicht zu stark: xAI rät dazu, für Reasoning-Modelle mindestens 900 Sekunden pro Anfrage zu planen. Schließlich manifestiert sich ein ungültiger API-Schlüssel als Code INVALID_ARGUMENT und die Nachricht “Incorrect API key provided”: Dies ist das, was die API heute zurückgibt, verifiziert am 3. November 2026.

Asynchrone Aufrufe

Für eine asyncio-Anwendung ersetzen Sie Client durch AsyncClient. Die Gesprächserstellung bleibt synchron; sample() und stream() sind die, die warten:

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())

Kernaussagen

  • xai-sdk ist ein gRPC SDK mit eigener Schnittstelle: Es nutzt nicht die Form oder Objekte des OpenAI SDKs
  • client.chat.create() erstellt ein Gespräch; chat.append(user(...)) fügt eine Nachricht hinzu, chat.sample() gibt die Antwort zurück, die in response.content gelesen wird
  • Nachrichten werden mit system, user und assistant aus xai_sdk.chat erstellt; Wörterbücher führen zum Scheitern des Aufrufs
  • Streaming verwendet chat.stream(), das Paare (response, chunk) zurückgibt
  • Fehler sind grpc.RpcError; UNAVAILABLE wird automatisch neu versucht, der Standard-Timeout beträgt 27 Minuten