Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Pydantic ja tööriistade määratlemine xAI SDK-ga

Õppetund 7 / 14 Värskendatud 3. november 2026 Arendajatele
Sellel lehel
  1. Lihtsusta tööriistade määratlemist
  2. Pydanticu lähenemine
  3. xAI SDK funktsioon tool()
  4. Kohandatud dekoraator kiiruse huvides
  5. Kolme lähenemise võrdlus
  6. Parimad tavad kirjelduste jaoks
  7. Peamised punktid

Uuendatud 3. novembril 2026 põhinedes xAI Function calling dokumentatsioonil ja xai-sdk versioonil 1.21.0: SDK ei paku ei @client.tool() dekoraatorit ega funktsioonide automaatset käivitamist; sa lood tööriistu funktsiooniga tool() (kasutades näiteks Pydanticu skeemi) ja tagastad tulemused tool_result abil. Allikas: Function calling.

Lihtsusta tööriistade määratlemist

JSON-skeemide käsitsi kirjutamine on sõnaohke ja vigadele avatud. Kaks lähenemist võimaldavad sul genereerida tööriistade määratlusi otse oma Pythoni koodist: Pydanticu mudelid, mille xAI SDK teisendab oma tool() funktsiooniga tööriistadeks, ja lihtne kohandatud dekoraator, mis loeb sinu funktsioonide signatuure.

Pydanticu lähenemine

Pydantic on Pythoni teek, mis võimaldab defineerida andmemudeleid automaatse valideerimisega. Groki API saab neid mudeleid kasutada tööriistade JSON-skeemide genereerimiseks.

from pydantic import BaseModel, Field
from typing import Optional

class WeatherParams(BaseModel):
    city: str = Field(description="Linna nimi")
    unit: Optional[str] = Field(
        default="celsius",
        description="Temperatuuri ühik",
        enum=["celsius", "fahrenheit"]
    )

See Pydanticu mudel genereerib automaatselt JSON-skeemi, mis on samaväärne sellega, mida oleksid pidanud käsitsi kirjutama. Eelised hõlmavad:

  • Tüübikontroll: Python kontrollib tüüpe käitusajal
  • Valideerimine: Pydantic valideerib andmed automaatselt
  • Dokumentatsioon: kirjed Field(description=...) toimivad dokumentatsioonina
  • Taaskasutatavus: sama mudel töötab nii valideerimiseks kui ka API dokumentatsiooniks

Komplekssed mudelid

Pydantic haldab pesastatud struktuure, loendeid ja täiustatud tüüpe:

from typing import List, Optional
from pydantic import BaseModel, Field

class Address(BaseModel):
    street: str = Field(description="Tänava number ja nimi")
    city: str = Field(description="Linn")
    zip_code: str = Field(description="Postiindeks")
    country: str = Field(default="FR", description="ISO riigikood")

class CreateOrderParams(BaseModel):
    product_id: str = Field(description="Toote identifikaator")
    quantity: int = Field(description="Tellitud kogus", ge=1, le=100)
    shipping_address: Address = Field(description="Tarneaadress")
    notes: Optional[str] = Field(
        default=None,
        description="Erilised tarnejuhised"
    )
    tags: List[str] = Field(
        default=[],
        description="Sildid tellimuse jälgimiseks"
    )

Piirangud ge (suurem või võrdne) ja le (väiksem või võrdne) teisendatakse JSON-skeemi piiranguteks, mida mudel jõustab.

xAI SDK funktsioon tool()

xAI SDK ei võta Pydanticu klassi sellisena vastu: see eeldab tööriista määratlust, mille selle funktsioon tool() ehitab nime, kirjelduse ja JSON-skeemi põhjal. Pydantic pakub täpselt seda skeemi meetodi model_json_schema() kaudu:

from xai_sdk.chat import tool

tools = [
    tool(
        name="get_weather",
        description="Hangi praegune ilm linna kohta",
        parameters=WeatherParams.model_json_schema(),
    ),
]

Kasutamine SDK-ga

Deklareerid tööriista vestluse loomisel. SDK ei käivita sinu funktsioone: kui Grok taotleb väljakutset, käivitab sinu kood selle, lisab tulemuse tool_result abil ja jätkab seejärel genereerimist.

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("Ilm Bordeaux's?"))
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}  # sinu implementatsioon
        chat.append(tool_result(json.dumps(result)))
    response = chat.sample()

print(response.content)

model_validate_json kontrollib ka seda, kas mudeli loodud argumendid vastavad skeemile: puuduv argument või vale tüüp tõstab vea enne, kui sinu funktsioon käivitub.

Kohandatud dekoraator kiiruse huvides

SDK ei paku @tool dekoraatorit. miski ei takista sul kirjutamast paari reaga oma versiooni, mis loeb funktsiooni signatuuri ja dokstringi:

import inspect

from pydantic import create_model
from xai_sdk.chat import tool


def custom_tool(func):
    """Ehitab xAI tööriista määratluse funktsiooni signatuuri ja dokstringi põhjal."""
    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:
    """Hangi praegune ilm linna kohta (nt Pariis, Lyon)."""
    return {"temp": 22, "unit": unit, "city": city}


tools = [custom_tool(get_weather)]

Funktsiooni nimi muutub tööriista nimeks, dokstringi esimene lõik muutub kirjelduseks ja parameetrid ilma vaikeväärtusteta muutuvad kohustuslikeks. Parameetrite kirjeldusi aga ei ekstraheerita: mitmetimõistetavate parameetrite puhul pöördu tagasi Pydanticu mudeli juurde, kasutades Field(description=...).

Kolme lähenemise võrdlus

LähenemineEelisedPiirangud
Käsitsi JSON-skeemTäielik kontroll, sõltuvusi poleSõnaohke, trükivead jäävad märkamata
Pydanticu mudel + tool()Argumentide valideerimine, väljapõhised kirjeldusedÜks klass ühe tööriista kohta
Kohandatud dekoraatorKõige lühemPuuduvad parameetripõhised kirjeldused, koodi hooldusvajadus

Parimad tavad kirjelduste jaoks

Sõltumata lähenemisviisist on kirjeldus see, mida mudel loeb, otsustamaks, kas tööriista kutsuda. Täpsusta, millal seda kasutada, mida see tagastab ja milline on parameetrite formaat:

class SearchProductsParams(BaseModel):
    query: str = Field(description="Otsinguterminid: toote nimi või märksõnad")
    category: str = Field(default="all", description="Kategooria: elektroonika, rõivad, toit või kõik")
    max_results: int = Field(default=10, ge=1, le=50, description="Tulemuste maksimaalne arv")


search = tool(
    name="search_products",
    description=(
        "Otsi tooteid e-kaubanduse kataloogist. Kasuta siis, kui "
        "kasutaja otsib tootet nime, kirjelduse või kategooria järgi. "
        "Tagastab toodete loendi hinnaga, saadavuse ja lingiga."
    ),
    parameters=SearchProductsParams.model_json_schema(),
)

Peamised punktid

  • Pydantic genereerib JSON-skeeme Pythoni mudelitest koos argumentide valideerimisega
  • xAI SDK ehitab tööriistu funktsiooniga tool(name=..., description=..., parameters=...)
  • SDK ei käivita sinu funktsioone: sinu kood teeb seda ja tagastab tulemuse tool_result abil
  • SDK-l puudub @tool dekoraator; kohandatud dekoraator on võimalik, kuid kaotad parameetripõhised kirjeldused
  • Viimistle oma kirjeldusi: mudel loeb neid tööriista valimiseks