xAI SDK: client.chat.create
Pe această pagină
Actualizat la 3 noiembrie 2026. Versiunea anterioară presupunea că
xai-sdkutiliza interfața SDK OpenAI: mesaje sub formă de dicționare,response.choices[0].message.content, parametrulstream=Trueși un modul inexistentxai_sdk.errors. Cu SDK-ul actual (versiunea 1.21.0), acel cod eșuează de la prima apelare:ValueError: unknown enum label "user". Această lecție urmează acum README-ul oficial al SDK-ului, iar fiecare exemplu a fost executat împotriva API-ului xAI (cu o cheie fictivă, pentru a verifica calea de apelare și erorile). Surse: xAI Python SDK · Best practices (xAI) · Debugging Errors (xAI).
SDK-ul nativ xAI
SDK-ul oficial xAI pentru Python, xai-sdk, nu utilizează punctul final REST Chat Completions: este o bibliotecă gRPC, dotată cu un client sincron (Client) și unul asincron (AsyncClient), pentru Python 3.10 și versiuni superioare. Acesta nu încearcă să imite SDK-ul OpenAI, iar acesta este primul aspect de reținut: obiectele, metodele și erorile sale au o structură proprie. Pentru a reutiliza codul scris pentru OpenAI, lecția următoare prezintă cealaltă abordare: configurarea SDK-ului OpenAI pentru API-ul xAI.
Instalare și autentificare
pip install xai-sdk
Autentificarea se face printr-o cheie API creată în consola xAI. Plasați-o în variabila de mediu XAI_API_KEY, pe care clientul o citește automat:
export XAI_API_KEY="your-api-key"
O conversație, nu o cerere
Cu acest SDK, client.chat.create() nu trimite nimic: creează un obiect conversație (chat), căruia îi adăugați mesaje prin append, apoi solicitați un răspuns cu sample(). Mesajele sunt construite cu funcțiile system, user și assistant din modulul xai_sdk.chat, nu cu dicționare.
from xai_sdk import Client
from xai_sdk.chat import system, user
client = Client() # citește 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)
Răspunsul expune textul direct în response.content, alături de finish_reason, usage (tokeni consumați), reasoning_content pentru modelele care îl expun și citations atunci când s-a efectuat o căutare.
API-ul rămâne fără stare (stateless): obiectul chat păstrează istoricul pentru dumneavoastră. Pentru o conversație cu mai multe tururi, adăugați răspunsul în firul de discuție înainte de următoarea întrebare:
chat.append(response)
chat.append(user("Give a concrete example of an application."))
print(chat.sample().content)
Parametri de generare
Parametrii sunt transmiși către client.chat.create() și se aplică întregii conversații:
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: identificatorul modelului. xAI recomandăgrok-4.7pentru toate utilizările.messages: mesajele inițiale, construite cusystem,userșiassistant.temperature: API-ul acceptă valori între 0 și 2, dar xAI limitează la 1 dincolo de această valoare și recomandă 0.7, cutop_pla 0.95.max_tokens: numărul maxim de tokeni generați. Cele mai bune practici xAI recomandă setarea acestei valori peste lungimea maximă așteptată a răspunsului sau lăsarea valorii implicite.reasoning_effort: profunzimea raționamentului, de lanonelahigh(șixhighla unele modele). Valoarea implicită depinde de model: xAI recomandă setarea explicită a acesteia la fiecare cerere și notarea ei împreună cu fiecare rezultat.response_format,tools,tool_choice: ieșiri structurate și apelarea instrumentelor, abordate mai târziu în curs.
Există și stop (până la patru secvențe), dar cele mai bune practici xAI specifică faptul că modelele de raționament nu îl acceptă, la fel cum nu acceptă nici presence_penalty și frequency_penalty.
Răspunsuri în flux (Streaming)
xAI recomandă utilizarea fluxului (streaming), în special cu modelele de raționament, ale căror răspunsuri pot dura mult timp până sosesc. Nu se utilizează un parametru: conversația oferă o a doua metodă, stream(), care returnează o pereche (response, chunk) la fiecare pas. chunk.content conține fragmentul de text care tocmai a sosit, iar response acumulează răspunsul complet pe tot parcursul fluxului.
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) # răspunsul complet se alătură istoricului
Gestionarea erorilor
Deoarece SDK-ul utilizează gRPC, erorile sale sunt grpc.RpcError (asincron, grpc.aio.AioRpcError, care moștenesc din acestea). Le citiți codul cu .code() și mesajul cu .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()}")
Trei comportamente merită cunoscute. SDK-ul reîncearcă automat cererile care eșuează cu UNAVAILABLE, de până la cinci ori, cu întârzieri crescătoare; README-ul său arată cum să adăugați alte coduri acestei liste, de exemplu RESOURCE_EXHAUSTED, codul gRPC pentru cote epuizate. Timpul de așteptare (timeout) este implicit de 27 de minute pentru orice cerere și se setează la crearea clientului (Client(timeout=…), în secunde). Nu îl reduceți prea mult: xAI sfătuiește să planificați cel puțin 900 de secunde per cerere pentru modelele sale de raționament. În final, o cheie API invalidă se manifestă prin codul INVALID_ARGUMENT și mesajul „Incorrect API key provided“: acesta este ceea ce returnează API-ul astăzi, verificat la 3 noiembrie 2026.
Apeluri asincrone
Pentru o aplicație asyncio, înlocuiți Client cu AsyncClient. Crearea conversației rămâne sincronă; sample() și stream() sunt cele care necesită await:
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())
Puncte cheie
xai-sdkeste un SDK gRPC, cu propria interfață: nu reutilizează forma sau obiectele SDK-ului OpenAIclient.chat.create()creează o conversație;chat.append(user(...))adaugă un mesaj,chat.sample()returnează răspunsul, citit înresponse.content- Mesajele sunt construite cu
system,userșiassistantdinxai_sdk.chat; dicționarele cauzează eșecul apelului - Streaming-ul utilizează
chat.stream(), care returnează perechi(response, chunk) - Erorile sunt
grpc.RpcError;UNAVAILABLEeste reîncercat automat, timeout-ul implicit este de 27 de minute