xAI SDK: client.chat.create
На тази страница
Обновено на 3 ноември 2026 г. Предишната версия приемаше, че
xai-sdkизползва интерфейса на OpenAI SDK: съобщения като речници,response.choices[0].message.content, параметърътstream=Trueи несъществуващия модулxai_sdk.errors. При действителния SDK (версия 1.21.0) този код се проваля още при първото извикване:ValueError: unknown enum label "user". Настоящият урок следва официалния README на SDK, като всеки пример е изпълнен срещу xAI API (с фиктивен ключ, за да се провери пътят на извикване и грешките). Източници: xAI Python SDK · Най-добри практики (xAI) · Отстраняване на грешки (xAI).
Нативният xAI SDK
Официалният xAI SDK за Python, xai-sdk, не използва крайната точка REST Chat Completions: това е библиотека gRPC със синхронен клиент (Client) и асинхронен клиент (AsyncClient) за Python 3.10 и по-нови версии. Той не се опитва да имитира OpenAI SDK и това е първото нещо, което трябва да имате предвид: неговите обекти, методи и грешки имат собствена структура. За да използвате повторно код, написан за OpenAI, следващият урок показва другия път – OpenAI SDK, конфигуриран за xAI API.
Инсталация и удостоверяване
pip install xai-sdk
Удостоверяването използва API ключ, създаден в конзолата на xAI. Поставете го в променливата на средата XAI_API_KEY, която клиентът прочита автоматично:
export XAI_API_KEY="your-api-key"
Разговор, а не заявка
С този SDK client.chat.create() не изпраща нищо: той създава обект за разговор (chat), към който добавяте съобщения с append, след което искате отговор с sample(). Съобщенията се изграждат с функциите system, user и assistant от модула xai_sdk.chat, а не с речници.
from xai_sdk import Client
from xai_sdk.chat import system, user
client = Client() # чете 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)
Отговорът излага текста си директно в response.content, заедно с finish_reason, usage (консумирани токени), reasoning_content за моделите, които го предоставят, и citations, когато е извършено търсене.
API остава без състояние: обектът chat пази историята вместо Вас. За разговор с много обороти добавете отговора към нишката преди следващия въпрос:
chat.append(response)
chat.append(user("Give a concrete example of an application."))
print(chat.sample().content)
Параметри за генериране
Параметрите се предават на client.chat.create() и важат за целия разговор:
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: идентификаторът на модела. xAI препоръчваgrok-4.7за всички употреби.messages: началните съобщения, изградени сsystem,userиassistant.temperature: API приема стойности от 0 до 2, но xAI ги ограничава до 1 над тази граница и препоръчва 0.7, катоtop_pе 0.95.max_tokens: максималният брой генерирани токени. Най-добрите практики на xAI препоръчват да го зададете над най-дългия очакван отговор или да оставите стойността по подразбиране.reasoning_effort: дълбочината на разсъждението, отnoneдоhigh(иxhighпри някои модели). Стойността по подразбиране зависи от модела: xAI препоръчва да я задавате изрично при всяка заявка и да я отбелязвате с всеки резултат.response_format,tools,tool_choice: структурирани изходи и извикване на инструменти, разгледани по-късно в курса.
Съществува и stop (до четири последователности), но най-добрите практики на xAI уточняват, че моделите за разсъждане не го приемат, нито presence_penalty и frequency_penalty.
Поточни отговори (Streaming)
xAI препоръчва поточно предаване, особено при модели за разсъждане, чиито отговори могат да отнемат много време. То не използва параметър: разговорът предлага втори метод, stream(), който връща двойка (response, chunk) на всяка стъпка. chunk.content съдържа текстовия фрагмент, който току-що е пристигнал, а response натрупва пълния отговор през целия поток.
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) # пълният отговор се присъединява към историята
Обработка на грешки
Тъй като SDK използва gRPC, неговите грешки са grpc.RpcError (асинхронно grpc.aio.AioRpcError, които наследяват от тях). Четете кода им с .code(), а съобщението – с .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()}")
Трябва да знаете три поведения. SDK повтаря автоматично заявките, които се провалят с UNAVAILABLE, до пет опита с нарастващо забавяне; неговият README показва как да добавите други кодове към този списък, например RESOURCE_EXHAUSTED – gRPC кодът за изчерпани квоти. Времето за изчакване по подразбиране е 27 минути за всяка заявка и се задава при създаването на клиента (Client(timeout=…), в секунди). Не го намалявайте твърде много: xAI съветва да планирате поне 900 секунди на заявка за своите модели за разсъждане. Накрая, невалиден API ключ се проявява с код INVALID_ARGUMENT и съобщение “Incorrect API key provided”: това връща API днес, проверено на 3 ноември 2026 г.
Асинхронни извиквания
За приложение с asyncio заменете Client с AsyncClient. Създаването на разговор остава синхронно; sample() и stream() са тези, които изчакват (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())
Ключови изводи
xai-sdkе gRPC SDK със собствен интерфейс: той не използва формата или обектите на OpenAI SDKclient.chat.create()създава разговор;chat.append(user(...))добавя съобщение,chat.sample()връща отговора, който се чете отresponse.content- Съобщенията се изграждат с
system,userиassistantотxai_sdk.chat; речниците причиняват провал на извикването - Поточното предаване използва
chat.stream(), което връща двойки(response, chunk) - Грешките са
grpc.RpcError;UNAVAILABLEсе повтаря автоматично, времето за изчакване по подразбиране е 27 минути