xAI SDK: client.chat.create
Na tej stronie
Zaktualizowano 3 listopada 2026 r. Poprzednia wersja zakładała, że
xai-sdkkorzysta z interfejsu OpenAI SDK: wiadomości jako słowniki,response.choices[0].message.content, parametrstream=Trueoraz nieistniejący modułxai_sdk.errors. W przypadku rzeczywistego SDK (wersja 1.21.0) taki kod zawodzi już przy pierwszym wywołaniu:ValueError: unknown enum label "user". Ta lekcja podąża teraz za oficjalnym plikiem README SDK, a każdy przykład został wykonany przeciwko API xAI (z fikcyjnym kluczem, aby zweryfikować ścieżkę wywołania i błędy). Źródła: xAI Python SDK · Najlepsze praktyki (xAI) · Debugowanie błędów (xAI).
Natywne SDK xAI
Oficjalne SDK xAI dla Pythona, xai-sdk, nie korzysta z punktu końcowego REST Chat Completions: jest to biblioteka gRPC, oferująca klienta synchronicznego (Client) i asynchronicznego (AsyncClient) dla Pythona 3.10 i nowszych. Nie próbuje ono naśladować OpenAI SDK i to jest pierwsza rzecz, o której musisz pamiętać: jego obiekty, metody i błędy mają własną strukturę. Aby wykorzystać kod napisany dla OpenAI, następna lekcja pokaże inną ścieżkę: skonfigurowanie OpenAI SDK pod API xAI.
Instalacja i uwierzytelnianie
pip install xai-sdk
Uwierzytelnianie odbywa się za pomocą klucza API utworzonego w konsoli xAI. Umieść go w zmiennej środowiskowej XAI_API_KEY, którą klient odczytuje automatycznie:
export XAI_API_KEY="your-api-key"
Konwersacja, a nie żądanie
W tym SDK client.chat.create() niczego nie wysyła: tworzy obiekt konwersacji (chat), do którego dodajesz wiadomości metodą append, a następnie żądasz odpowiedzi za pomocą sample(). Wiadomości buduje się za pomocą funkcji system, user i assistant z modułu xai_sdk.chat, a nie za pomocą słowników.
from xai_sdk import Client
from xai_sdk.chat import system, user
client = Client() # odczytuje 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)
Odpowiedź udostępnia swój tekst bezpośrednio w response.content, obok pól finish_reason, usage (zużyte tokeny), reasoning_content dla modeli, które je udostępniają, oraz citations, gdy przeprowadzono wyszukiwanie.
API pozostaje bezstanowe: obiekt chat przechowuje historię za Ciebie. W przypadku konwersacji wieloetapowej dodaj odpowiedź do wątku przed kolejnym pytaniem:
chat.append(response)
chat.append(user("Give a concrete example of an application."))
print(chat.sample().content)
Parametry generowania
Parametry przekazuje się do client.chat.create() i obowiązują one dla całej konwersacji:
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: identyfikator modelu. xAI rekomendujegrok-4.7do wszystkich zastosowań.messages: początkowe wiadomości, zbudowane za pomocąsystem,useriassistant.temperature: API akceptuje wartości od 0 do 2, ale xAI ogranicza je do 1 powyżej tej wartości i rekomenduje 0.7, ztop_pustawionym na 0.95.max_tokens: maksymalna liczba wygenerowanych tokenów. Najlepsze praktyki xAI zalecają ustawienie tej wartości powyżej najdłuższej oczekiwanej odpowiedzi lub pozostawienie wartości domyślnej.reasoning_effort: głębokość rozumowania, odnonedohigh(orazxhighw niektórych modelach). Wartość domyślna zależy od modelu: xAI zaleca jawne ustawianie jej w każdym żądaniu i odnotowywanie przy każdym wyniku.response_format,tools,tool_choice: strukturyzowane wyjścia i wywoływanie narzędzi, omówione później w kursie.
Istnieje również stop (do czterech sekwencji), ale najlepsze praktyki xAI określają, że modele rozumujące nie akceptują tego parametru, ani presence_penalty i frequency_penalty.
Strumieniowanie odpowiedzi
xAI zaleca strumieniowanie, zwłaszcza w przypadku modeli rozumujących, których odpowiedzi mogą przychodzić przez długi czas. Nie używa się do tego parametru: konwersacja oferuje drugą metodę, stream(), która zwraca parę (response, chunk) w każdym kroku. chunk.content zawiera fragment tekstu, który właśnie nadszedł, a response kumuluje pełną odpowiedź w trakcie strumieniowania.
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) # pełna odpowiedź dołącza do historii
Obsługa błędów
Ponieważ SDK komunikuje się przez gRPC, jego błędami są grpc.RpcError (w trybie asynchronicznym grpc.aio.AioRpcError, które po nich dziedziczą). Kod odczytujesz za pomocą .code(), a komunikat za pomocą .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()}")
Warto znać trzy zachowania. SDK samodzielnie ponawia żądania, które zakończyły się błędem UNAVAILABLE, do pięciu prób z rosnącym opóźnieniem; jego plik README pokazuje, jak dodać inne kody do tej listy, na przykład RESOURCE_EXHAUSTED, kod gRPC oznaczający wyczerpane limity. Czas oczekiwania (timeout) domyślnie wynosi 27 minut dla każdego żądania i ustawia się go podczas tworzenia klienta (Client(timeout=…), w sekundach). Nie zmniejszaj go zbyt mocno: xAI radzi planować co najmniej 900 sekund na żądanie w przypadku swoich modeli rozumujących. Na koniec, nieprawidłowy klucz API objawia się kodem INVALID_ARGUMENT i komunikatem “Incorrect API key provided”: tak zwraca API dzisiaj, zweryfikowano 3 listopada 2026 r.
Wywołania asynchroniczne
W aplikacji asyncio zamień Client na AsyncClient. Tworzenie konwersacji pozostaje synchroniczne; to sample() i stream() wymagają użycia 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())
Kluczowe wnioski
xai-sdkto SDK gRPC z własnym interfejsem: nie wykorzystuje ono kształtu ani obiektów OpenAI SDKclient.chat.create()tworzy konwersację;chat.append(user(...))dodaje wiadomość,chat.sample()zwraca odpowiedź, którą odczytujesz zresponse.content- Wiadomości buduje się za pomocą
system,useriassistantzxai_sdk.chat; użycie słowników powoduje niepowodzenie wywołania - Strumieniowanie korzysta z
chat.stream(), które zwraca pary(response, chunk) - Błędy to
grpc.RpcError;UNAVAILABLEjest automatycznie ponawiane, domyślny limit czasu wynosi 27 minut