Pereiti prie pagrindinio turinio
Lietuvių— Pasirinkite kalbą
Meniu

Pydantic ir įrankių apibrėžimas naudojant xAI SDK

Paskaita 7 iš 14 Atnaujinta 2026 m. lapkričio 3 d. Kūrėjas
Šiame puslapyje
  1. Įrankių apibrėžimo supaprastinimas
  2. Pydantic metodas
  3. xAI SDK tool() funkcija
  4. Individualus dekoratorius greičiui
  5. Trijų metodų palyginimas
  6. Geriausios praktikos rašant aprašymus
  7. Svarbiausi punktai

Atnaujinta 2026 m. lapkričio 3 d. pagal xAI Function calling dokumentaciją ir xai-sdk 1.21.0 versiją: SDK nepateikia nei @client.tool() dekoratoriaus, nei automatinio funkcijų vykdymo; įrankius kuriate naudodami tool() (pvz., su Pydantic schema) ir grąžinate rezultatus naudodami tool_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

MetodasPrivalumaiApribojimai
Rankinė JSON schemaPilna kontrolė, jokių priklausomybiųDaugiažodis, rašybos klaidos lieka nepastebėtos
Pydantic modelis + tool()Argumentų validavimas, kiekvieno lauko aprašymaiViena klasė vienam įrankiui
Individualus dekoratoriusGlaustiausiasNė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 @tool dekoratoriaus; individualus dekoratorius įmanomas, tačiau tenka atsisakyti parametrų aprašymų
  • Tobulinkite savo aprašymus: modelis juos skaito norėdamas pasirinkti įrankį