xAI SDK: client.chat.create
Na tejto strane
Aktualizované 3. novembra 2026. Predchádzajúca verzia predpokladala, že
xai-sdkpoužíva rozhranie OpenAI SDK: správy ako slovníky,response.choices[0].message.content, parameterstream=Truea neexistujúci modulxai_sdk.errors. So skutočným SDK (verzia 1.21.0) tento kód zlyhá hneď pri prvom volaní:ValueError: unknown enum label "user". Táto lekcia teraz nasleduje oficiálny README SDK a každý príklad bol spustený proti xAI API (s falošným kľúčom na overenie cesty volania a chýb). Zdroje: xAI Python SDK · Najlepšie postupy (xAI) · Ladenie chýb (xAI).
Natívne xAI SDK
Oficiálne xAI SDK pre Python, xai-sdk, nepoužíva koncový bod REST Chat Completions: ide o knižnicu gRPC so synchronným klientom (Client) a asynchrónnym klientom (AsyncClient) pre Python 3.10 a novší. Nesnaží sa napodobniť OpenAI SDK a to je prvá vec, ktorú si musíš zapamätať: jeho objekty, metódy a chyby majú vlastnú štruktúru. Ak chceš znovu použiť kód napísaný pre OpenAI, ďalšia lekcia ukáže inú cestu – OpenAI SDK nakonfigurované pre xAI API.
Inštalácia a autentifikácia
pip install xai-sdk
Autentifikácia využíva API kľúč vytvorený v konzole xAI. Umiestni ho do premennej prostredia XAI_API_KEY, ktorú klient automaticky načíta:
export XAI_API_KEY="your-api-key"
Konverzácia, nie požiadavka
S týmto SDK client.chat.create() nič neodosiela: vytvára objekt konverzácie (chat), do ktorého pridávaš správy pomocou append a následne vyžiadaš odpoveď pomocou sample(). Správy sa vytvárajú funkciami system, user a assistant z modulu xai_sdk.chat, nie pomocou slovníkov.
from xai_sdk import Client
from xai_sdk.chat import system, user
client = Client() # načíta 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)
Odpoveď sprístupňuje svoj text priamo v response.content, spolu s finish_reason, usage (spotrebované tokeny), reasoning_content pre modely, ktoré ho poskytujú, a citations, ak sa vykonalo vyhľadávanie.
API zostáva bezstavové: objekt chat si za teba uchováva históriu. Pri konverzácii s viacerými kolami pridaj odpoveď do vlákna pred ďalšou otázkou:
chat.append(response)
chat.append(user("Give a concrete example of an application."))
print(chat.sample().content)
Parametre generovania
Parametre sa odovzdávajú do client.chat.create() a platia pre celú konverzáciu:
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: identifikátor modelu. xAI odporúčagrok-4.7pre všetky použitia.messages: počiatočné správy vytvorené pomocousystem,useraassistant.temperature: API akceptuje hodnoty od 0 do 2, ale xAI ich nad 1 orezáva a odporúča 0,7 stop_pnastaveným na 0,95.max_tokens: maximálny počet vygenerovaných tokenov. Najlepšie postupy xAI odporúčajú nastaviť túto hodnotu nad očakávanú dĺžku najdlhšej odpovede alebo ponechať predvolenú hodnotu.reasoning_effort: hĺbka uvažovania odnonepohigh(axhighna niektorých modeloch). Predvolená hodnota závisí od modelu: xAI odporúča nastaviť ju explicitne pri každej požiadavke a zaznamenať ju pri každom výsledku.response_format,tools,tool_choice: štruktúrované výstupy a volanie nástrojov, ktorými sa budeme zaoberať neskôr v kurze.
Existuje aj stop (až štyri sekvencie), ale najlepšie postupy xAI uvádzajú, že modely zamerané na uvažovanie ho neprijímajú, rovnako ako presence_penalty a frequency_penalty.
Streamovanie odpovedí
xAI odporúča streamovanie, najmä pri modeloch zameraných na uvažovanie, ktorých odpovede môžu trvať dlho. Nepoužíva sa parameter: konverzácia ponúka druhú metódu stream(), ktorá v každom kroku vráti dvojicu (response, chunk). chunk.content obsahuje práve dorazený textový fragment a response počas celého streamu akumuluje úplnú odpoveď.
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) # úplná odpoveď sa pripojí do histórie
Spracovanie chýb
Keďže SDK komunikuje cez gRPC, jeho chyby sú typu grpc.RpcError (asynchrónne grpc.aio.AioRpcError, ktoré z nich dedí). Ich kód čítaš pomocou .code() a správu pomocou .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()}")
Stoja za zmienku tri typy správania. SDK samo automaticky opakuje požiadavky, ktoré zlyhajú s chybou UNAVAILABLE, až päťkrát so zvyšujúcim sa oneskorením; jeho README ukazuje, ako pridať do tohto zoznamu ďalšie kódy, napríklad RESOURCE_EXHAUSTED, čo je kód gRPC pre vyčerpané kvóty. Časový limit čakania je predvolene nastavený na 27 minút pre akúkoľvek požiadavku a nastavuje sa pri vytvorení klienta (Client(timeout=…), v sekundách). Neznižuj ho príliš: xAI radí plánovať aspoň 900 sekúnd na požiadavku pri svojich modeloch zameraných na uvažovanie. Nakoniec, neplatný API kľúč sa prejaví kódom INVALID_ARGUMENT a správou „Incorrect API key provided“: toto je to, čo API vracia dnes, overené 3. novembra 2026.
Asynchrónne volania
Pre aplikáciu asyncio nahraď Client za AsyncClient. Vytvorenie konverzácie zostáva synchronické; čakajú sa iba sample() a stream():
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())
Kľúčové poznatky
xai-sdkje gRPC SDK s vlastným rozhraním: nepoužíva tvar ani objekty OpenAI SDKclient.chat.create()vytvára konverzáciu;chat.append(user(...))pridáva správu,chat.sample()vracia odpoveď čitateľnú vresponse.content- Správy sa vytvárajú pomocou
system,useraassistantzxai_sdk.chat; slovníky spôsobia zlyhanie volania - Streamovanie používa
chat.stream(), ktoré vracia dvojice(response, chunk) - Chyby sú typu
grpc.RpcError;UNAVAILABLEsa automaticky opakuje, predvolený časový limit je 27 minút