L'SDK Python di xAI
In questa pagina
Aggiornato il 3 novembre 2026, sulla base delle best practice e del riferimento API di xAI: temperatura limitata a 1 e consigliata a 0,7. Fonte: Best practices. L’esempio di chiamata segue il README dell’SDK (
chat.append(user(...)),chat.sample(),response.content) ed è stato eseguito per verificarne il funzionamento.
L’SDK Python ufficiale di xAI
L’SDK Python nativo di xAI è il modo più diretto per lavorare con l’API Grok. Espone le funzionalità specifiche della piattaforma e riceve gli aggiornamenti in anteprima quando vengono aggiunti nuovi modelli o endpoint.
Installazione
Installa l’SDK con pip nel tuo ambiente Python:
pip install xai-sdk
Ti consigliamo di utilizzare un ambiente virtuale per isolare le dipendenze di ogni progetto:
python -m venv venv
source venv/bin/activate # Linux/macOS
venv\Scripts\activate # Windows
pip install xai-sdk
Inizializzazione del client
La classe Client è il punto di ingresso dell’SDK. Gestisce l’autenticazione, le connessioni HTTP e la serializzazione delle richieste:
from xai_sdk import Client
import os
client = Client(api_key=os.getenv("XAI_API_KEY"))
Se la variabile d’ambiente XAI_API_KEY è impostata, puoi creare il client anche senza argomenti espliciti:
client = Client()
L’SDK rileva automaticamente la variabile e la utilizza per l’autenticazione.
Invio di una richiesta
Una volta inizializzato il client, l’SDK ragiona in termini di conversazioni: client.chat.create() crea la conversazione (senza inviare nulla), append aggiunge un messaggio costruito con user() o system(), e sample() chiede al modello di fornire la sua risposta:
import os
from xai_sdk import Client
from xai_sdk.chat import user
client = Client(api_key=os.getenv("XAI_API_KEY"))
chat = client.chat.create(model="grok-4.7")
chat.append(user("Spiega cos'è un'API REST in 3 frasi."))
response = chat.sample()
print(response.content)
Parametri comuni
model: l’ID del modello da utilizzare (obbligatorio); xAI consigliagrok-4.7messages: i messaggi iniziali della conversazione, costruiti consystem(),user()eassistant()daxai_sdk.chat(i dizionari semplici fanno fallire la chiamata)temperature: da 0 a 2, limitata a 1 oltre tale valore; xAI consiglia 0,7, contop_pa 0,95max_tokens: il numero massimo di token generatireasoning_effort: la profondità del ragionamento (none,low,medium,high), che xAI consiglia di impostare in ogni richiesta
Lo streaming non passa attraverso un parametro: for response, chunk in chat.stream(): restituisce i frammenti man mano che arrivano in chunk.content. La lezione 10 mostra lo streaming con l’API REST tramite SSE.
Vantaggi dell’SDK nativo
Rispetto all’SDK OpenAI puntato sull’API xAI (prossima lezione), l’SDK nativo offre accesso diretto alle funzionalità specifiche di xAI: ricerca su X e sul web, strumenti lato server, generazione video, collezioni di documenti. I suoi tipi Python completi potenziano l’autocompletamento del tuo editor e xAI lo mantiene al passo con l’API. Ha anche una sua struttura specifica, che devi accettare: funziona su gRPC, i suoi messaggi sono costruiti con user() e system(), e i suoi errori sono grpc.RpcError.
Quando scegliere questo SDK
La scelta deriva naturalmente dalla tua situazione. Per un nuovo progetto costruito specificamente sull’API Grok, l’SDK nativo è il punto di partenza ovvio: ottieni tutto quanto sopra senza vincoli di compatibilità da rispettare. Diventa essenziale non appena prevedi di utilizzare funzionalità specifiche di xAI come la ricerca su X o la ricerca web integrata, che funzionano pienamente solo in questo modo. Se, d’altra parte, disponi di codice esistente basato sull’SDK OpenAI, non riscrivere nulla per ora: la prossima lezione mostra come adattarlo modificando due righe.
Punti chiave
- Installa con
pip install xai-sdkin un ambiente virtuale - La classe
Clientè il punto di ingresso, con rilevamento automatico diXAI_API_KEY client.chat.create()crea una conversazione;chat.append(user(...))aggiunge un messaggio echat.sample()restituisce la risposta, letta daresponse.content- Preferisci questo SDK per nuovi progetti che prendono di mira esclusivamente l’API Grok