Pydantic ja tööriistade määratlemine xAI SDK-ga
Sellel lehel
Uuendatud 3. novembril 2026 põhinedes xAI Function calling dokumentatsioonil ja
xai-sdkversioonil 1.21.0: SDK ei paku ei@client.tool()dekoraatorit ega funktsioonide automaatset käivitamist; sa lood tööriistu funktsioonigatool()(kasutades näiteks Pydanticu skeemi) ja tagastad tulemusedtool_resultabil. Allikas: Function calling.
Lihtsusta tööriistade määratlemist
JSON-skeemide käsitsi kirjutamine on sõnaohke ja vigadele avatud. Kaks lähenemist võimaldavad sul genereerida tööriistade määratlusi otse oma Pythoni koodist: Pydanticu mudelid, mille xAI SDK teisendab oma tool() funktsiooniga tööriistadeks, ja lihtne kohandatud dekoraator, mis loeb sinu funktsioonide signatuure.
Pydanticu lähenemine
Pydantic on Pythoni teek, mis võimaldab defineerida andmemudeleid automaatse valideerimisega. Groki API saab neid mudeleid kasutada tööriistade JSON-skeemide genereerimiseks.
from pydantic import BaseModel, Field
from typing import Optional
class WeatherParams(BaseModel):
city: str = Field(description="Linna nimi")
unit: Optional[str] = Field(
default="celsius",
description="Temperatuuri ühik",
enum=["celsius", "fahrenheit"]
)
See Pydanticu mudel genereerib automaatselt JSON-skeemi, mis on samaväärne sellega, mida oleksid pidanud käsitsi kirjutama. Eelised hõlmavad:
- Tüübikontroll: Python kontrollib tüüpe käitusajal
- Valideerimine: Pydantic valideerib andmed automaatselt
- Dokumentatsioon: kirjed
Field(description=...)toimivad dokumentatsioonina - Taaskasutatavus: sama mudel töötab nii valideerimiseks kui ka API dokumentatsiooniks
Komplekssed mudelid
Pydantic haldab pesastatud struktuure, loendeid ja täiustatud tüüpe:
from typing import List, Optional
from pydantic import BaseModel, Field
class Address(BaseModel):
street: str = Field(description="Tänava number ja nimi")
city: str = Field(description="Linn")
zip_code: str = Field(description="Postiindeks")
country: str = Field(default="FR", description="ISO riigikood")
class CreateOrderParams(BaseModel):
product_id: str = Field(description="Toote identifikaator")
quantity: int = Field(description="Tellitud kogus", ge=1, le=100)
shipping_address: Address = Field(description="Tarneaadress")
notes: Optional[str] = Field(
default=None,
description="Erilised tarnejuhised"
)
tags: List[str] = Field(
default=[],
description="Sildid tellimuse jälgimiseks"
)
Piirangud ge (suurem või võrdne) ja le (väiksem või võrdne) teisendatakse JSON-skeemi piiranguteks, mida mudel jõustab.
xAI SDK funktsioon tool()
xAI SDK ei võta Pydanticu klassi sellisena vastu: see eeldab tööriista määratlust, mille selle funktsioon tool() ehitab nime, kirjelduse ja JSON-skeemi põhjal. Pydantic pakub täpselt seda skeemi meetodi model_json_schema() kaudu:
from xai_sdk.chat import tool
tools = [
tool(
name="get_weather",
description="Hangi praegune ilm linna kohta",
parameters=WeatherParams.model_json_schema(),
),
]
Kasutamine SDK-ga
Deklareerid tööriista vestluse loomisel. SDK ei käivita sinu funktsioone: kui Grok taotleb väljakutset, käivitab sinu kood selle, lisab tulemuse tool_result abil ja jätkab seejärel genereerimist.
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("Ilm Bordeaux's?"))
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} # sinu implementatsioon
chat.append(tool_result(json.dumps(result)))
response = chat.sample()
print(response.content)
model_validate_json kontrollib ka seda, kas mudeli loodud argumendid vastavad skeemile: puuduv argument või vale tüüp tõstab vea enne, kui sinu funktsioon käivitub.
Kohandatud dekoraator kiiruse huvides
SDK ei paku @tool dekoraatorit. miski ei takista sul kirjutamast paari reaga oma versiooni, mis loeb funktsiooni signatuuri ja dokstringi:
import inspect
from pydantic import create_model
from xai_sdk.chat import tool
def custom_tool(func):
"""Ehitab xAI tööriista määratluse funktsiooni signatuuri ja dokstringi põhjal."""
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:
"""Hangi praegune ilm linna kohta (nt Pariis, Lyon)."""
return {"temp": 22, "unit": unit, "city": city}
tools = [custom_tool(get_weather)]
Funktsiooni nimi muutub tööriista nimeks, dokstringi esimene lõik muutub kirjelduseks ja parameetrid ilma vaikeväärtusteta muutuvad kohustuslikeks. Parameetrite kirjeldusi aga ei ekstraheerita: mitmetimõistetavate parameetrite puhul pöördu tagasi Pydanticu mudeli juurde, kasutades Field(description=...).
Kolme lähenemise võrdlus
| Lähenemine | Eelised | Piirangud |
|---|---|---|
| Käsitsi JSON-skeem | Täielik kontroll, sõltuvusi pole | Sõnaohke, trükivead jäävad märkamata |
Pydanticu mudel + tool() | Argumentide valideerimine, väljapõhised kirjeldused | Üks klass ühe tööriista kohta |
| Kohandatud dekoraator | Kõige lühem | Puuduvad parameetripõhised kirjeldused, koodi hooldusvajadus |
Parimad tavad kirjelduste jaoks
Sõltumata lähenemisviisist on kirjeldus see, mida mudel loeb, otsustamaks, kas tööriista kutsuda. Täpsusta, millal seda kasutada, mida see tagastab ja milline on parameetrite formaat:
class SearchProductsParams(BaseModel):
query: str = Field(description="Otsinguterminid: toote nimi või märksõnad")
category: str = Field(default="all", description="Kategooria: elektroonika, rõivad, toit või kõik")
max_results: int = Field(default=10, ge=1, le=50, description="Tulemuste maksimaalne arv")
search = tool(
name="search_products",
description=(
"Otsi tooteid e-kaubanduse kataloogist. Kasuta siis, kui "
"kasutaja otsib tootet nime, kirjelduse või kategooria järgi. "
"Tagastab toodete loendi hinnaga, saadavuse ja lingiga."
),
parameters=SearchProductsParams.model_json_schema(),
)
Peamised punktid
- Pydantic genereerib JSON-skeeme Pythoni mudelitest koos argumentide valideerimisega
- xAI SDK ehitab tööriistu funktsiooniga
tool(name=..., description=..., parameters=...) - SDK ei käivita sinu funktsioone: sinu kood teeb seda ja tagastab tulemuse
tool_resultabil - SDK-l puudub
@tooldekoraator; kohandatud dekoraator on võimalik, kuid kaotad parameetripõhised kirjeldused - Viimistle oma kirjeldusi: mudel loeb neid tööriista valimiseks