Léim go dtí an príomhábhar
Gaeilge— Roghnaigh teanga
Roghchlár

Pydantic agus Sainmhíniú Uirlisí leis an xAI SDK

Ceacht 7 as 14 Nuashonraithe 3 Samhain 2026 Forbróir
Ar an leathanach seo
  1. Simpligh Sainmhíniú na nUirlisí
  2. Cur Chuige Pydantic
  3. An Fheidhm tool() san xAI SDK
  4. Maiseac Saincheaptha ar mhaithe le Luas
  5. Comparáid idir na Trí Chur Chuige
  6. Barrachleachtais do chur síos
  7. Príomhphointí

Nuashonraithe an 3 Samhain, 2026 bunaithe ar dhoiciméadacht Function calling xAI agus xai-sdk 1.21.0: ní thairgeann an SDK maisc @client.tool() ná feidhmiú uathoibríoch; déanann tú uirlisí le tool() (ag baint úsáide as scéama Pydantic, mar shampla) agus filleann tú torthaí le tool_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 ChuigeSochairTeorainneacha
Scéama JSON de láimhRialú iomlán, gan spleáchaisFada, théann litrithe míchearta in éag gan bhrath
Samhail Pydantic + tool()Bailíochtú argóintí, cur síosanna in aghaidh na réimseAicme amháin in aghaidh na huirlise
Maiseac saincheapthaAn ceann is giorraGan 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 @tool ag 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ú