Salt la conținutul principal
Română— Alege o limbă
Meniu

xAI SDK: client.chat.create

Lecția 4 din 12 Actualizată 3 noiembrie 2026 Dezvoltator
Pe această pagină
  1. SDK-ul nativ xAI
  2. Instalare și autentificare
  3. O conversație, nu o cerere
  4. Parametri de generare
  5. Răspunsuri în flux (Streaming)
  6. Gestionarea erorilor
  7. Apeluri asincrone
  8. Puncte cheie

Actualizat la 3 noiembrie 2026. Versiunea anterioară presupunea că xai-sdk utiliza interfața SDK OpenAI: mesaje sub formă de dicționare, response.choices[0].message.content, parametrul stream=True și un modul inexistent xai_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.7 pentru toate utilizările.
  • messages: mesajele inițiale, construite cu system, user și assistant.
  • temperature: API-ul acceptă valori între 0 și 2, dar xAI limitează la 1 dincolo de această valoare și recomandă 0.7, cu top_p la 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 la none la high (și xhigh la 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-sdk este un SDK gRPC, cu propria interfață: nu reutilizează forma sau obiectele SDK-ului OpenAI
  • client.chat.create() creează o conversație; chat.append(user(...)) adaugă un mesaj, chat.sample() returnează răspunsul, citit în response.content
  • Mesajele sunt construite cu system, user și assistant din xai_sdk.chat; dicționarele cauzează eșecul apelului
  • Streaming-ul utilizează chat.stream(), care returnează perechi (response, chunk)
  • Erorile sunt grpc.RpcError; UNAVAILABLE este reîncercat automat, timeout-ul implicit este de 27 de minute