Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

xAI SDK: client.chat.create

Lekcija 4 od 12 Posodobljeno 3. november 2026 Razvijalec
Na tej strani
  1. Izvirni xAI SDK
  2. Namestitev in avtentikacija
  3. Pogovor, ne zahtevek
  4. Parametri generiranja
  5. Pretakanje odgovorov
  6. Obravnava napak
  7. Asinhroni klici
  8. Ključne ugotovitve

Posodobljeno 3. novembra 2026. Prejšnja različica je predpostavljala, da xai-sdk uporablja vmesnik OpenAI SDK: sporočila kot slovarji, response.choices[0].message.content, parameter stream=True in neobstoječ modul xai_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ča grok-4.7.
  • messages: začetna sporočila, zgrajena s system, user in assistant.
  • temperature: API sprejme vrednosti od 0 do 2, vendar jih xAI nad 1 omeji na 1 in priporoča 0,7 z top_p na 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, od none do high (in xhigh pri 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-sdk je SDK gRPC z lastnim vmesnikom: ne ponovno uporablja oblike ali objektov OpenAI SDK-ja
  • client.chat.create() ustvari pogovor; chat.append(user(...)) doda sporočilo, chat.sample() vrne odgovor, ki ga prebereš v response.content
  • Sporočila so zgrajena s system, user in assistant iz xai_sdk.chat; slovarji povzročijo neuspeh klica
  • Pretakanje uporablja chat.stream(), ki vrača pare (response, chunk)
  • Napake so grpc.RpcError; UNAVAILABLE se samodejno ponovi, privzeti časovni limit je 27 minut