Salt la conținutul principal
Română— Alege o limbă
Meniu

Pydantic și definirea instrumentelor cu SDK-ul xAI

Lecția 7 din 14 Actualizată 3 noiembrie 2026 Dezvoltator
Pe această pagină
  1. Simplificarea definirii instrumentelor
  2. Abordarea cu Pydantic
  3. Funcția tool() din SDK-ul xAI
  4. Un decorator personalizat pentru viteză
  5. Compararea celor trei abordări
  6. Cele mai bune practici pentru descrieri
  7. Puncte cheie

Actualizat la 3 noiembrie 2026 pe baza documentației Function calling de la xAI și a versiunii xai-sdk 1.21.0: SDK-ul nu oferă nici un decorator @client.tool(), nici execuție automată a funcțiilor; construiți instrumentele cu tool() (folosind, de exemplu, o schemă Pydantic) și returnați rezultatele cu tool_result. Sursă: Function calling.

Simplificarea definirii instrumentelor

Scrierea manuală a schemelor JSON este verbose și predispusă la erori. Există două abordări care vă permit să generați definițiile instrumentelor direct din codul Python: modelele Pydantic, pe care SDK-ul xAI le transformă în instrumente prin funcția sa tool(), și un decorator personalizat simplu care citește semnăturile funcțiilor dumneavoastră.

Abordarea cu Pydantic

Pydantic este o bibliotecă Python care vă permite să definiți modele de date cu validare automată. API-ul Grok poate utiliza aceste modele pentru a genera scheme JSON pentru instrumente.

from pydantic import BaseModel, Field
from typing import Optional

class WeatherParams(BaseModel):
    city: str = Field(description="City name")
    unit: Optional[str] = Field(
        default="celsius",
        description="Temperature unit",
        enum=["celsius", "fahrenheit"]
    )

Acest model Pydantic generează automat schema JSON echivalentă cu cea pe care ați fi scris-o manual. Printre avantaje se numără:

  • Verificarea tipurilor: Python verifică tipurile la runtime
  • Validare: Pydantic validează datele automat
  • Documentație: intrările Field(description=...) servesc drept documentație
  • Reutilizare: același model funcționează atât pentru validare, cât și pentru documentația API

Modele complexe

Pydantic gestionează structuri imbricate, liste și tipuri avansate:

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

class Address(BaseModel):
    street: str = Field(description="Street number and name")
    city: str = Field(description="City")
    zip_code: str = Field(description="ZIP code")
    country: str = Field(default="FR", description="ISO country code")

class CreateOrderParams(BaseModel):
    product_id: str = Field(description="Product identifier")
    quantity: int = Field(description="Ordered quantity", ge=1, le=100)
    shipping_address: Address = Field(description="Shipping address")
    notes: Optional[str] = Field(
        default=None,
        description="Special delivery instructions"
    )
    tags: List[str] = Field(
        default=[],
        description="Tags for order tracking"
    )

Constrângerile ge (mai mare sau egal) și le (mai mic sau egal) se traduc în constrângeri ale schemei JSON pe care modelul le impune.

Funcția tool() din SDK-ul xAI

SDK-ul xAI nu acceptă o clasă Pydantic ca atare: acesta așteaptă o definiție de instrument, pe care funcția sa tool() o construiește dintr-un nume, o descriere și o schemă JSON. Pydantic oferă exact această schemă prin model_json_schema():

from xai_sdk.chat import tool

tools = [
    tool(
        name="get_weather",
        description="Get the current weather for a city",
        parameters=WeatherParams.model_json_schema(),
    ),
]

Utilizarea cu SDK-ul

Declarați instrumentul atunci când creați conversația. SDK-ul nu execută funcțiile dumneavoastră: când Grok solicită un apel, codul dumneavoastră îl execută, adaugă rezultatul cu tool_result, apoi reia generarea.

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("Weather in Bordeaux?"))
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}  # your implementation
        chat.append(tool_result(json.dumps(result)))
    response = chat.sample()

print(response.content)

model_validate_json verifică, de asemenea, dacă argumentele produse de model corespund schemei: un argument lipsă sau un tip greșit va genera o eroare înainte ca funcția dumneavoastră să ruleze.

Un decorator personalizat pentru viteză

SDK-ul nu oferă un decorator @tool. Nimic nu vă împiedică să scrieți unul în câteva linii, care să citească semnătura și docstring-ul unei funcții:

import inspect

from pydantic import create_model
from xai_sdk.chat import tool


def custom_tool(func):
    """Builds the xAI tool definition from a function's signature and 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:
    """Get the current weather for a city (e.g., Paris, Lyon)."""
    return {"temp": 22, "unit": unit, "city": city}


tools = [custom_tool(get_weather)]

Numele funcției devine numele instrumentului, primul paragraf al docstring-ului devine descrierea, iar parametrii fără valori implicite devin obligatorii. Descrierile parametrilor, totuși, nu sunt extrase: pentru parametri ambigui, reveniți la un model Pydantic cu Field(description=...).

Compararea celor trei abordări

AbordareAvantajeLimitări
Schema JSON manualăControl total, fără dependențeVerbose, greșelile de tastare trec neobservate
Model Pydantic + tool()Validarea argumentelor, descrieri pe câmpO clasă per instrument
Decorator personalizatCel mai concisFără descrieri per parametru, cod de întreținut

Cele mai bune practici pentru descrieri

Indiferent de abordare, descrierea este ceea ce modelul citește pentru a decide dacă să apeleze instrumentul. Specificați când să îl utilizați, ce returnează și formatul parametrilor:

class SearchProductsParams(BaseModel):
    query: str = Field(description="Search terms: product name or keywords")
    category: str = Field(default="all", description="Category: electronics, clothing, food, or all")
    max_results: int = Field(default=10, ge=1, le=50, description="Maximum number of results")


search = tool(
    name="search_products",
    description=(
        "Search for products in the e-commerce catalog. Use when "
        "the user looks for a product by name, description, or category. "
        "Returns a list of products with price, availability, and link."
    ),
    parameters=SearchProductsParams.model_json_schema(),
)

Puncte cheie

  • Pydantic generează scheme JSON din modele Python, cu validarea argumentelor
  • SDK-ul xAI construiește instrumente cu tool(name=..., description=..., parameters=...)
  • SDK-ul nu execută funcțiile dumneavoastră: codul dumneavoastră o face, apoi returnează rezultatul cu tool_result
  • SDK-ul nu are un decorator @tool; un decorator personalizat este posibil, cu costul pierderii descrierilor per parametru
  • Șlefuiți-vă descrierile: modelul le citește pentru a alege un instrument