Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

Pydantic a definícia nástrojov pomocou xAI SDK

Lekcia 7 z 14 Aktualizované 3. novembra 2026 Vývojár
Na tejto strane
  1. Zjednodušenie definície nástrojov
  2. Prístup s Pydantic
  3. Funkcia tool() v xAI SDK
  4. Vlastný dekorátor pre rýchlosť
  5. Porovnanie troch prístupov
  6. Osvedčené postupy pre popisy
  7. Kľúčové poznatky

Aktualizované 3. novembra 2026 na základe dokumentácie xAI Function calling a verzie xai-sdk 1.21.0: SDK neponúka ani dekorátor @client.tool(), ani automatické spúšťanie funkcií; nástroje buduješ pomocou tool() (napríklad s schémou Pydantic) a výsledky vraciaš cez tool_result. Zdroj: Function calling.

Zjednodušenie definície nástrojov

Ručné písanie schém JSON je zdĺhavé a náchylné na chyby. Existujú dva prístupy, ktoré ti umožnia generovať definície nástrojov priamo z kódu Python: modely Pydantic, ktoré xAI SDK transformuje na nástroje pomocou funkcie tool(), a jednoduchý vlastný dekorátor, ktorý číta signatúry tvojich funkcií.

Prístup s Pydantic

Pydantic je knižnica pre Python, ktorá ti umožňuje definovať dátové modely s automatickou validáciou. API Grok dokáže tieto modely využiť na generovanie schém JSON pre nástroje.

from pydantic import BaseModel, Field
from typing import Optional

class WeatherParams(BaseModel):
    city: str = Field(description="Názov mesta")
    unit: Optional[str] = Field(
        default="celsius",
        description="Jednotka teploty",
        enum=["celsius", "fahrenheit"]
    )

Tento model Pydantic automaticky vygeneruje ekvivalent schémy JSON, ktorú by si inak napísal ručne. Medzi výhody patrí:

  • Kontrola typov: Python kontroluje typy počas behu
  • Validácia: Pydantic automaticky overuje údaje
  • Dokumentácia: Položky Field(description=...) slúžia ako dokumentácia
  • Opätovné použitie: Ten istý model funguje pre validáciu aj dokumentáciu API

Zložité modely

Pydantic zvláda vnorené štruktúry, zoznamy a pokročilé typy:

from typing import List, Optional
from pydantic import BaseModel, Field

class Address(BaseModel):
    street: str = Field(description="Číslo a názov ulice")
    city: str = Field(description="Mesto")
    zip_code: str = Field(description="PSČ")
    country: str = Field(default="FR", description="Kód krajiny ISO")

class CreateOrderParams(BaseModel):
    product_id: str = Field(description="Identifikátor produktu")
    quantity: int = Field(description="Objednané množstvo", ge=1, le=100)
    shipping_address: Address = Field(description="Adresa doručenia")
    notes: Optional[str] = Field(
        default=None,
        description="Špeciálne pokyny pre doručenie"
    )
    tags: List[str] = Field(
        default=[],
        description="Tagy na sledovanie objednávky"
    )

Obmedzenia ge (väčšie alebo rovné) a le (menšie alebo rovné) sa prekladajú do obmedzení schémy JSON, ktoré model presadzuje.

Funkcia tool() v xAI SDK

xAI SDK neprijíma triedu Pydantic tak, ako je: očakáva definíciu nástroja, ktorú jeho funkcia tool() zostaví z názvu, popisu a schémy JSON. Pydantic poskytuje presne túto schému prostredníctvom model_json_schema():

from xai_sdk.chat import tool

tools = [
    tool(
        name="get_weather",
        description="Získať aktuálne počasie pre mesto",
        parameters=WeatherParams.model_json_schema(),
    ),
]

Použitie so SDK

Nástroj deklaruješ pri vytváraní konverzácie. SDK nespúšťa tvoje funkcie: keď Grok požiada o volanie, tvoj kód ho vykoná, pridá výsledok pomocou tool_result a potom obnoví generovanie.

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("Počasie v 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}  # tvoja implementácia
        chat.append(tool_result(json.dumps(result)))
    response = chat.sample()

print(response.content)

model_validate_json tiež kontroluje, či argumenty vygenerované modelom zodpovedajú schéme: chýbajúci argument alebo nesprávny typ vyvolá chybu ešte pred spustením tvojej funkcie.

Vlastný dekorátor pre rýchlosť

SDK neposkytuje dekorátor @tool. Nič ti však nebráni napísať si ho v niekoľkých riadkoch tak, aby čítal signatúru funkcie a jej docstring:

import inspect

from pydantic import create_model
from xai_sdk.chat import tool


def custom_tool(func):
    """Vytvorí definíciu nástroja xAI zo signatúry funkcie a docstringu."""
    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:
    """Získať aktuálne počasie pre mesto (napr. Paríž, Lyon)."""
    return {"temp": 22, "unit": unit, "city": city}


tools = [custom_tool(get_weather)]

Názov funkcie sa stane názvom nástroja, prvý odsek docstringu sa stane popisom a parametre bez predvolených hodnôt sa stanú povinnými. Popisy parametrov sa však neextrahujú: pri nejednoznačných parametroch sa vráť k modelu Pydantic s Field(description=...).

Porovnanie troch prístupov

PrístupVýhodyObmedzenia
Ručná schéma JSONÚplná kontrola, žiadne závislostiZdĺhavé, preklepy zostanú neodhalené
Model Pydantic + tool()Validácia argumentov, popisy pre jednotlivé poliaJedna trieda na nástroj
Vlastný dekorátorNajstručnejšíŽiadne popisy parametrov, kód na údržbu

Osvedčené postupy pre popisy

Bez ohľadu na zvolený prístup je popis tým, čo model číta, aby sa rozhodol, či nástroj zavolať. Uveď, kedy ho použiť, čo vracia a aký je formát parametrov:

class SearchProductsParams(BaseModel):
    query: str = Field(description="Vyhľadávacie výrazy: názov produktu alebo kľúčové slová")
    category: str = Field(default="all", description="Kategória: elektronika, oblečenie, potraviny alebo all")
    max_results: int = Field(default=10, ge=1, le=50, description="Maximálny počet výsledkov")


search = tool(
    name="search_products",
    description=(
        "Vyhľadať produkty v e-commerce katalógu. Použi, keď "
        "používateľ hľadá produkt podľa názvu, popisu alebo kategórie. "
        "Vráti zoznam produktov s cenou, dostupnosťou a odkazom."
    ),
    parameters=SearchProductsParams.model_json_schema(),
)

Kľúčové poznatky

  • Pydantic generuje schémy JSON z modelov Python s validáciou argumentov
  • xAI SDK buduje nástroje pomocou tool(name=..., description=..., parameters=...)
  • SDK nespúšťa tvoje funkcie: robí to tvoj kód a následne vráti výsledok cez tool_result
  • SDK nemá dekorátor @tool; vlastný dekorátor je možný, ale za cenu absencie popisov jednotlivých parametrov
  • Vylepši svoje popisy: model ich číta, aby si vybral nástroj