Przejdź do głównej treści
Polski— Wybierz język
Menu

xAI SDK: client.chat.create

Lekcja 4 z 12 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Natywne SDK xAI
  2. Instalacja i uwierzytelnianie
  3. Konwersacja, a nie żądanie
  4. Parametry generowania
  5. Strumieniowanie odpowiedzi
  6. Obsługa błędów
  7. Wywołania asynchroniczne
  8. Kluczowe wnioski

Zaktualizowano 3 listopada 2026 r. Poprzednia wersja zakładała, że xai-sdk korzysta z interfejsu OpenAI SDK: wiadomości jako słowniki, response.choices[0].message.content, parametr stream=True oraz 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 rekomenduje grok-4.7 do wszystkich zastosowań.
  • messages: początkowe wiadomości, zbudowane za pomocą system, user i assistant.
  • temperature: API akceptuje wartości od 0 do 2, ale xAI ogranicza je do 1 powyżej tej wartości i rekomenduje 0.7, z top_p ustawionym 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, od none do high (oraz xhigh w 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-sdk to SDK gRPC z własnym interfejsem: nie wykorzystuje ono kształtu ani obiektów OpenAI SDK
  • client.chat.create() tworzy konwersację; chat.append(user(...)) dodaje wiadomość, chat.sample() zwraca odpowiedź, którą odczytujesz z response.content
  • Wiadomości buduje się za pomocą system, user i assistant z xai_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; UNAVAILABLE jest automatycznie ponawiane, domyślny limit czasu wynosi 27 minut