Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Pydantic in definicija orodij z xAI SDK

Lekcija 7 od 14 Posodobljeno 3. november 2026 Razvijalec
Na tej strani
  1. Poenostavitev definicije orodij
  2. Pristop s Pydantic
  3. Funkcija tool() v xAI SDK
  4. Okrasek po meri za hitrost
  5. Primerjava treh pristopov
  6. Najboljše prakse za opise
  7. Ključne ugotovitve

Posodobljeno 3. novembra 2026 na podlagi dokumentacije xAI Function calling in različice xai-sdk 1.21.0: SDK ne ponuja niti okraska @client.tool() niti samodejnega izvajanja funkcij; orodja gradiš s funkcijo tool() (na primer z uporabo sheme Pydantic) in rezultate vračaš z tool_result. Vir: Function calling.

Poenostavitev definicije orodij

Ročno pisanje shem JSON je obsežno in dovzetno za napake. Dva pristopa ti omogočata generiranje definicij orodij neposredno iz kode Python: modeli Pydantic, ki jih xAI SDK pretvori v orodja s funkcijo tool(), in preprost okrasek po meri, ki prebere podpise tvojih funkcij.

Pristop s Pydantic

Pydantic je knjižnica za Python, ki ti omogoča definiranje podatkovnih modelov s samodejnim preverjanjem veljavnosti. API Grok lahko te modele uporabi za generiranje shem JSON za orodja.

from pydantic import BaseModel, Field
from typing import Optional

class WeatherParams(BaseModel):
    city: str = Field(description="Ime mesta")
    unit: Optional[str] = Field(
        default="celsius",
        description="Enota za temperaturo",
        enum=["celsius", "fahrenheit"]
    )

Ta model Pydantic samodejno generira ekvivalentno shemo JSON, ki bi jo sicer napisal ročno. Prednosti vključujejo:

  • Preverjanje tipov: Python preveri tipe med izvajanjem
  • Validacija: Pydantic samodejno preveri veljavnost podatkov
  • Dokumentacija: vnosi Field(description=...) služijo kot dokumentacija
  • Ponovna uporaba: isti model deluje tako za validacijo kot za dokumentacijo API-ja

Kompleksni modeli

Pydantic obvlada gnezdenje struktur, sezname in napredne tipe:

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

class Address(BaseModel):
    street: str = Field(description="Številka in ime ulice")
    city: str = Field(description="Mesto")
    zip_code: str = Field(description="Poštna številka")
    country: str = Field(default="FR", description="Koda države ISO")

class CreateOrderParams(BaseModel):
    product_id: str = Field(description="Identifikator izdelka")
    quantity: int = Field(description="Naročena količina", ge=1, le=100)
    shipping_address: Address = Field(description="Naslov za dostavo")
    notes: Optional[str] = Field(
        default=None,
        description="Posebna navodila za dostavo"
    )
    tags: List[str] = Field(
        default=[],
        description="Oznake za sledenje naročila"
    )

Omejitvi ge (večje ali enako) in le (manjše ali enako) se prevedeta v omejitve sheme JSON, ki jih model uveljavlja.

Funkcija tool() v xAI SDK

xAI SDK ne sprejme razreda Pydantic takšnega, kot je: pričakuje definicijo orodja, ki jo njegova funkcija tool() zgradi iz imena, opisa in sheme JSON. Pydantic zagotavlja prav to shemo prek model_json_schema():

from xai_sdk.chat import tool

tools = [
    tool(
        name="get_weather",
        description="Pridobi trenutno vreme za določeno mesto",
        parameters=WeatherParams.model_json_schema(),
    ),
]

Uporaba s SDK-jem

Orodje deklariraš ob ustvarjanju pogovora. SDK ne izvaja tvojih funkcij: ko Grok zahteva klic, tvoja koda funkcijo izvede, doda rezultat s tool_result in nato nadaljuje generiranje.

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("Vreme v Bordeauxu?"))
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 implementacija
        chat.append(tool_result(json.dumps(result)))
    response = chat.sample()

print(response.content)

model_validate_json prav tako preveri, ali se argumenti, ki jih proizvede model, ujemajo s shemo: manjkajoč argument ali napačen tip sproži napako, preden se tvoja funkcija zažene.

Okrasek po meri za hitrost

SDK ne ponuja okrasa @tool. Nič ti ne preprečuje, da v nekaj vrsticah napišeš svojega, ki prebere podpis funkcije in docstring:

import inspect

from pydantic import create_model
from xai_sdk.chat import tool


def custom_tool(func):
    """Zgradi definicijo orodja xAI iz podpisa funkcije in docstringa."""
    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:
    """Pridobi trenutno vreme za mesto (npr. Pariz, Lyon)."""
    return {"temp": 22, "unit": unit, "city": city}


tools = [custom_tool(get_weather)]

Ime funkcije postane ime orodja, prvi odstavek docstringa postane opis, parametri brez privzetih vrednosti pa postanejo obvezni. Opisi parametrov se žal ne izvlečejo: za dvoumne parametre se vrni k modelu Pydantic z Field(description=...).

Primerjava treh pristopov

PristopPrednostiOmejitve
Ročna shema JSONPopoln nadzor, brez odvisnostiObsežno, tipkarske napake ostanejo neodkrite
Model Pydantic + tool()Validacija argumentov, opisi po poljihEn razred na orodje
Okrasek po meriNajbolj jedrnatoNi opisov po parametrih, koda za vzdrževanje

Najboljše prakse za opise

Ne glede na pristop je opis tisto, kar model prebere, da se odloči, ali bo poklical orodje. Navedi, kdaj ga uporabiti, kaj vrača in kakšna je oblika parametrov:

class SearchProductsParams(BaseModel):
    query: str = Field(description="Iskalni niz: ime izdelka ali ključne besede")
    category: str = Field(default="all", description="Kategorija: elektronika, oblačila, hrana ali vse")
    max_results: int = Field(default=10, ge=1, le=50, description="Največje število rezultatov")


search = tool(
    name="search_products",
    description=(
        "Išči izdelke v e-trgovinskem katalogu. Uporabi, ko "
        "uporabnik išče izdelek po imenu, opisu ali kategoriji. "
        "Vrne seznam izdelkov s ceno, razpoložljivostjo in povezavo."
    ),
    parameters=SearchProductsParams.model_json_schema(),
)

Ključne ugotovitve

  • Pydantic generira sheme JSON iz modelov Python z validacijo argumentov
  • xAI SDK gradi orodja s tool(name=..., description=..., parameters=...)
  • SDK ne izvaja tvojih funkcij: to stori tvoja koda, rezultat pa vrne s tool_result
  • SDK nima okrasa @tool; okrasek po meri je mogoč, a na račun opisov po parametrih
  • Izpopolni svoje opise: model jih prebere, da izbere orodje