Pydantic ja työkalumääritykset xAI SDK:n kanssa
Tällä sivulla
Päivitetty 3. marraskuuta 2026 xAI:n Function calling -dokumentaation ja
xai-sdkversion 1.21.0 perusteella: SDK ei tarjoa@client.tool()-dekoraattoria eikä automaattista funktioiden suorittamista. Rakennat työkalut funktiollatool()(käyttäen esimerkiksi Pydantic-skeemaa) ja palautat tulokset funktiollatool_result. Lähde: Function calling.
Työkalumääritysten yksinkertaistaminen
JSON-skeemojen kirjoittaminen käsin on työlästä ja virhealtista. Kaksi lähestymistapaa mahdollistaa työkalumääritysten generoinnin suoraan Python-koodistasi: Pydantic-mallit, jotka xAI SDK muuntaa työkaluiksi tool()-funktiolla, sekä yksinkertainen mukautettu dekoraattori, joka lukee funktiosi allekirjoitukset.
Pydantic-lähestymistapa
Pydantic on Python-kirjasto, jonka avulla voit määritellä datamalleja automaattisella validoinnilla. Grok API voi käyttää näitä malleja generoidakseen JSON-skeemat työkaluille.
from pydantic import BaseModel, Field
from typing import Optional
class WeatherParams(BaseModel):
city: str = Field(description="Kaupungin nimi")
unit: Optional[str] = Field(
default="celsius",
description="Lämpötilan yksikkö",
enum=["celsius", "fahrenheit"]
)
Tämä Pydantic-malli generoi automaattisesti JSON-skeeman, joka vastaa käsin kirjoitettua versiota. Etuja ovat:
- Tyyppitarkistus: Python tarkistaa tyypit ajonaikaisesti
- Validointi: Pydantic validoi datan automaattisesti
- Dokumentaatio:
Field(description=...)-merkinnät toimivat dokumentaationa - Uudelleenkäytettävyys: sama malli toimii sekä validointiin että API-dokumentaatioon
Monimutkaiset mallit
Pydantic hallitsee sisäkkäisiä rakenteita, listoja ja edistyneitä tyyppejä:
from typing import List, Optional
from pydantic import BaseModel, Field
class Address(BaseModel):
street: str = Field(description="Kadun numero ja nimi")
city: str = Field(description="Kaupunki")
zip_code: str = Field(description="Postinumero")
country: str = Field(default="FR", description="ISO-maakoodi")
class CreateOrderParams(BaseModel):
product_id: str = Field(description="Tuotetunniste")
quantity: int = Field(description="Tilattu määrä", ge=1, le=100)
shipping_address: Address = Field(description="Toimitusosoite")
notes: Optional[str] = Field(
default=None,
description="Erityiset toimitusohjeet"
)
tags: List[str] = Field(
default=[],
description="Tagit tilauksen seurantaan"
)
Rajoitteet ge (suurempi tai yhtä suuri) ja le (pienempi tai yhtä suuri) muuntuvat JSON Schema -rajoitteiksi, jotka malli valvoo.
xAI SDK:n tool()-funktio
xAI SDK ei ota Pydantic-luokkaa sellaisenaan: se odottaa työkalumääritystä, jonka sen tool()-funktio rakentaa nimen, kuvauksen ja JSON-skeeman pohjalta. Pydantic tarjoaa täsmälleen tämän skeeman metodilla model_json_schema():
from xai_sdk.chat import tool
tools = [
tool(
name="get_weather",
description="Hae nykyinen sää tietylle kaupungille",
parameters=WeatherParams.model_json_schema(),
),
]
Käyttö SDK:n kanssa
Määrittelet työkalun luodessasi keskustelun. SDK ei suorita funktioitasi: kun Grok pyytää kutsumista, koodisi suorittaa sen, lisää tuloksen tool_result-funktiolla ja jatkaa sitten generointia.
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("Sää Bordeaux'ssa?"))
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} # oma toteutuksesi
chat.append(tool_result(json.dumps(result)))
response = chat.sample()
print(response.content)
model_validate_json tarkistaa myös, että mallin tuottamat argumentit vastaavat skeemaa: puuttuva argumentti tai väärä tyyppi nostaa virheen ennen funktion suorittamista.
Mukautettu dekoraattori nopeutta varten
SDK ei tarjoa @tool-dekoraattoria. Mikään ei kuitenkaan estä sinua kirjoittamasta sellaista muutamassa rivissä, joka lukee funktion allekirjoituksen ja docstringin:
import inspect
from pydantic import create_model
from xai_sdk.chat import tool
def custom_tool(func):
"""Rakentaa xAI-työkalumäärityksen funktion allekirjoituksesta ja docstringistä."""
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:
"""Hae nykyinen sää tietylle kaupungille (esim. Pariisi, Lyon)."""
return {"temp": 22, "unit": unit, "city": city}
tools = [custom_tool(get_weather)]
Funktion nimi muuttuu työkalun nimeksi, docstringin ensimmäinen kappale kuvaukseksi, ja parametrit ilman oletusarvoja muuttuvat pakollisiksi. Parametrien kuvauksia ei kuitenkaan ekstraktoida: epäselvien parametrien kohdalla palaa Pydantic-malliin, jossa käytät Field(description=...).
Kolmen lähestymistavan vertailu
| Lähestymistapa | Edut | Rajoitukset |
|---|---|---|
| Manuaalinen JSON-skeema | Täysi kontrolli, ei riippuvuuksia | Laaja, kirjoitusvirheet jäävät huomaamatta |
Pydantic-malli + tool() | Argumenttien validointi, kenttäkohtaiset kuvaukset | Yksi luokka per työkalu |
| Mukautettu dekoraattori | Tiivein | Ei parametrikohtaisia kuvauksia, ylläpidettävää koodia |
Parhaat käytännöt kuvauksille
Lähestymistavasta riippumatta kuvaus on se, mitä malli lukee päättäessään työkalun kutsumisesta. Kerro milloin sitä käytetään, mitä se palauttaa ja mikä on parametrien muoto:
class SearchProductsParams(BaseModel):
query: str = Field(description="Hakutermit: tuotteen nimi tai avainsanat")
category: str = Field(default="all", description="Kategoria: elektroniikka, vaatteet, ruoka tai kaikki")
max_results: int = Field(default=10, ge=1, le=50, description="Tulosten enimmäismäärä")
search = tool(
name="search_products",
description=(
"Etsi tuotteita verkkokaupan luettelosta. Käytä, kun "
"käyttäjä etsii tuotetta nimen, kuvauksen tai kategorian perusteella. "
"Palauttaa listan tuotteista hintoineen, saatavuustietoineen ja linkkeineen."
),
parameters=SearchProductsParams.model_json_schema(),
)
Keskeiset asiat
- Pydantic generoi JSON-skeemat Python-malleista argumenttien validoinnilla
- xAI SDK rakentaa työkalut funktiolla
tool(name=..., description=..., parameters=...) - SDK ei suorita funktioitasi: koodisi tekee sen ja palauttaa tuloksen
tool_result-funktiolla - SDK:ssa ei ole
@tool-dekoraattoria; mukautettu dekoraattori on mahdollinen, mutta se vie parametrikohtaiset kuvaukset - Hio kuvauksiasi: malli lukee ne valitakseen työkalun