Pydantic u d-Definizzjoni tal-Għodod bis-SDK ta' xAI
F'din il-paġna
Aġġornat fit-3 ta’ Novembru 2026 abbażi tad-dokumentazzjoni Function calling ta’ xAI u
xai-sdk1.21.0: l-SDK ma joffrix dekoratur@client.tool()u lanqas eżekuzzjoni awtomatika tal-funzjonijiet; tibni l-għodod b’tool()(bl-użu ta’ skema Pydantic, pereżempju) u tirritorna r-riżultati b’tool_result. Sors: Function calling.
Issimplifika d-Definizzjoni tal-Għodod
Il-kitba ta’ skemi JSON bl-idejn hija twila u suxxettibbli għall-iżbalji. Żewġ approċċi jippermettulek tiġġenera definizzjonijiet ta’ għodod mill-kodiċi Python tiegħek: mudelli Pydantic, li l-SDK ta’ xAI jikkonverti f’għodod bil-funzjoni tool() tiegħu, u dekoratur personalizzat sempliċi li jaqra l-firmi tal-funzjonijiet tiegħek.
Approċċ Pydantic
Pydantic hija librerija Python li tippermettilek tiddefinixxi mudelli tad-data b’validazzjoni awtomatika. L-API ta’ Grok tista’ tuża dawn il-mudelli biex tiġġenera skemi JSON għall-għodod.
from pydantic import BaseModel, Field
from typing import Optional
class WeatherParams(BaseModel):
city: str = Field(description="Isem il-belt")
unit: Optional[str] = Field(
default="celsius",
description="Unità tat-temperatura",
enum=["celsius", "fahrenheit"]
)
Dan il-mudell Pydantic jiġġenera awtomatikament l-iskema JSON ekwivalenti għal dak li kieku ktibt bl-idejn. Il-benefiċċji jinkludu:
- Verifika tat-tip: Python jiċċekkja t-tipi waqt ir-run
- Validazzjoni: Pydantic jivvalida d-data awtomatikament
- Dokumentazzjoni: L-entrati
Field(description=...)jservu bħala dokumentazzjoni - Riutilizzabbiltà: l-istess mudell jaħdem għall-validazzjoni u d-dokumentazzjoni tal-API
Mudelli Kumplessi
Pydantic jimmaniġġja strutturi mbejjna, listi, u tipi avvanzati:
from typing import List, Optional
from pydantic import BaseModel, Field
class Address(BaseModel):
street: str = Field(description="Numru u isem it-triq")
city: str = Field(description="Belt")
zip_code: str = Field(description="Kodiċi postali")
country: str = Field(default="FR", description="Kodiċi ISO tal-pajjiż")
class CreateOrderParams(BaseModel):
product_id: str = Field(description="Identifikatur tal-prodott")
quantity: int = Field(description="Kwantità ordnata", ge=1, le=100)
shipping_address: Address = Field(description="Indirizz tal-kunsinna")
notes: Optional[str] = Field(
default=None,
description="Istruzzjonijiet speċjali tal-kunsinna"
)
tags: List[str] = Field(
default=[],
description="Tags għat-traċċar tal-ordni"
)
Il-vincoli ge (akbar jew ugwali) u le (inqas jew ugwali) jiġu ttradotti f’vincoli ta’ Skema JSON li l-mudell jinfurza.
Il-Funzjoni tool() tal-SDK ta’ xAI
L-SDK ta’ xAI ma jaċċettax klassi Pydantic kif inhi: jistenna definizzjoni ta’ għodda, li l-funzjoni tool() tiegħu tibni minn isem, deskrizzjoni, u skema JSON. Pydantic jipprovdi eżattament din l-iskema permezz ta’ model_json_schema():
from xai_sdk.chat import tool
tools = [
tool(
name="get_weather",
description="Ikseb it-temp attwali għal belt",
parameters=WeatherParams.model_json_schema(),
),
]
L-Użu mal-SDK
Tiddikjara l-għodda meta toħloq il-konversazzjoni. L-SDK ma jeżegwix il-funzjonijiet tiegħek: meta Grok jitlob sejħa, il-kodiċi tiegħek jeżegwixxiha, iżid ir-riżultat b’tool_result, imbagħad ikompli l-ġenerazzjoni.
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("It-temp f'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} # l-implimentazzjoni tiegħek
chat.append(tool_result(json.dumps(result)))
response = chat.sample()
print(response.content)
model_validate_json jiċċekkja wkoll li l-argumenti prodotti mill-mudell jaqblu mal-iskema: argument nieqes jew tip żbaljat iqajjem żball qabel ma tibda l-funzjoni tiegħek.
Dekoratur Personalizzat għall-Veloċità
L-SDK ma jipprovdix dekoratur @tool. Xejn ma jwaqqafek milli tikteb wieħed f’ftit linji li jaqra l-firma tal-funzjoni u d-docstring tagħha:
import inspect
from pydantic import create_model
from xai_sdk.chat import tool
def custom_tool(func):
"""Jibni d-definizzjoni tal-għodda ta' xAI mill-firma u d-docstring tal-funzjoni."""
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:
"""Ikseb it-temp attwali għal belt (eż. Pariġi, Lyon)."""
return {"temp": 22, "unit": unit, "city": city}
tools = [custom_tool(get_weather)]
L-isem tal-funzjoni jsir l-isem tal-għodda, l-ewwel paragrafu tad-docstring isir id-deskrizzjoni, u l-parametri mingħajr valuri default isiru meħtieġa. Madankollu, id-deskrizzjonijiet tal-parametri ma jiġux estratti: għal parametri ambigwi, erġa’ lura għal mudell Pydantic b’Field(description=...).
Tqabbil tat-Tliet Approċċi
| Approċċ | Benefiċċji | Limitazzjonijiet |
|---|---|---|
| Skema JSON manwali | Kontroll totali, l-ebda dipendenza | Verboż, żbalji tat-tip ma jiġux skoperti |
Mudell Pydantic + tool() | Validazzjoni tal-argumenti, deskrizzjonijiet għal kull qasam | Klassi waħda għal kull għodda |
| Dekoratur personalizzat | L-aktar konċiż | L-ebda deskrizzjoni għal kull parametru, kodiċi li jrid jinżamm |
Prattiki Aħjar għad-Deskrizzjonijiet
Irrispettivament mill-approċċ, id-deskrizzjoni hija dak li l-mudell jaqra biex jiddeċiedi jekk iħallix l-għodda. Iddikjara meta għandek tużaha, x’tirritorna, u l-format tal-parametri:
class SearchProductsParams(BaseModel):
query: str = Field(description="Termini tat-tiftix: isem tal-prodott jew keywords")
category: str = Field(default="all", description="Kategorija: elettronika, ħwejjeġ, ikel, jew kollha")
max_results: int = Field(default=10, ge=1, le=50, description="Numru massimu ta' riżultati")
search = tool(
name="search_products",
description=(
"Fittex prodotti fil-katalgu tal-kummerċ elettroniku. Uża meta "
"l-utent ifittex prodott bl-isem, id-deskrizzjoni, jew il-kategorija. "
"Jirritorna lista ta' prodotti bi prezz, disponibbiltà, u link."
),
parameters=SearchProductsParams.model_json_schema(),
)
Punti Ewlenin
- Pydantic jiġġenera skemi JSON minn mudelli Python, b’validazzjoni tal-argumenti
- L-SDK ta’ xAI jibni għodod b’
tool(name=..., description=..., parameters=...) - L-SDK ma jeżegwix il-funzjonijiet tiegħek: il-kodiċi tiegħek jagħmel dan, imbagħad jirritorna r-riżultat b’
tool_result - L-SDK m’għandux dekoratur
@tool; dekoratur personalizzat huwa possibbli, bl-ispiża ta’ deskrizzjonijiet għal kull parametru - Irraffina d-deskrizzjonijiet tiegħek: il-mudell jaqrahom biex jagħżel għodda