Ορισμός Εργαλείων με Pydantic και το xAI SDK
Σε αυτήν τη σελίδα
Ενημερώθηκε στις 3 Νοεμβρίου 2026 με βάση την τεκμηρίωση Function calling της xAI και την έκδοση
xai-sdk1.21.0: το SDK δεν προσφέρει ούτε διακοσμητή@client.tool()ούτε αυτόματη εκτέλεση συναρτήσεων. Δημιουργείτε εργαλεία με τη συνάρτησηtool()(χρησιμοποιώντας για παράδειγμα ένα σχήμα Pydantic) και επιστρέφετε τα αποτελέσματα με τοtool_result. Πηγή: Function calling.
Απλοποίηση του Ορισμού Εργαλείων
Η χειροκίνητη σύνταξη σχημάτων JSON είναι φλύαρη και επιρρεπής σε σφάλματα. Δύο προσεγγίσεις σάς επιτρέπουν να παράγετε ορισμούς εργαλείων απευθείας από τον κώδικα Python σας: τα μοντέλα Pydantic, τα οποία το xAI SDK μετατρέπει σε εργαλεία μέσω της συνάρτησης tool(), και ένας απλός προσαρμοσμένος διακοσμητής που διαβάζει τις υπογραφές των συναρτήσεών σας.
Προσέγγιση με Pydantic
Το Pydantic είναι μια βιβλιοθήκη Python που σάς επιτρέπει να ορίζετε μοντέλα δεδομένων με αυτόματη επικύρωση. Το API του Grok μπορεί να χρησιμοποιήσει αυτά τα μοντέλα για να παράγει σχήματα JSON για εργαλεία.
from pydantic import BaseModel, Field
from typing import Optional
class WeatherParams(BaseModel):
city: str = Field(description="City name")
unit: Optional[str] = Field(
default="celsius",
description="Temperature unit",
enum=["celsius", "fahrenheit"]
)
Αυτό το μοντέλο Pydantic παράγει αυτόματα το ισοδύναμο σχήμα JSON που θα γράφατε χειροκίνητα. Τα οφέλη περιλαμβάνουν:
- Έλεγχος τύπων: Η Python ελέγχει τους τύπους κατά την εκτέλεση
- Επικύρωση: Το Pydantic επικυρώνει αυτόματα τα δεδομένα
- Τεκμηρίωση: Οι καταχωρίσεις
Field(description=...)λειτουργούν ως τεκμηρίωση - Επαναχρησιμοποίηση: Το ίδιο μοντέλο λειτουργεί τόσο για επικύρωση όσο και για τεκμηρίωση API
Σύνθετα Μοντέλα
Το Pydantic διαχειρίζεται εμφωλευμένες δομές, λίστες και προηγμένους τύπους:
from typing import List, Optional
from pydantic import BaseModel, Field
class Address(BaseModel):
street: str = Field(description="Street number and name")
city: str = Field(description="City")
zip_code: str = Field(description="ZIP code")
country: str = Field(default="FR", description="ISO country code")
class CreateOrderParams(BaseModel):
product_id: str = Field(description="Product identifier")
quantity: int = Field(description="Ordered quantity", ge=1, le=100)
shipping_address: Address = Field(description="Shipping address")
notes: Optional[str] = Field(
default=None,
description="Special delivery instructions"
)
tags: List[str] = Field(
default=[],
description="Tags for order tracking"
)
Οι περιορισμοί ge (μεγαλύτερο ή ίσο) και le (μικρότερο ή ίσο) μεταφράζονται σε περιορισμούς JSON Schema που επιβάλλει το μοντέλο.
Η Συνάρτηση tool() του xAI SDK
Το xAI SDK δεν δέχεται μια κλάση Pydantic ως έχει: αναμένει έναν ορισμό εργαλείου, τον οποίο η συνάρτηση tool() κατασκευάζει από ένα όνομα, μια περιγραφή και ένα σχήμα JSON. Το Pydantic παρέχει ακριβώς αυτό το σχήμα μέσω της model_json_schema():
from xai_sdk.chat import tool
tools = [
tool(
name="get_weather",
description="Get the current weather for a city",
parameters=WeatherParams.model_json_schema(),
),
]
Χρήση με το SDK
Δηλώνετε το εργαλείο κατά τη δημιουργία της συνομιλίας. Το SDK δεν εκτελεί τις συναρτήσεις σας: όταν το Grok ζητήσει μια κλήση, ο κώδικάς σας την εκτελεί, προσθέτει το αποτέλεσμα με το tool_result και στη συνέχεια επαναλαμβάνει τη δημιουργία κειμένου.
import json
from xai_sdk import Client
from xai_sdk.chat import tool_result, user
client = Client(api_key="your-api-key")
chat = client.chat.create(model="grok-4.5", tools=tools)
chat.append(user("Weather in Bordeaux?"))
response = chat.sample()
if response.tool_calls:
chat.append(response)
for call in response.tool_calls:
args = WeatherParams.model_validate_json(call.function.arguments)
result = {"temp": 22, "unit": args.unit, "city": args.city} # your implementation
chat.append(tool_result(json.dumps(result)))
response = chat.sample()
print(response.content)
Η model_validate_json ελέγχει επίσης ότι τα ορίσματα που παρήγαγε το μοντέλο ταιριάζουν με το σχήμα: ένα missing όρισμα ή λανθασμένος τύπος θα προκαλέσει σφάλμα πριν εκτελεστεί η συνάρτησή σας.
Ένας Προσαρμοσμένος Διακοσμητής για Ταχύτητα
Το SDK δεν παρέχει έναν διακοσμητή @tool. Τίποτα όμως δεν σας εμποδίζει να γράψετε έναν σε λίγες γραμμές, ο οποίος διαβάζει την υπογραφή μιας συνάρτησης και το docstring της:
import inspect
from pydantic import create_model
from xai_sdk.chat import tool
def custom_tool(func):
"""Builds the xAI tool definition from a function's signature and docstring."""
fields = {
name: (p.annotation, ... if p.default is inspect.Parameter.empty else p.default)
for name, p in inspect.signature(func).parameters.items()
}
schema = create_model(func.__name__, **fields).model_json_schema()
description = (inspect.getdoc(func) or func.__name__).split("\n\n")[0]
return tool(name=func.__name__, description=description, parameters=schema)
def get_weather(city: str, unit: str = "celsius") -> dict:
"""Get the current weather for a city (e.g., Paris, Lyon)."""
return {"temp": 22, "unit": unit, "city": city}
tools = [custom_tool(get_weather)]
Το όνομα της συνάρτησης γίνεται το όνομα του εργαλείου, η πρώτη παράγραφος του docstring γίνεται η περιγραφή και οι παράμετροι χωρίς προεπιλεγμένες τιμές γίνονται υποχρεωτικές. Ωστόσο, οι περιγραφές των παραμέτρων δεν εξάγονται: για ασαφείς παραμέτρους, επιστρέψτε σε ένα μοντέλο Pydantic με Field(description=...).
Σύγκριση των Τριών Προσεγγίσεων
| Προσέγγιση | Οφέλη | Περιορισμοί |
|---|---|---|
| Χειροκίνητο σχήμα JSON | Πλήρης έλεγχος, χωρίς εξαρτήσεις | Φλύαρο, τα τυπογραφικά λάθη δεν εντοπίζονται |
Μοντέλο Pydantic + tool() | Επικύρωση ορισμάτων, περιγραφές ανά πεδίο | Μία κλάση ανά εργαλείο |
| Προσαρμοσμένος διακοσμητής | Πιο συνοπτικό | Χωρίς περιγραφές ανά παράμετρο, κώδικας προς συντήρηση |
Βέλτιστες Πρακτικές για τις Περιγραφές
Ανεξάρτητα από την προσέγγιση, η περιγραφή είναι αυτό που διαβάζει το μοντέλο για να αποφασίσει αν θα καλέσει το εργαλείο. Αναφέρετε πότε πρέπει να χρησιμοποιείται, τι επιστρέφει και τη μορφή των παραμέτρων:
class SearchProductsParams(BaseModel):
query: str = Field(description="Search terms: product name or keywords")
category: str = Field(default="all", description="Category: electronics, clothing, food, or all")
max_results: int = Field(default=10, ge=1, le=50, description="Maximum number of results")
search = tool(
name="search_products",
description=(
"Search for products in the e-commerce catalog. Use when "
"the user looks for a product by name, description, or category. "
"Returns a list of products with price, availability, and link."
),
parameters=SearchProductsParams.model_json_schema(),
)
Βασικά σημεία
- Το Pydantic παράγει σχήματα JSON από μοντέλα Python, με επικύρωση ορισμάτων
- Το xAI SDK κατασκευάζει εργαλεία με
tool(name=..., description=..., parameters=...) - Το SDK δεν εκτελεί τις συναρτήσεις σας: ο κώδικάς σας το κάνει και επιστρέφει το αποτέλεσμα με το
tool_result - Το SDK δεν διαθέτει διακοσμητή
@tool· ένας προσαρμοσμένος διακοσμητής είναι εφικτός, με κόστος την απώλεια των περιγραφών ανά παράμετρο - Βελτιώστε τις περιγραφές σας: το μοντέλο τις διαβάζει για να επιλέξει ένα εργαλείο