xAI SDK: client.chat.create
Auf dieser Seite
Aktualisiert am 3. November 2026. Die vorherige Version ging davon aus, dass das
xai-sdkdie Schnittstelle des OpenAI SDKs verwendet: Nachrichten als Wörterbücher,response.choices[0].message.content, der Parameterstream=Trueund eine nicht existierendexai_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 empfiehltgrok-4.7für alle Anwendungen.messages: Die initialen Nachrichten, erstellt mitsystem,userundassistant.temperature: Die API akzeptiert Werte von 0 bis 2, aber xAI begrenzt sie ab diesem Wert auf 1 und empfiehlt 0,7, mittop_pbei 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, vonnonebishigh(undxhighbei 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-sdkist ein gRPC SDK mit eigener Schnittstelle: Es nutzt nicht die Form oder Objekte des OpenAI SDKsclient.chat.create()erstellt ein Gespräch;chat.append(user(...))fügt eine Nachricht hinzu,chat.sample()gibt die Antwort zurück, die inresponse.contentgelesen wird- Nachrichten werden mit
system,userundassistantausxai_sdk.chaterstellt; Wörterbücher führen zum Scheitern des Aufrufs - Streaming verwendet
chat.stream(), das Paare(response, chunk)zurückgibt - Fehler sind
grpc.RpcError;UNAVAILABLEwird automatisch neu versucht, der Standard-Timeout beträgt 27 Minuten