xAI SDK: client.chat.create
Na tej strani
Posodobljeno 3. novembra 2026. Prejšnja različica je predpostavljala, da
xai-sdkuporablja vmesnik OpenAI SDK: sporočila kot slovarji,response.choices[0].message.content, parameterstream=Truein neobstoječ modulxai_sdk.errors. Z dejanskim SDK-jem (različica 1.21.0) ta koda odpove že ob prvem klicu:ValueError: unknown enum label "user". Ta lekcija zdaj sledi uradnemu README-ju SDK-ja, vsak primer pa je bil izvršen proti API-ju xAI (z lažnim ključem za preverjanje poti klica in napak). Viri: xAI Python SDK · Najboljše prakse (xAI) · Odpravljanje napak (xAI).
Izvirni xAI SDK
Uradni xAI SDK za Python, xai-sdk, ne uporablja končne točke REST Chat Completions: gre za knjižnico gRPC s sinhronim odjemalcem (Client) in asinhronim odjemalcem (AsyncClient) za Python 3.10 in novejše. Ne poskuša posnemati OpenAI SDK-ja, kar je prva stvar, ki jo moraš imeti v mislih: njegovi objekti, metode in napake imajo svojo strukturo. Če želiš ponovno uporabiti kodo, napisano za OpenAI, naslednja lekcija prikazuje drugo pot: OpenAI SDK, konfiguriran za API xAI.
Namestitev in avtentikacija
pip install xai-sdk
Avtentikacija uporablja ključ API, ustvarjen v konzoli xAI. Postavi ga v okoljsko spremenljivko XAI_API_KEY, ki jo odjemalec samodejno prebere:
export XAI_API_KEY="your-api-key"
Pogovor, ne zahtevek
S tem SDK-jem client.chat.create() ničesar ne pošlje: ustvari objekt pogovora (chat), kateremu dodaš sporočila z append, nato pa z sample() zahtevaš odgovor. Sporočila gradiš s funkcijami system, user in assistant iz modula xai_sdk.chat, ne s slovarji.
from xai_sdk import Client
from xai_sdk.chat import system, user
client = Client() # prebere 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)
Odgovor neposredno razkrije besedilo v response.content, poleg tega pa vsebuje še finish_reason, usage (porabljeni žetoni), reasoning_content za modele, ki to omogočajo, in citations, ko je bilo opravljeno iskanje.
API ostaja brez stanja: objekt chat namesto tebe hrani zgodovino. Za večkratni pogovor dodaj odgovor v nit pred naslednjim vprašanjem:
chat.append(response)
chat.append(user("Give a concrete example of an application."))
print(chat.sample().content)
Parametri generiranja
Parametre posreduješ client.chat.create() in veljajo za celoten pogovor:
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: identifikator modela. xAI za vse uporabe priporočagrok-4.7.messages: začetna sporočila, zgrajena ssystem,userinassistant.temperature: API sprejme vrednosti od 0 do 2, vendar jih xAI nad 1 omeji na 1 in priporoča 0,7 ztop_pna 0,95.max_tokens: največje število ustvarjenih žetonov. Najboljše prakse xAI priporočajo, da ga nastaviš nad najdaljši pričakovani odgovor ali pustiš privzeto vrednost.reasoning_effort: globina razmišljanja, odnonedohigh(inxhighpri nekaterih modelih). Privzeta vrednost je odvisna od modela: xAI priporoča, da jo nastaviš eksplicitno pri vsaki zahtevi in jo zabeležiš ob vsakem rezultatu.response_format,tools,tool_choice: strukturirani izhodi in klicanje orodij, obravnavani kasneje v tečaju.
Obstaja tudi stop (do štiri zaporedja), vendar najboljše prakse xAI določajo, da modeli za razmišljanje tega ne sprejemajo, prav tako ne presence_penalty in frequency_penalty.
Pretakanje odgovorov
xAI priporoča pretakanje, zlasti pri modelih za razmišljanje, katerih odgovori lahko prihajajo dolgo časa. Ne uporablja parametra: pogovor ponuja drugo metodo, stream(), ki na vsakem koraku vrne par (response, chunk). chunk.content vsebuje del besedila, ki je pravkar prispel, response pa skozi celoten pretok kopiči popoln odgovor.
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) # popoln odgovor se pridruži zgodovini
Obravnava napak
Ker SDK govori gRPC, so njegove napake tipa grpc.RpcError (asinhrono grpc.aio.AioRpcError, ki iz njega dedujejo). Kodo prebereš z .code(), sporočilo pa z .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()}")
Vredno je poznati tri vedenja. SDK samodejno ponovi zahtevke, ki odpovejo z UNAVAILABLE, do petkrat z naraščajočim zamikom; njegov README prikazuje, kako temu seznamu dodati druge kode, na primer RESOURCE_EXHAUSTED, kodo gRPC za izčrpane kvote. Časovna omejitev čakanja je privzeto 27 minut za katero koli zahtevo in se nastavi ob ustvarjanju odjemalca (Client(timeout=…), v sekundah). Ne zmanjšuj je preveč: xAI svetuje, da pri njegovih modelih za razmišljanje načrtuješ vsaj 900 sekund na zahtevo. Končno, neveljaven ključ API se kaže kot koda INVALID_ARGUMENT in sporočilo “Incorrect API key provided”: to je tisto, kar API vrača danes, preverjeno 3. novembra 2026.
Asinhroni klici
Za aplikacijo asyncio zamenjaj Client z AsyncClient. Ustvarjanje pogovora ostaja sinhrono; čakata pa sample() in 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())
Ključne ugotovitve
xai-sdkje SDK gRPC z lastnim vmesnikom: ne ponovno uporablja oblike ali objektov OpenAI SDK-jaclient.chat.create()ustvari pogovor;chat.append(user(...))doda sporočilo,chat.sample()vrne odgovor, ki ga prebereš vresponse.content- Sporočila so zgrajena s
system,userinassistantizxai_sdk.chat; slovarji povzročijo neuspeh klica - Pretakanje uporablja
chat.stream(), ki vrača pare(response, chunk) - Napake so
grpc.RpcError;UNAVAILABLEse samodejno ponovi, privzeti časovni limit je 27 minut