Μετάβαση στο κύριο περιεχόμενο
Ελληνικά— Επιλέξτε γλώσσα
Μενού

Ορισμός Εργαλείων με Pydantic και το xAI SDK

Μάθημα 7 / 14 Ενημερώθηκε 3 Νοεμβρίου 2026 Για developers
Σε αυτήν τη σελίδα
  1. Απλοποίηση του Ορισμού Εργαλείων
  2. Προσέγγιση με Pydantic
  3. Η Συνάρτηση tool() του xAI SDK
  4. Ένας Προσαρμοσμένος Διακοσμητής για Ταχύτητα
  5. Σύγκριση των Τριών Προσεγγίσεων
  6. Βέλτιστες Πρακτικές για τις Περιγραφές
  7. Βασικά σημεία

Ενημερώθηκε στις 3 Νοεμβρίου 2026 με βάση την τεκμηρίωση Function calling της xAI και την έκδοση xai-sdk 1.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· ένας προσαρμοσμένος διακοσμητής είναι εφικτός, με κόστος την απώλεια των περιγραφών ανά παράμετρο
  • Βελτιώστε τις περιγραφές σας: το μοντέλο τις διαβάζει για να επιλέξει ένα εργαλείο