Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Pydantic ja työkalumääritykset xAI SDK:n kanssa

Oppitunti 7 / 14 Päivitetty 3. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Työkalumääritysten yksinkertaistaminen
  2. Pydantic-lähestymistapa
  3. xAI SDK:n tool()-funktio
  4. Mukautettu dekoraattori nopeutta varten
  5. Kolmen lähestymistavan vertailu
  6. Parhaat käytännöt kuvauksille
  7. Keskeiset asiat

Päivitetty 3. marraskuuta 2026 xAI:n Function calling -dokumentaation ja xai-sdk version 1.21.0 perusteella: SDK ei tarjoa @client.tool()-dekoraattoria eikä automaattista funktioiden suorittamista. Rakennat työkalut funktiolla tool() (käyttäen esimerkiksi Pydantic-skeemaa) ja palautat tulokset funktiolla tool_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ähestymistapaEdutRajoitukset
Manuaalinen JSON-skeemaTäysi kontrolli, ei riippuvuuksiaLaaja, kirjoitusvirheet jäävät huomaamatta
Pydantic-malli + tool()Argumenttien validointi, kenttäkohtaiset kuvauksetYksi luokka per työkalu
Mukautettu dekoraattoriTiiveinEi 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