Премини към основното съдържание
Български— Изберете език
Меню

xAI SDK: client.chat.create

Урок 4 от 12 Обновен 3 ноември 2026 г. Програмист
На тази страница
  1. Нативният xAI SDK
  2. Инсталация и удостоверяване
  3. Разговор, а не заявка
  4. Параметри за генериране
  5. Поточни отговори (Streaming)
  6. Обработка на грешки
  7. Асинхронни извиквания
  8. Ключови изводи

Обновено на 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 SDK
  • client.chat.create() създава разговор; chat.append(user(...)) добавя съобщение, chat.sample() връща отговора, който се чете от response.content
  • Съобщенията се изграждат с system, user и assistant от xai_sdk.chat; речниците причиняват провал на извикването
  • Поточното предаване използва chat.stream(), което връща двойки (response, chunk)
  • Грешките са grpc.RpcError; UNAVAILABLE се повтаря автоматично, времето за изчакване по подразбиране е 27 минути