xAI SDK: client.chat.create
Ezen az oldalon
Frissítve: 2026. november 3. Az előző verzió tévesen feltételezte, hogy az
xai-sdkaz OpenAI SDK interfészét használja: üzenetek szótárként,response.choices[0].message.content, astream=Trueparaméter és egy nem létezőxai_sdk.errorsmodul. A valós SDK-val (1.21.0 verzió) ez a kód már az első hívásnál elbukik:ValueError: unknown enum label "user". Ez a lecke most a hivatalos SDK README-jét követi, és minden példát lefuttattunk az xAI API ellen (egy teszt-kulccsal), hogy ellenőrizzük a hívási útvonalat és a hibákat. Források: xAI Python SDK · Legjobb gyakorlatok (xAI) · Hibakeresés (xAI).
A natív xAI SDK
A hivatalos xAI Python SDK, az xai-sdk, nem a REST Chat Completions végpontot használja: ez egy gRPC könyvtár, szinkron (Client) és aszinkron (AsyncClient) klienssel, Python 3.10 és újabb verziókhoz. Nem próbálja utánozni az OpenAI SDK-t, és ez az első dolog, amit észben kell tartanod: az objektumai, metódusai és hibái saját struktúrával rendelkeznek. Ha OpenAI-hoz írt kódot szeretnél újrahasználni, a következő lecke mutatja a másik utat: az xAI API-ra konfigurált OpenAI SDK-t.
Telepítés és hitelesítés
pip install xai-sdk
A hitelesítéshez az xAI konzolban létrehozott API-kulcsot használd. Helyezd el a kulcsot az XAI_API_KEY környezeti változóban, amelyet a kliens automatikusan beolvas:
export XAI_API_KEY="your-api-key"
Beszélgetés, nem pedig kérés
Ezzel az SDK-val a client.chat.create() nem küld semmit közvetlenül: létrehoz egy beszélgetés objektumot (chat), amelyhez az append metódussal adsz hozzá üzeneteket, majd a sample() metódussal kérsz választ. Az üzeneteket nem szótárakkal, hanem az xai_sdk.chat modul system, user és assistant függvényeivel építed fel.
from xai_sdk import Client
from xai_sdk.chat import system, user
client = Client() # beolvassa az XAI_API_KEY változót
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)
A válasz szövege közvetlenül a response.content attribútumban érhető el, mellette megtalálod a finish_reason, a usage (felhasznált tokenek), a reasoning_content (azoknál a modelleknél, amelyek kiadják) és a citations (keresés végrehajtása esetén) adatokat is.
Az API továbbra is állapot nélküli (stateless): a chat objektum őrzi meg számodra az előzményeket. Több körös beszélgetéshez add hozzá a választ a szálhoz a következő kérdés előtt:
chat.append(response)
chat.append(user("Give a concrete example of an application."))
print(chat.sample().content)
Generálási paraméterek
A paramétereket a client.chat.create() híváskor adod meg, és az egész beszélgetésre vonatkoznak:
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: a modell azonosítója. Az xAI minden használathoz agrok-4.7modellt javasolja.messages: a kezdeti üzenetek, amelyeket asystem,userésassistantfüggvényekkel építesz fel.temperature: az API 0 és 2 közötti értéket fogad el, de az xAI 1 fölé korlátozza, és a 0,7-es értéket javasolja,top_pesetén pedig 0,95-öt.max_tokens: a generált tokenek maximális száma. Az xAI legjobb gyakorlatai szerint állítsd ezt a várható leghosszabb válasz fölé, vagy hagyd az alapértelmezett értéken.reasoning_effort: a következtetés mélysége,none-tólhigh-ig (és egyes modelleknélxhigh). Az alapértelmezés modellenként változik: az xAI javasolja, hogy minden kérésnél állítsd be expliciten, és jegyezd fel minden eredményhez.response_format,tools,tool_choice: strukturált kimenetek és eszköz hívások (tool calling), amelyeket a tanfolyam későbbi részében tárgyalunk.
Létezik a stop paraméter is (legfeljebb négy szekvencia), de az xAI legjobb gyakorlatai szerint a következtető modellek nem fogadják el ezt, sem a presence_penalty, sem a frequency_penalty paramétereket.
Folyamatos válaszok (Streaming)
Az xAI a folyamatos választ (streaming) javasolja, különösen a következtető modelleknél, amelyek válasza sokáig tarthat. Ehhez nem paramétert használsz: a beszélgetés objektum rendelkezik egy második metódussal, a stream()-mel, amely minden lépésben egy (response, chunk) párt ad vissza. A chunk.content tartalmazza az éppen megérkezett szövegrészletet, míg a response a teljes választ halmozza fel a streamelés során.
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) # a teljes válasz csatlakozik az előzményekhez
Hibakezelés
Mivel az SDK gRPC-t használ, a hibái grpc.RpcError típusúak (aszinkron esetben grpc.aio.AioRpcError, amelyek ezekből örökölnek). A kódot a .code(), az üzenetet pedig a .details() metódussal olvashatod ki:
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()}")
Három viselkedést érdemes ismerned. Az SDK automatikusan újrapróbálja azokat a kéréseket, amelyek UNAVAILABLE hibával buknak el, legfeljebb öt alkalommal, növekvő késleltetéssel; a README bemutatja, hogyan adhatsz további kódokat ehhez a listához, például a RESOURCE_EXHAUSTED-et, ami a gRPC kódja a kimerített kvótákra. A várakozási időtúllépés (wait timeout) alapértelmezés szerint 27 perc bármely kérésre, és a kliens létrehozásakor állítható be (Client(timeout=…), másodpercben). Ne csökkentsd túl sokat: az xAI azt tanácsolja, hogy következtető modellek használatakor legalább 900 másodpercet tervezz kérésenként. Végül, egy érvénytelen API-kulcs az INVALID_ARGUMENT kóddal és az „Incorrect API key provided“ üzenettel jelentkezik: ezt adja vissza az API jelenleg, ellenőrizve 2026. november 3-án.
Aszinkron hívások
Egy asyncio alkalmazáshoz cseréld le a Client-t AsyncClient-re. A beszélgetés létrehozása szinkron marad; a sample() és a stream() metódusokra kell várni (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())
Főbb megállapítások
- Az
xai-sdkegy gRPC SDK, saját interfésszel: nem használja újra az OpenAI SDK alakzatait vagy objektumait - A
client.chat.create()létrehoz egy beszélgetést; achat.append(user(...))hozzáad egy üzenetet, achat.sample()visszaadja a választ, amelyet aresponse.content-ban olvashatsz - Az üzeneteket az
xai_sdk.chatmodulsystem,userésassistantfüggvényeivel építed fel; a szótárak miatt a hívás meghiúsul - A streameléshez a
chat.stream()metódust használd, amely(response, chunk)párokat ad vissza - A hibák
grpc.RpcErrortípusúak; azUNAVAILABLEhibát az SDK automatikusan újrapróbálja, az alapértelmezett időtúllépés pedig 27 perc