Pydantic un rīku definēšana ar xAI SDK
Šajā lapā
Atjaunināts 2026. gada 3. novembrī, pamatojoties uz xAI Function calling dokumentāciju un
xai-sdk1.21.0: SDK nenodrošina ne@client.tool()dekoratoru, ne automātisku funkciju izpildi; tu veido rīkus artool()(izmantojot, piemēram, Pydantic shēmu) un atgriež rezultātus artool_result. Avots: Function calling.
Rīku definēšanas vienkāršošana
JSON shēmu rakstīšana ar roku ir apjomīga un kļūdu pilna. Divas pieejas ļauj ģenerēt rīku definīcijas tieši no tava Python koda: Pydantic modeļi, kurus xAI SDK pārveido par rīkiem, izmantojot savu tool() funkciju, un vienkāršs pielāgots dekorators, kas nolasa tavu funkciju parakstus.
Pydantic pieeja
Pydantic ir Python bibliotēka, kas ļauj definēt datu modeļus ar automātisku validāciju. Grok API var izmantot šos modeļus, lai ģenerētu JSON shēmas rīkiem.
from pydantic import BaseModel, Field
from typing import Optional
class WeatherParams(BaseModel):
city: str = Field(description="Pilsētas nosaukums")
unit: Optional[str] = Field(
default="celsius",
description="Temperatūras mērvienība",
enum=["celsius", "fahrenheit"]
)
Šis Pydantic modelis automātiski ģenerē JSON shēmu, kas ir ekvivalenta tai, ko būtu rakstījis manuāli. Priekšrocības ietver:
- Tipu pārbaude: Python pārbauda tipus izpildlaikā
- Validācija: Pydantic automātiski validē datus
- Dokumentācija:
Field(description=...)ieraksti kalpo kā dokumentācija - Atkārtota izmantojamība: viens un tas pats modelis darbojas gan validācijai, gan API dokumentācijai
Sarežģīti modeļi
Pydantic apstrādā ligzdotas struktūras, sarakstus un uzlabotus tipus:
from typing import List, Optional
from pydantic import BaseModel, Field
class Address(BaseModel):
street: str = Field(description="Ielas numurs un nosaukums")
city: str = Field(description="Pilsēta")
zip_code: str = Field(description="Pasta indekss")
country: str = Field(default="FR", description="ISO valsts kods")
class CreateOrderParams(BaseModel):
product_id: str = Field(description="Produkta identifikators")
quantity: int = Field(description="Pasūtītais daudzums", ge=1, le=100)
shipping_address: Address = Field(description="Piegādes adrese")
notes: Optional[str] = Field(
default=None,
description="Īpaši piegādes norādījumi"
)
tags: List[str] = Field(
default=[],
description="Birkas pasūtījuma izsekošanai"
)
Ierobežojumi ge (lielāks vai vienāds) un le (mazāks vai vienāds) tiek pārvērsti JSON shēmas ierobežojumos, ko modelis nodrošina.
xAI SDK funkcija tool()
xAI SDK nepieņem Pydantic klasi tieši tādu, kāda tā ir: tā sagaida rīka definīciju, ko tās tool() funkcija veido no nosaukuma, apraksta un JSON shēmas. Pydantic nodrošina tieši šo shēmu, izmantojot model_json_schema():
from xai_sdk.chat import tool
tools = [
tool(
name="get_weather",
description="Iegūst aktuālo laika prognozi pilsētai",
parameters=WeatherParams.model_json_schema(),
),
]
Izmantošana ar SDK
Tu deklarē rīku, veidojot sarunu. SDK neizpilda tavas funkcijas: kad Grok pieprasa izsaukumu, tavs kods to izpilda, pievieno rezultātu ar tool_result un pēc tam atsāk ģenerēšanu.
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("Laiks Bordo?"))
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} # tava implementācija
chat.append(tool_result(json.dumps(result)))
response = chat.sample()
print(response.content)
model_validate_json arī pārbauda, vai modeļa ģenerētie argumenti atbilst shēmai: trūkstošs arguments vai nepareizs tips izraisīs kļūdu pirms tavas funkcijas izpildes.
Pielāgots dekorators ātrumam
SDK nenodrošina @tool dekoratoru. Nekas neliedz tev uzrakstīt tādu dažās rindiņās, kas nolasa funkcijas parakstu un docstring:
import inspect
from pydantic import create_model
from xai_sdk.chat import tool
def custom_tool(func):
"""Veido xAI rīka definīciju no funkcijas paraksta un 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:
"""Iegūst aktuālo laika prognozi pilsētai (piem., Parīze, Liona)."""
return {"temp": 22, "unit": unit, "city": city}
tools = [custom_tool(get_weather)]
Funkcijas nosaukums kļūst par rīka nosaukumu, pirmais docstring teikums kļūst par aprakstu, un parametri bez noklusējuma vērtībām kļūst par obligātiem. Parametru apraksti gan netiek ekstrahēti: neskaidriem parametriem atgriezies pie Pydantic modeļa ar Field(description=...).
Trīs pieeju salīdzinājums
| Pieeja | Priekšrocības | Ierobežojumi |
|---|---|---|
| Manuāla JSON shēma | Pilnīga kontrole, nav atkarību | Apjomīga, kļūdas paliek nepamanītas |
Pydantic modelis + tool() | Argumentu validācija, apraksti katram laukam | Viena klase katram rīkam |
| Pielāgots dekorators | Viskoncizākais | Nav aprakstu katram parametram, uzturams kods |
Labākā prakse aprakstiem
Neatkarīgi no pieejas, apraksts ir tas, ko modelis lasa, lai izlemtu, vai izsaukt rīku. Norādi, kad to lietot, ko tas atgriež un kāds ir parametru formāts:
class SearchProductsParams(BaseModel):
query: str = Field(description="Meklēšanas termini: produkta nosaukums vai atslēgvārdi")
category: str = Field(default="all", description="Kategorija: elektronika, apģērbs, pārtika vai viss")
max_results: int = Field(default=10, ge=1, le=50, description="Maksimālais rezultātu skaits")
search = tool(
name="search_products",
description=(
"Meklē produktus e-komercijas katalogā. Izmanto, kad "
"lietotājs meklē produktu pēc nosaukuma, apraksta vai kategorijas. "
"Atgriež produktu sarakstu ar cenu, pieejamību un saiti."
),
parameters=SearchProductsParams.model_json_schema(),
)
Galvenās atziņas
- Pydantic ģenerē JSON shēmas no Python modeļiem ar argumentu validāciju
- xAI SDK veido rīkus ar
tool(name=..., description=..., parameters=...) - SDK neizpilda tavas funkcijas: to dara tavs kods, pēc tam atgriežot rezultātu ar
tool_result - SDK nav
@tooldekoratora; pielāgots dekorators ir iespējams, taču par cenu aprakstu trūkuma katram parametram - Pilnveido savus aprakstus: modelis tos lasa, lai izvēlētos rīku