Pydantic in definicija orodij z xAI SDK
Na tej strani
Posodobljeno 3. novembra 2026 na podlagi dokumentacije xAI Function calling in različice
xai-sdk1.21.0: SDK ne ponuja niti okraska@client.tool()niti samodejnega izvajanja funkcij; orodja gradiš s funkcijotool()(na primer z uporabo sheme Pydantic) in rezultate vračaš ztool_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
| Pristop | Prednosti | Omejitve |
|---|---|---|
| Ročna shema JSON | Popoln nadzor, brez odvisnosti | Obsežno, tipkarske napake ostanejo neodkrite |
Model Pydantic + tool() | Validacija argumentov, opisi po poljih | En razred na orodje |
| Okrasek po meri | Najbolj jedrnato | Ni 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