Lähe põhisisu juurde
Eesti— Vali keel
Menüü

xAI SDK: client.chat.create

Õppetund 4 / 12 Värskendatud 3. november 2026 Arendajatele
Sellel lehel
  1. Native xAI SDK
  2. Paigaldamine ja autentimine
  3. Vestlus, mitte päring
  4. Generatsiooni parameetrid
  5. Voogedastusvastused
  6. Vigade käsitlemine
  7. Asünkroonsed kutsed
  8. Peamised punktid

Uuendatud 3. novembril 2026. Eelmine versioon eeldas, et xai-sdk kasutab OpenAI SDK liidest: sõnumid sõnastikena, response.choices[0].message.content, parameeter stream=True ja olematut moodulit xai_sdk.errors. Tegeliku SDK-ga (versioon 1.21.0) nurjub see kood juba esimesel katsel: ValueError: unknown enum label "user". See tund järgib nüüd ametlikku SDK README-d ja iga näide on käivitatud xAI API vastu (kasutades võltsvõtit, et kontrollida kutse teed ja vigu). Allikad: xAI Python SDK · Parimad tavad (xAI) · Vigade silumine (xAI).

Native xAI SDK

Ametlik xAI SDK Pythonile, xai-sdk, ei kasuta REST Chat Completions lõpppunkti: see on gRPC teek, millel on sünkroonne klient (Client) ja asünkroonne klient (AsyncClient) Python 3.10 ja uuematele versioonidele. See ei püüa imiteerida OpenAI SDK-d ja see on esimene asi, mida meeles pidada: selle objektidel, meetoditel ja vigadel on oma struktuur. OpenAI jaoks kirjutatud koodi taaskasutamiseks näitab järgmine tund teist teed – OpenAI SDK seadistamist xAI API jaoks.

Paigaldamine ja autentimine

pip install xai-sdk

Autentimine kasutab xAI konsoolis loodud API võtit. Paiguta see keskkonnamuutujasse XAI_API_KEY, mille klient loeb automaatselt:

export XAI_API_KEY="your-api-key"

Vestlus, mitte päring

Selle SDK-ga client.chat.create() ei saada midagi: see loob vestluse objekti (chat), millele lisad sõnumeid meetodiga append, ning seejärel küsid vastust meetodiga sample(). Sõnumid ehitatakse funktsioonidega system, user ja assistant moodulist xai_sdk.chat, mitte sõnastikega.

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

client = Client()  # loeb 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)

Vastus avaldab oma teksti otse atribuudis response.content, koos finish_reason, usage (tarbitud tokenid), reasoning_content mudelitele, mis seda avaldavad, ja citations, kui tehti otsing.

API jääb olekuta: chat objekt hoiab ajalugu sinu eest. Mitmevoorulise vestluse jaoks lisa vastus lõimele enne järgmist küsimust:

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

Generatsiooni parameetrid

Parameetrid antakse edasi funktsioonile client.chat.create() ja need kehtivad kogu vestlusele:

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: mudeli identifikaator. xAI soovitab kõigeks kasutuseks grok-4.7.
  • messages: algseisundi sõnumid, ehitatud funktsioonidega system, user ja assistant.
  • temperature: API aktsepteerib vahemikku 0 kuni 2, kuid xAI piirab selle üle 1 väärtusega 1 ja soovitab 0.7 koos top_p väärtusega 0.95.
  • max_tokens: genereeritavate tokenite maksimaalne arv. xAI parimad tavad soovitavad seada see suuremaks kui eeldatavaim vastuse pikkus või jätta vaikeväärtus.
  • reasoning_effort: arutluse sügavus, vahemikus none kuni high (ja mõnel mudelil xhigh). Vaikeväärtus sõltub mudelist: xAI soovitab selle iga päringu puhul sõnaselgelt määrata ja iga tulemuse juures märkida.
  • response_format, tools, tool_choice: struktureeritud väljundid ja tööriistade kutsumine, mida käsitletakse kursuse hilisemas osas.

Samuti on olemas stop (kuni neli jada), kuid xAI parimad tavad täpsustavad, et arutlusmudelid ei aktsepteeri seda, nagu ka presence_penalty ja frequency_penalty.

Voogedastusvastused

xAI soovitab voogedastust, eriti arutlusmudelite puhul, mille vastuste saabumine võib kaua aega võtta. See ei kasuta parameetrit: vestlus pakub teist meetodit, stream(), mis tagastab igal sammul paari (response, chunk). chunk.content sisaldab äsja saabunud tekstifragmenti ja response kogub kogu vastuse voogedastuse vältel.

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)  # täielik vastus liitub ajalooga

Vigade käsitlemine

Kuna SDK räägib gRPC-i, on selle vead tüüpi grpc.RpcError (asünkroonselt grpc.aio.AioRpcError, mis pärinevad neist). Loed nende koodi .code() ja sõnumi .details() abil:

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()}")

Kolm käitumismudelit tasub teada. SDK proovib ise uuesti päringuid, mis ebaõnnestuvad veaga UNAVAILABLE, kuni viis korda kasvava viitega; selle README näitab, kuidas lisada sellesse nimekirja teisi koode, näiteks RESOURCE_EXHAUSTED, mis on gRPC kood ammendunud kvootide jaoks. Ooteaeg on vaikimisi iga päringu jaoks 27 minutit ja see määratakse kliendi loomisel (Client(timeout=…), sekundites). Ära vähenda seda liiga palju: xAI soovitab planeerida oma arutlusmudelitega vähemalt 900 sekundit päringu kohta. Lõpuks avaldub vigane API võti koodina INVALID_ARGUMENT ja sõnumiga “Incorrect API key provided”: seda tagastab API tänasel päeval, kontrollitud 3. novembril 2026.

Asünkroonsed kutsed

Asyncio rakenduse jaoks asenda Client väärtusega AsyncClient. Vestluse loomine jääb sünkroonseks; ootama jäävad sample() ja 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())

Peamised punktid

  • xai-sdk on gRPC SDK oma liidesega: see ei kasuta OpenAI SDK kuju ega objekte
  • client.chat.create() loob vestluse; chat.append(user(...)) lisab sõnumi, chat.sample() tagastab vastuse, mida loed response.content kaudu
  • Sõnumid ehitatakse funktsioonidega system, user ja assistant moodulist xai_sdk.chat; sõnastikud põhjustavad kutse nurjumise
  • Voogedastus kasutab chat.stream(), mis tagastab paarid (response, chunk)
  • Vead on tüüpi grpc.RpcError; UNAVAILABLE proovitakse automaatselt uuesti, vaikeajaületus on 27 minutit