Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

xAI SDK: client.chat.create

Lekcija 4 od 12 Ažurirano 3. studenoga 2026. Programer
Na ovoj stranici
  1. Izvorni xAI SDK
  2. Instalacija i autentifikacija
  3. Razgovor, a ne zahtjev
  4. Parametri generiranja
  5. Strujanje odgovora (Streaming)
  6. Rukovanje greškama
  7. Asinkroni pozivi
  8. Ključne točke

Ažurirano 3. studenoga 2026. Prethodna verzija pretpostavljala je da xai-sdk koristi sučelje OpenAI SDK-a: poruke kao rječnici, response.choices[0].message.content, parametar stream=True i nepostojeći modul xai_sdk.errors. Sa stvarnim SDK-om (verzija 1.21.0), taj kod pada već pri prvom pozivu: ValueError: unknown enum label "user". Ova lekcija sada slijedi službeni README SDK-a, a svaki je primjer izvršen protiv xAI API-ja (s lažnim ključem, kako bi se verificirali putanja poziva i greške). Izvori: xAI Python SDK · Najbolje prakse (xAI) · Otklanjanje grešaka (xAI).

Izvorni xAI SDK

Službeni xAI SDK za Python, xai-sdk, ne koristi REST Chat Completions endpoint: to je gRPC biblioteka sa sinkronim klijentom (Client) i asinkronim klijentom (AsyncClient), za Python 3.10 i novije verzije. Ne pokušava oponašati OpenAI SDK, i to je prva stvar koju moraš imati na umu: njegovi objekti, metode i greške imaju vlastitu strukturu. Da bi ponovno iskoristio kod napisan za OpenAI, sljedeća lekcija prikazuje drugi put: OpenAI SDK konfiguriran za xAI API.

Instalacija i autentifikacija

pip install xai-sdk

Autentifikacija koristi API ključ kreiran u xAI konzoli. Postavi ga u varijablu okoline XAI_API_KEY, koju klijent automatski čita:

export XAI_API_KEY="your-api-key"

Razgovor, a ne zahtjev

S ovim SDK-om, client.chat.create() ništa ne šalje: on stvara objekt razgovora (chat), kojem dodaješ poruke s append, a zatim tražiš odgovor s sample(). Poruke se grade funkcijama system, user i assistant iz modula xai_sdk.chat, a ne rječnicima.

from xai_sdk import Client
from xai_sdk.chat import system, user

client = Client()  # čita 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 izlaže svoj tekst izravno u response.content, uz finish_reason, usage (potrošeni tokeni), reasoning_content za modele koji to izlažu i citations kada je provedeno pretraživanje.

API ostaje bez stanja (stateless): objekt chat čuva povijest umjesto tebe. Za višesmjerni razgovor, dodaj odgovor u nit prije sljedećeg pitanja:

chat.append(response)
chat.append(user("Give a concrete example of an application."))
print(chat.sample().content)

Parametri generiranja

Parametri se prosljeđuju u client.chat.create() i primjenjuju se na cijeli razgovor:

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 preporučuje grok-4.7 za sve upotrebe.
  • messages: početne poruke, izgrađene s system, user i assistant.
  • temperature: API prihvaća vrijednosti od 0 do 2, ali xAI to ograničava na 1 iznad te granice i preporučuje 0.7, s top_p na 0.95.
  • max_tokens: maksimalan broj generiranih tokena. Najbolje prakse xAI-ja preporučuju postavljanje iznad najduljeg očekivanog odgovora ili ostavljanje zadane vrijednosti.
  • reasoning_effort: dubina rezoniranja, od none do high (i xhigh na nekim modelima). Zadana vrijednost ovisi o modelu: xAI preporučuje da je eksplicitno postaviš u svakom zahtjevu i zabilježiš uz svaki rezultat.
  • response_format, tools, tool_choice: strukturirani izlazi i pozivanje alata, obrađeni kasnije u tečaju.

stop također postoji (do četiri sekvence), ali najbolje prakse xAI-ja navode da modeli za rezoniranje ne prihvaćaju ni njega ni presence_penalty i frequency_penalty.

Strujanje odgovora (Streaming)

xAI preporučuje strujanje, posebno s modelima za rezoniranje, čiji odgovori mogu dugo stizati. Ne koristi se parametar: razgovor nudi drugu metodu, stream(), koja u svakom koraku vraća par (response, chunk). chunk.content sadrži tekstualni fragment koji je upravo stigao, a response akumulira kompletan odgovor tijekom cijelog strujanja.

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)  # kompletan odgovor pridružuje se povijesti

Rukovanje greškama

Budući da SDK govori gRPC, njegove su greške grpc.RpcError (asinkrono, grpc.aio.AioRpcError, koje nasljeđuju od njih). Njihov kod čitaš s .code(), a poruku s .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()}")

Tri ponašanja vrijedi znati. SDK samostalno ponavlja zahtjeve koji ne uspiju s UNAVAILABLE, do pet pokušaja s rastućim kašnjenjem; njegov README pokazuje kako dodati druge kodove na ovaj popis, na primjer RESOURCE_EXHAUSTED, gRPC kod za iscrpljene kvote. Vrijeme čekanja (wait timeout) zadano je na 27 minuta za bilo koji zahtjev i postavlja se pri kreiranju klijenta (Client(timeout=…), u sekundama). Nemoj ga previše smanjivati: xAI savjetuje da planiraš najmanje 900 sekundi po zahtjevu sa svojim modelima za rezoniranje. Konačno, neispravan API ključ manifestira se kodom INVALID_ARGUMENT i porukom “Incorrect API key provided”: to je ono što API danas vraća, verificirano 3. studenoga 2026.

Asinkroni pozivi

Za asyncio aplikaciju, zamijeni Client s AsyncClient. Kreiranje razgovora ostaje sinkrono; sample() i stream() su oni koji čekaju (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())

Ključne točke

  • xai-sdk je gRPC SDK s vlastitim sučeljem: ne ponovno koristi oblik ni objekte OpenAI SDK-a
  • client.chat.create() stvara razgovor; chat.append(user(...)) dodaje poruku, chat.sample() vraća odgovor, koji se čita u response.content
  • Poruke se grade s system, user i assistant iz xai_sdk.chat; rječnici uzrokuju neuspjeh poziva
  • Strujanje koristi chat.stream(), koji vraća parove (response, chunk)
  • Greške su grpc.RpcError; UNAVAILABLE se automatski ponavlja, zadano vrijeme čekanja je 27 minuta