Ir para o conteúdo principal
Português— Escolher um idioma
Menu

xAI SDK: client.chat.create

Aula 4 de 12 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. O SDK nativo da xAI
  2. Instalação e autenticação
  3. Uma conversa, não um pedido
  4. Parâmetros de geração
  5. Respostas em streaming
  6. Tratamento de erros
  7. Chamadas assíncronas
  8. Pontos-chave

Atualizado em 3 de novembro de 2026. A versão anterior partia do princípio de que o xai-sdk utilizava a interface do SDK da OpenAI: mensagens como dicionários, response.choices[0].message.content, o parâmetro stream=True e um módulo inexistente xai_sdk.errors. Com o SDK real (versão 1.21.0), esse código falha na primeira chamada: ValueError: unknown enum label "user". Esta lição segue agora o README oficial do SDK e todos os exemplos foram executados contra a API da xAI (com uma chave fictícia, para verificar o caminho da chamada e os erros). Fontes: xAI Python SDK · Melhores práticas (xAI) · Depuração de Erros (xAI).

O SDK nativo da xAI

O SDK oficial da xAI para Python, xai-sdk, não utiliza o endpoint REST Chat Completions: é uma biblioteca gRPC, com um cliente síncrono (Client) e um cliente assíncrono (AsyncClient), para Python 3.10 e superiores. Não tenta imitar o SDK da OpenAI, e essa é a primeira coisa a ter em mente: os seus objetos, métodos e erros têm a sua própria estrutura. Para reutilizar código escrito para a OpenAI, a próxima lição mostra o outro caminho, o SDK da OpenAI configurado para a API da xAI.

Instalação e autenticação

pip install xai-sdk

A autenticação utiliza uma chave de API criada na consola da xAI. Coloque-a na variável de ambiente XAI_API_KEY, que o cliente lê automaticamente:

export XAI_API_KEY="your-api-key"

Uma conversa, não um pedido

Com este SDK, client.chat.create() não envia nada: cria um objeto de conversa (chat), ao qual adiciona mensagens com append, e depois solicita uma resposta com sample(). As mensagens são construídas com as funções system, user e assistant do módulo xai_sdk.chat, e não com dicionários.

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

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

A resposta expõe o seu texto diretamente em response.content, juntamente com finish_reason, usage (tokens consumidos), reasoning_content para modelos que o expõem, e citations quando foi realizada uma pesquisa.

A API permanece sem estado: o objeto chat mantém o histórico por si. Para uma conversa de várias voltas, adicione a resposta ao tópico antes da próxima pergunta:

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

Parâmetros de geração

Os parâmetros são passados para client.chat.create() e aplicam-se a toda a conversa:

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: o identificador do modelo. A xAI recomenda grok-4.7 para todos os usos.
  • messages: as mensagens iniciais, construídas com system, user e assistant.
  • temperature: a API aceita de 0 a 2, mas a xAI limita-a a 1 além desse valor e recomenda 0.7, com top_p em 0.95.
  • max_tokens: o número máximo de tokens gerados. As melhores práticas da xAI recomendam defini-lo acima da resposta mais longa esperada, ou deixar o valor padrão.
  • reasoning_effort: a profundidade do raciocínio, de none a high (e xhigh em alguns modelos). O padrão depende do modelo: a xAI recomenda defini-lo explicitamente em cada pedido e registá-lo com cada resultado.
  • response_format, tools, tool_choice: saídas estruturadas e chamada de ferramentas, abordadas mais adiante no curso.

O stop também existe (até quatro sequências), mas as melhores práticas da xAI especificam que os modelos de raciocínio não o aceitam, nem presence_penalty e frequency_penalty.

Respostas em streaming

A xAI recomenda o streaming, especialmente com modelos de raciocínio, cujas respostas podem demorar muito a chegar. Não utiliza um parâmetro: a conversa oferece um segundo método, stream(), que devolve um par (response, chunk) em cada passo. chunk.content contém o fragmento de texto que acabou de chegar, e response acumula a resposta completa ao longo do fluxo.

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)  # a resposta completa junta-se ao histórico

Tratamento de erros

Como o SDK fala gRPC, os seus erros são grpc.RpcError (assincronamente, grpc.aio.AioRpcError, que herdam deles). Lê o seu código com .code() e a mensagem com .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()}")

Há três comportamentos que vale a pena conhecer. O SDK tenta novamente automaticamente os pedidos que falham com UNAVAILABLE, até cinco tentativas com atraso crescente; o seu README mostra como adicionar outros códigos a esta lista, por exemplo RESOURCE_EXHAUSTED, o código gRPC para quotas esgotadas. O tempo limite de espera é de 27 minutos por padrão para qualquer pedido e é definido na criação do cliente (Client(timeout=…), em segundos). Não o reduza demasiado: a xAI aconselha planear pelo menos 900 segundos por pedido com os seus modelos de raciocínio. Por fim, uma chave de API inválida manifesta-se com o código INVALID_ARGUMENT e a mensagem “Incorrect API key provided”: é isto que a API devolve hoje, verificado em 3 de novembro de 2026.

Chamadas assíncronas

Para uma aplicação asyncio, substitua Client por AsyncClient. A criação da conversa permanece síncrona; sample() e stream() são os que aguardam:

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

Pontos-chave

  • xai-sdk é um SDK gRPC, com a sua própria interface: não reutiliza a forma ou os objetos do SDK da OpenAI
  • client.chat.create() cria uma conversa; chat.append(user(...)) adiciona uma mensagem, chat.sample() devolve a resposta, lida em response.content
  • As mensagens são construídas com system, user e assistant de xai_sdk.chat; os dicionários fazem a chamada falhar
  • O streaming usa chat.stream(), que devolve pares (response, chunk)
  • Os erros são grpc.RpcError; UNAVAILABLE é tentado novamente automaticamente, o tempo limite padrão é de 27 minutos