Pydantic ir įrankių apibrėžimas naudojant xAI SDK
Šiame puslapyje
Atnaujinta 2026 m. lapkričio 3 d. pagal xAI Function calling dokumentaciją ir
xai-sdk1.21.0 versiją: SDK nepateikia nei@client.tool()dekoratoriaus, nei automatinio funkcijų vykdymo; įrankius kuriate naudodamitool()(pvz., su Pydantic schema) ir grąžinate rezultatus naudodamitool_result. Šaltinis: Function calling.
Įrankių apibrėžimo supaprastinimas
JSON schemų rašymas rankiniu būdu yra daugiažodis ir klaidų kupinas. Yra du būdai, leidžiantys generuoti įrankių apibrėžimus tiesiai iš Python kodo: Pydantic modeliai, kuriuos xAI SDK paverčia įrankiais naudodama savo tool() funkciją, ir paprastas individualus dekoratorius, nuskaitydamas jūsų funkcijų parašus.
Pydantic metodas
Pydantic yra Python biblioteka, leidžianti apibrėžti duomenų modelius su automatiniu validavimu. Grok API gali naudoti šiuos modelius JSON schemoms įrankiams generuoti.
from pydantic import BaseModel, Field
from typing import Optional
class WeatherParams(BaseModel):
city: str = Field(description="Miesto pavadinimas")
unit: Optional[str] = Field(
default="celsius",
description="Temperatūros vienetas",
enum=["celsius", "fahrenheit"]
)
Šis Pydantic modelis automatiškai sugeneruoja JSON schemą, lygiavertę tai, kurią būtumėte parašę rankiniu būdu. Privalumai:
- Tipų tikrinimas: Python tikrina tipus vykdymo metu
- Validavimas: Pydantic automatiškai validuoja duomenis
- Dokumentacija:
Field(description=...)įrašai tarnauja kaip dokumentacija - Pakartotinis naudojimas: tas pats modelis tinka ir validavimui, ir API dokumentacijai
Sudėtingi modeliai
Pydantic tvarko įdėtąsias struktūras, sąrašus ir pažangius tipus:
from typing import List, Optional
from pydantic import BaseModel, Field
class Address(BaseModel):
street: str = Field(description="Gatvės numeris ir pavadinimas")
city: str = Field(description="Miestas")
zip_code: str = Field(description="Pašto kodas")
country: str = Field(default="FR", description="ISO šalies kodas")
class CreateOrderParams(BaseModel):
product_id: str = Field(description="Produkto identifikatorius")
quantity: int = Field(description="Užsakytas kiekis", ge=1, le=100)
shipping_address: Address = Field(description="Pristatymo adresas")
notes: Optional[str] = Field(
default=None,
description="Specialios pristatymo instrukcijos"
)
tags: List[str] = Field(
default=[],
description="Žymos užsakymo sekimui"
)
Apribojimai ge (daugiau arba lygu) ir le (mažiau arba lygu) paverčiami JSON Schema apribojimais, kuriuos modelis užtikrina.
xAI SDK tool() funkcija
xAI SDK nepriima Pydantic klasės tokios, kokia ji yra: ji tikisi įrankio apibrėžimo, kurį jos tool() funkcija sukuria iš pavadinimo, aprašymo ir JSON schemos. Pydantic pateikia būtent šią schemą per model_json_schema():
from xai_sdk.chat import tool
tools = [
tool(
name="get_weather",
description="Gauti dabartinę oro temperatūrą mieste",
parameters=WeatherParams.model_json_schema(),
),
]
Naudojimas su SDK
Įrankį deklaruojate kurdami pokalbį. SDK nevykdo jūsų funkcijų: kai Grok prašo įvykdyti kvietimą, jūsų kodas jį įvykdo, prideda rezultatą naudodamas tool_result, tada atnaujina generavimą.
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("Koks oras Bordo mieste?"))
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} # jūsų implementacija
chat.append(tool_result(json.dumps(result)))
response = chat.sample()
print(response.content)
model_validate_json taip pat patikrina, ar modelio sugeneruoti argumentai atitinka schemą: trūkstamas argumentas arba neteisingas tipas sukels klaidą prieš jūsų funkcijai pradedant veikti.
Individualus dekoratorius greičiui
SDK nepateikia @tool dekoratoriaus. Niekas netrukdo jums parašyti tokio per kelias eilutes, kuris nuskaitytų funkcijos parašą ir dokumentacijos eilutę (docstring):
import inspect
from pydantic import create_model
from xai_sdk.chat import tool
def custom_tool(func):
"""Sukuria xAI įrankio apibrėžimą iš funkcijos parašo ir 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:
"""Gauti dabartinę oro temperatūrą mieste (pvz., Paryžius, Lionas)."""
return {"temp": 22, "unit": unit, "city": city}
tools = [custom_tool(get_weather)]
Funkcijos pavadinimas tampa įrankio pavadinimu, pirmasis docstring pastraipos sakinys tampa aprašymu, o parametrai be numatytųjų reikšmių tampa privalomais. Tačiau parametrų aprašymai neišskiriami: dviprasmiškiems parametrams grįžkite prie Pydantic modelio su Field(description=...).
Trijų metodų palyginimas
| Metodas | Privalumai | Apribojimai |
|---|---|---|
| Rankinė JSON schema | Pilna kontrolė, jokių priklausomybių | Daugiažodis, rašybos klaidos lieka nepastebėtos |
Pydantic modelis + tool() | Argumentų validavimas, kiekvieno lauko aprašymai | Viena klasė vienam įrankiui |
| Individualus dekoratorius | Glaustiausias | Nėra parametrų aprašymų, reikia prižiūrėti kodą |
Geriausios praktikos rašant aprašymus
Nepriklausomai nuo pasirinkto metodo, aprašymas yra tai, ką modelis skaito spręsdamas, ar kviesti įrankį. Nurodykite, kada jį naudoti, ką jis grąžina ir koks yra parametrų formatas:
class SearchProductsParams(BaseModel):
query: str = Field(description="Paieškos terminai: produkto pavadinimas arba raktiniai žodžiai")
category: str = Field(default="all", description="Kategorija: elektronika, drabužiai, maistas arba viskas")
max_results: int = Field(default=10, ge=1, le=50, description="Maksimalus rezultatų skaičius")
search = tool(
name="search_products",
description=(
"Ieškoti produktų el. prekybos kataloge. Naudokite, kai "
"vartotojas ieško produkto pagal pavadinimą, aprašymą ar kategoriją. "
"Grąžina produktų sąrašą su kaina, prieinamumu ir nuoroda."
),
parameters=SearchProductsParams.model_json_schema(),
)
Svarbiausi punktai
- Pydantic generuoja JSON schemas iš Python modelių su argumentų validavimu
- xAI SDK kuria įrankius naudodama
tool(name=..., description=..., parameters=...) - SDK nevykdo jūsų funkcijų: tai daro jūsų kodas, o tada grąžina rezultatą per
tool_result - SDK neturi
@tooldekoratoriaus; individualus dekoratorius įmanomas, tačiau tenka atsisakyti parametrų aprašymų - Tobulinkite savo aprašymus: modelis juos skaito norėdamas pasirinkti įrankį