Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

Pydantic és eszközdefiníció az xAI SDK-val

7. lecke 14 közül Frissítve 2026. november 3. Fejlesztő
Ezen az oldalon
  1. Az eszközdefiníció egyszerűsítése
  2. Pydantic megközelítés
  3. Az xAI SDK tool() függvénye
  4. Egyedi dekorátor a gyorsaság érdekében
  5. A három megközelítés összehasonlítása
  6. Bevált gyakorlatok a leírásokhoz
  7. Főbb megállapítások

Frissítve: 2026. november 3. az xAI Function calling dokumentációja és az xai-sdk 1.21.0 verziója alapján: az SDK nem kínál @client.tool() dekorátort, sem automatikus függvényvégrehajtást; az eszközöket a tool() függvénnyel építed fel (például Pydantic sémával), és az eredményeket a tool_result segítségével adod vissza. Forrás: Function calling.

Az eszközdefiníció egyszerűsítése

A JSON sémák kézi írása szószátyár és hibaérzékeny. Két megközelítés lehetővé teszi, hogy Python kódodból generáld az eszközdefiníciókat: a Pydantic modelleket, amelyeket az xAI SDK a tool() függvényével alakít át eszközzé, valamint egy egyszerű egyedi dekorátort, amely kiolvassa a függvényeid aláírását.

Pydantic megközelítés

A Pydantic egy Python könyvtár, amely lehetővé teszi adatmodellek definiálását automatikus validálással. A Grok API ezeket a modelleket használja fel az eszközök JSON sémáinak generálására.

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"]
    )

Ez a Pydantic modell automatikusan generálja azt a JSON sémát, amelyet egyébként kézzel írtál volna meg. Az előnyök közé tartozik:

  • Típusellenőrzés: a Python futásidőben ellenőrzi a típusokat
  • Validálás: a Pydantic automatikusan validálja az adatokat
  • Dokumentáció: a Field(description=...) bejegyzések dokumentációként szolgálnak
  • Újrafelhasználhatóság: ugyanaz a modell működik validálásra és API-dokumentációra is

Komplex modellek

A Pydantic kezeli a beágyazott struktúrákat, listákat és speciális típusokat:

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

A ge (nagyobb vagy egyenlő) és le (kisebb vagy egyenlő) megszorítások JSON Schema megszorításokká alakulnak, amelyeket a modell érvényesít.

Az xAI SDK tool() függvénye

Az xAI SDK nem fogad el közvetlenül egy Pydantic osztályt: egy eszközdefiníciót vár, amelyet a tool() függvénye épít fel egy név, egy leírás és egy JSON séma alapján. A Pydantic pontosan ezt a sémát biztosítja a model_json_schema() metóduson keresztül:

from xai_sdk.chat import tool

tools = [
    tool(
        name="get_weather",
        description="Get the current weather for a city",
        parameters=WeatherParams.model_json_schema(),
    ),
]

Használat az SDK-val

Az eszközt a beszélgetés létrehozásakor deklarálod. Az SDK nem hajtja végre a függvényeidet: amikor a Grok hívást kér, a kódod végrehajtja azt, hozzáadja az eredményt a tool_result segítségével, majd folytatja a generálást.

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)

A model_validate_json azt is ellenőrzi, hogy a modell által előállított argumentumok megfelelnek-e a sémának: egy hiányzó argumentum vagy helytelen típus hibát dob, mielőtt a függvényed lefutna.

Egyedi dekorátor a gyorsaság érdekében

Az SDK nem biztosít @tool dekorátort. Semmi sem akadályoz meg abban, hogy írj egyet néhány sorban, amely kiolvassa egy függvény aláírását és docstringjét:

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

A függvény neve lesz az eszköz neve, a docstring első bekezdése a leírás, az alapértelmezett érték nélküli paraméterek pedig kötelezővé válnak. A paraméterleírásokat azonban nem vonja ki: ha a paraméterek nem egyértelműek, térj vissza egy Pydantic modellhez a Field(description=...) használatával.

A három megközelítés összehasonlítása

MegközelítésElőnyökKorlátok
Kézi JSON sémaTeljes kontroll, nincs függőségSzószátyár, a elírások észrevétlenek maradnak
Pydantic modell + tool()Argumentum-validálás, mezőnkénti leírásokEszközönként egy osztály szükséges
Egyedi dekorátorLegtömörebbNincsenek paraméterenkénti leírások, karbantartandó kód

Bevált gyakorlatok a leírásokhoz

Függetlenül a választott megközelítéstől, a leírás az, amit a modell olvas, hogy eldöntse, hívja-e az eszközt. Fogalmazd meg, mikor kell használni, mit ad vissza, és milyen formátumúak a paraméterek:

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

Főbb megállapítások

  • A Pydantic JSON sémákat generál Python modellekből, argumentum-validálással
  • Az xAI SDK a tool(name=..., description=..., parameters=...) függvénnyel építi fel az eszközöket
  • Az SDK nem hajtja végre a függvényeidet: a kódod teszi ezt, majd a tool_result segítségével adja vissza az eredményt
  • Az SDK-ban nincs @tool dekorátor; egy egyedi dekorátor lehetséges, de ez a paraméterenkénti leírások hiányával jár
  • Csiszold meg a leírásokat: a modell ezeket olvassa az eszköz kiválasztásához