xAI SDK: client.chat.create
Σε αυτήν τη σελίδα
Ενημερώθηκε στις 3 Νοεμβρίου 2026. Η προηγούμενη έκδοση υπέθετε λανθασμένα ότι το
xai-sdkχρησιμοποιούσε τη διεπαφή του OpenAI SDK: μηνύματα ως λεξικά,response.choices[0].message.content, την παράμετροstream=Trueκαι ένα ανύπαρκτο modulexai_sdk.errors. Με το πραγματικό SDK (έκδοση 1.21.0), εκείνος ο κώδικας αποτυγχάνει στην πρώτη κλήση:ValueError: unknown enum label "user". Αυτό το μάθημα ακολουθεί πλέον το επίσημο README του SDK και κάθε παράδειγμα έχει εκτελεστεί έναντι του xAI API (με ψευδο-κλειδί, για την επαλήθευση της διαδρομής κλήσης και των σφαλμάτων). Πηγές: xAI Python SDK · Best practices (xAI) · Debugging Errors (xAI).
Το εγγενές xAI SDK
Το επίσημο xAI SDK για Python, το xai-sdk, δεν χρησιμοποιεί το endpoint 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 από το module 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 (tokens που καταναλώθηκαν), reasoning_content για τα μοντέλα που το εκθέτουν, και citations όταν έχει πραγματοποιηθεί αναζήτηση.
Το API παραμένει χωρίς κατάσταση (stateless): το αντικείμενο 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: ο μέγιστος αριθμός παραγόμενων tokens. Οι βέλτιστες πρακτικές του xAI προτείνουν να ορίζεται υψηλότερα από την αναμενόμενη μεγαλύτερη απάντηση ή να αφήνεται η προεπιλεγμένη τιμή.reasoning_effort: το βάθος συλλογισμού, απόnoneέωςhigh(καιxhighσε ορισμένα μοντέλα). Η προεπιλογή εξαρτάται από το μοντέλο: το xAI προτείνει να το ορίζετε ρητά σε κάθε αίτημα και να το καταγράφετε με κάθε αποτέλεσμα.response_format,tools,tool_choice: δομημένες έξοδοι και κλήση εργαλείων, που καλύπτονται αργότερα στο μάθημα.
Υπάρχει επίσης το stop (έως τέσσερις ακολουθίες), αλλά οι βέλτιστες πρακτικές του xAI ορίζουν ότι τα μοντέλα συλλογισμού δεν το δέχονται, ούτε τα presence_penalty και frequency_penalty.
Ροή απαντήσεων (Streaming)
Το xAI προτείνει τη ροή (streaming), ειδικά με τα μοντέλα συλλογισμού, των οποίων οι απαντήσεις μπορεί να καθυστερήσουν σημαντικά. Δεν χρησιμοποιείται παράμετρος: η συνομιλία προσφέρει μια δεύτερη μέθοδο, την 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 για εξαντλημένα όρια χρήσης. Το χρονικό όριο αναμονής (wait timeout) είναι προεπιλεγμένα 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είναι ένα SDK gRPC, με δική του διεπαφή: δεν επαναχρησιμοποιεί τη μορφή ή τα αντικείμενα του OpenAI SDK - Το
client.chat.create()δημιουργεί μια συνομιλία· τοchat.append(user(...))προσθέτει ένα μήνυμα, τοchat.sample()επιστρέφει την απάντηση, την οποία διαβάζετε στοresponse.content - Τα μηνύματα κατασκευάζονται με τα
system,userκαιassistantαπό τοxai_sdk.chat· τα λεξικά προκαλούν αποτυχία της κλήσης - Η ροή (streaming) χρησιμοποιεί το
chat.stream(), το οποίο επιστρέφει ζεύγη(response, chunk) - Τα σφάλματα είναι
grpc.RpcError· τοUNAVAILABLEεπαναλαμβάνεται αυτόματα, η προεπιλεγμένη λήξη χρόνου είναι 27 λεπτά