Премини към основното съдържание
Български— Изберете език
Меню

Дефиниране на инструменти с Pydantic и xAI SDK

Урок 7 от 14 Обновен 3 ноември 2026 г. Програмист
На тази страница
  1. Опростяване на дефинирането на инструменти
  2. Подход с Pydantic
  3. Функцията tool() на xAI SDK
  4. Персонализиран декоратор за бързина
  5. Сравнение на трите подхода
  6. Най-добри практики за описания
  7. Ключови изводи

Обновено на 3 ноември 2026 г. въз основа на документацията на xAI за Function calling и xai-sdk 1.21.0: SDK не предлага декоратор @client.tool(), нито автоматично изпълнение на функции; Вие изграждате инструменти чрез tool() (използвайки например Pydantic схема) и връщате резултатите с tool_result. Източник: Function calling.

Опростяване на дефинирането на инструменти

Ръчното писане на JSON схеми е многословно и податливо на грешки. Съществуват два подхода, които Ви позволяват да генерирате дефиниции на инструменти директно от Вашия Python код: модели на Pydantic, които xAI SDK трансформира в инструменти чрез функцията си tool(), и обикновен персонализиран декоратор, който чете сигнатурите на Вашите функции.

Подход с Pydantic

Pydantic е Python библиотека, която Ви позволява да дефинирате модели за данни с автоматична валидация. Grok API може да използва тези модели за генериране на JSON схеми за инструменти.

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"]
    )

Този Pydantic модел автоматично генерира JSON схемата, еквивалентна на тази, която бихте написали ръчно. Предимствата включват:

  • Проверка на типовете: Python проверява типовете по време на изпълнение (runtime)
  • Валидация: Pydantic валидира данните автоматично
  • Документация: записите Field(description=...) служат като документация
  • Повторна употреба: един и същи модел работи както за валидация, така и за API документация

Сложни модели

Pydantic обработва вложени структури, списъци и разширени типове:

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"
    )

Ограниченията ge (по-голямо или равно) и le (по-малко или равно) се превръщат в ограничения на JSON Schema, които моделът налага.

Функцията tool() на xAI SDK

xAI SDK не приема Pydantic клас такъв, какъвто е: то очаква дефиниция на инструмент, която неговата функция tool() изгражда от име, описание и JSON схема. Pydantic предоставя точно тази схема чрез 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(),
    ),
]

Използване със SDK

Вие декларирате инструмента при създаване на разговора. SDK не изпълнява Вашите функции: когато Grok поиска извикване, Вашият код го изпълнява, добавя резултата с tool_result и след това възобновява генерирането.

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 също така проверява дали аргументите, произведени от модела, съответстват на схемата: липсващ аргумент или грешен тип ще предизвика грешка, преди функцията Ви да се изпълни.

Персонализиран декоратор за бързина

SDK не предоставя декоратор @tool. Нищо не Ви пречи да напишете такъв в няколко реда, който чете сигнатурата и docstring на функцията:

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)]

Името на функцията става име на инструмента, първият абзац на docstring става описание, а параметрите без стойности по подразбиране стават задължителни. Описанията на параметрите обаче не се извличат: за двусмислени параметри се върнете към Pydantic модел с Field(description=...).

Сравнение на трите подхода

ПодходПредимстваОграничения
Ръчна JSON схемаПълен контрол, без зависимостиМногословно, правописните грешки остават неоткрити
Pydantic модел + tool()Валидация на аргументите, описания за всяко полеЕдин клас за всеки инструмент
Персонализиран декораторНай-кратък кодНяма описания за отделни параметри, код за поддръжка

Най-добри практики за описания

Независимо от подхода, описанието е това, което моделът чете, за да реши дали да извика инструмента. Посочете кога да се използва, какво връща и формата на параметрите:

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(),
)

Ключови изводи

  • Pydantic генерира JSON схеми от Python модели, с валидация на аргументите
  • xAI SDK изгражда инструменти с tool(name=..., description=..., parameters=...)
  • SDK не изпълнява Вашите функции: Вашият код го прави, след което връща резултата с tool_result
  • SDK няма декоратор @tool; възможен е персонализиран декоратор, но с цената на липсата на описания за отделни параметри
  • Прецизирайте Вашите описания: моделът ги чете, за да избере инструмент