Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Pydantic u d-Definizzjoni tal-Għodod bis-SDK ta' xAI

Lezzjoni 7 / 14 Aġġornat 3 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. Issimplifika d-Definizzjoni tal-Għodod
  2. Approċċ Pydantic
  3. Il-Funzjoni tool() tal-SDK ta’ xAI
  4. Dekoratur Personalizzat għall-Veloċità
  5. Tqabbil tat-Tliet Approċċi
  6. Prattiki Aħjar għad-Deskrizzjonijiet
  7. Punti Ewlenin

Aġġornat fit-3 ta’ Novembru 2026 abbażi tad-dokumentazzjoni Function calling ta’ xAI u xai-sdk 1.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ċċjiLimitazzjonijiet
Skema JSON manwaliKontroll totali, l-ebda dipendenzaVerboż, żbalji tat-tip ma jiġux skoperti
Mudell Pydantic + tool()Validazzjoni tal-argumenti, deskrizzjonijiet għal kull qasamKlassi waħda għal kull għodda
Dekoratur personalizzatL-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