Pydantic agus Sainmhíniú Uirlisí leis an xAI SDK
Ar an leathanach seo
Nuashonraithe an 3 Samhain, 2026 bunaithe ar dhoiciméadacht Function calling xAI agus
xai-sdk1.21.0: ní thairgeann an SDK maisc@client.tool()ná feidhmiú uathoibríoch; déanann tú uirlisí letool()(ag baint úsáide as scéama Pydantic, mar shampla) agus filleann tú torthaí letool_result. Foinse: Function calling.
Simpligh Sainmhíniú na nUirlisí
Tá scríobh scéamaí JSON de láimh fada agus lán earráidí. Tá dhá chur chuige ann a ligeann duit sainmhínithe uirlisí a ghiniúint ó do chód Python: samhlacha Pydantic, a ndéanann an xAI SDK uirlisí astu lena fheidhm tool(), agus maisc saincheaptha simplí a léann do shínithe feidhme.
Cur Chuige Pydantic
Is leabharlann Python é Pydantic a ligeann duit samhlacha sonraí a shainiú le bailíochtú uathoibríoch. Is féidir leis an API Grok na samhlacha seo a úsáid chun scéamaí JSON d’uirlisí a ghiniúint.
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"]
)
Giníonn an tsamhail Pydantic seo an scéama JSON go huathoibríoch atá coibhéiseach leis an gceann a scríobhfá de láimh. I measc na sochar tá:
- Seiceáil cineáil: Seiceálann Python cineálacha ag am rith
- Bailíochtú: Déanann Pydantic bailíochtú ar shonraí go huathoibríoch
- Doiciméadú: Feidhmíonn iontrálacha
Field(description=...)mar dhoiciméadú - In-athúsáidteacht: Oibríonn an tsamhail chéanna le haghaidh bailíochtaithe agus doiciméadaithe API
Samhlacha Casta
Láimhseálann Pydantic struchtúir neadaithe, liostaí, agus cineálacha casta:
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"
)
Aistrítear na srianta ge (níos mó ná nó cothrom le) agus le (níos lú ná nó cothrom le) go srianta Scéama JSON a fhorghníomhaíonn an tsamhail.
An Fheidhm tool() san xAI SDK
Ní ghlacann an xAI SDK le haicme Pydantic mar atá sí: teastaíonn sainmhíniú uirlise uaidh, a thógann a fheidhm tool() ó ainm, cur síos, agus scéama JSON. Soláthraíonn Pydantic an scéama seo go díreach trí 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(),
),
]
Ag Úsáid leis an SDK
Dearbhaíonn tú an uirlis agus an comhrá á chruthú agat. Ní fhorghníomhaíonn an SDK do chuid feidhmeanna: nuair a iarrann Grok glao, forghníomhaíonn do chód é, cuireann tú an toradh leis le tool_result, agus ansin leanann tú ar aghaidh leis an nginiúint.
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)
Seiceálann model_validate_json freisin go bhfuil na hargóintí a tháirgeann an tsamhail ag teacht leis an scéama: ardaíonn argóint in easnamh nó cineál mícheart earráid sula rithfidh do fheidhm.
Maiseac Saincheaptha ar mhaithe le Luas
Ní sholáthraíonn an SDK maisc @tool. Ní chuireann aon rud cosc ort ceann a scríobh i roinnt línte a léann sínithe feidhme agus docshreang:
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)]
Éiríonn ainm na feidhme ina ainm uirlise, éiríonn an chéad alt den docshreang ina chur síos, agus éiríonn paraiméadair gan luachanna réamhshocraithe ina bparaiméadair éigeantacha. Ní eastósctar cur síosanna paraiméadair, áfach: le haghaidh paraiméadair atá débhríoch, fill ar shamhail Pydantic le Field(description=...).
Comparáid idir na Trí Chur Chuige
| Cur Chuige | Sochair | Teorainneacha |
|---|---|---|
| Scéama JSON de láimh | Rialú iomlán, gan spleáchais | Fada, théann litrithe míchearta in éag gan bhrath |
Samhail Pydantic + tool() | Bailíochtú argóintí, cur síosanna in aghaidh na réimse | Aicme amháin in aghaidh na huirlise |
| Maiseac saincheaptha | An ceann is giorra | Gan cur síosanna in aghaidh na bparaiméadar, cód le cothabháil |
| Cleachtais Is Fearr le haghaidh Cur Síosanna
Beag beann ar an gcur chuige, is é an cur síos an rud a léann an tsamhail chun cinneadh a dhéanamh an dtugtar glao ar an uirlis nó nach dtugtar. Luaigh cathain a úsáidtear é, cad a fhilleann sé, agus formáid na bparaiméadar:
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(),
)
Barrachleachtais do chur síos
Príomhphointí
- Gineann Pydantic scéamaí JSON ó shamhlacha Python, le bailíochtú argóintí
- Tógann an xAI SDK uirlisí le
tool(name=..., description=..., parameters=...) - Ní fhorghníomhaíonn an SDK do chuid feidhmeanna: déanann do chód é, ansin filleann sé an toradh le
tool_result - Níl aon mhaisc
@toolag an SDK; tá maisc saincheaptha indéanta, ach ar chostas cur síosanna in aghaidh na bparaiméadar - Snas do chuid cur síosanna: léann an tsamhail iad chun uirlis a roghnú