Pydantic și definirea instrumentelor cu SDK-ul xAI
Pe această pagină
Actualizat la 3 noiembrie 2026 pe baza documentației Function calling de la xAI și a versiunii
xai-sdk1.21.0: SDK-ul nu oferă nici un decorator@client.tool(), nici execuție automată a funcțiilor; construiți instrumentele cutool()(folosind, de exemplu, o schemă Pydantic) și returnați rezultatele cutool_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
| Abordare | Avantaje | Limitări |
|---|---|---|
| Schema JSON manuală | Control total, fără dependențe | Verbose, greșelile de tastare trec neobservate |
Model Pydantic + tool() | Validarea argumentelor, descrieri pe câmp | O clasă per instrument |
| Decorator personalizat | Cel mai concis | Fă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