Spring til hovedindhold
Dansk— Vælg et sprog
Menu

Pydantic og værktøjsdefinition med xAI SDK

Lektion 7 af 14 Opdateret 3. november 2026 Udvikler
På denne side
  1. Forenkl værktøjsdefinition
  2. Pydantic-metoden
  3. xAI SDK’ets tool()-funktion
  4. En brugerdefineret dekoration til hurtighed
  5. Sammenligning af de tre metoder
  6. Bedste praksis for beskrivelser
  7. Vigtige pointer

Opdateret 3. november 2026 baseret på xAI-dokumentationen om Function calling og xai-sdk 1.21.0: SDK’et tilbyder hverken en @client.tool()-dekoration eller automatisk funktionsudførelse; du bygger værktøjer med tool() (f.eks. ved hjælp af et Pydantic-skema) og returnerer resultater med tool_result. Kilde: Function calling.

Forenkl værktøjsdefinition

At skrive JSON-skemaer i hånden er omstændeligt og fejlbehæftet. To metoder lader dig generere værktøjsdefinitioner direkte fra din Python-kode: Pydantic-modeller, som xAI SDK’et omdanner til værktøjer med sin tool()-funktion, og en simpel brugerdefineret dekoration, der læser dine funktionssignaturer.

Pydantic-metoden

Pydantic er et Python-bibliotek, der lader dig definere datamodeller med automatisk validering. Grok API’en kan bruge disse modeller til at generere JSON-skemaer til værktøjer.

from pydantic import BaseModel, Field
from typing import Optional

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

Denne Pydantic-model genererer automatisk det JSON-skema, som du ellers skulle have skrevet manuelt. Fordelene inkluderer:

  • Typekontrol: Python tjekker typer ved kørselstidspunktet
  • Validering: Pydantic validerer data automatisk
  • Dokumentation: Field(description=...)-poster fungerer som dokumentation
  • Genanvendelighed: Samme model virker både til validering og API-dokumentation

Komplekse modeller

Pydantic håndterer nestede strukturer, lister og avancerede typer:

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

class Address(BaseModel):
    street: str = Field(description="Gadenavn og husnummer")
    city: str = Field(description="By")
    zip_code: str = Field(description="Postnummer")
    country: str = Field(default="FR", description="ISO-landekode")

class CreateOrderParams(BaseModel):
    product_id: str = Field(description="Produktidentifikator")
    quantity: int = Field(description="Bestilt antal", ge=1, le=100)
    shipping_address: Address = Field(description="Leveringsadresse")
    notes: Optional[str] = Field(
        default=None,
        description="Særlige leveringsinstruktioner"
    )
    tags: List[str] = Field(
        default=[],
        description="Tags til ordresporing"
    )

Begrænsningerne ge (større end eller lig med) og le (mindre end eller lig med) oversættes til JSON Schema-begrænsninger, som modellen håndhæver.

xAI SDK’ets tool()-funktion

xAI SDK’et accepterer ikke en Pydantic-klasse som sådan: Det forventer en værktøjsdefinition, som dets tool()-funktion bygger ud fra et navn, en beskrivelse og et JSON-skema. Pydantic leverer præcis dette skema via model_json_schema():

from xai_sdk.chat import tool

tools = [
    tool(
        name="get_weather",
        description="Hent det aktuelle vejr for en by",
        parameters=WeatherParams.model_json_schema(),
    ),
]

Brug sammen med SDK’et

Du deklarerer værktøjet, når du opretter samtalen. SDK’et udfører ikke dine funktioner: Når Grok anmoder om et kald, udfører din kode det, tilføjer resultatet med tool_result og genoptager derefter genereringen.

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("Vejret i 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}  # din implementering
        chat.append(tool_result(json.dumps(result)))
    response = chat.sample()

print(response.content)

model_validate_json tjekker også, at de argumenter, modellen producerer, matcher skemaet: Et manglende argument eller en forkert type udløser en fejl, før din funktion kører.

En brugerdefineret dekoration til hurtighed

SDK’et leverer ikke en @tool-dekoration. Intet hindrer dig i at skrive en på få linjer, der læser en funktions signatur og docstring:

import inspect

from pydantic import create_model
from xai_sdk.chat import tool


def custom_tool(func):
    """Bygger xAI-værktøjsdefinitionen ud fra en funktions signatur og 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:
    """Hent det aktuelle vejr for en by (f.eks. Paris, Lyon)."""
    return {"temp": 22, "unit": unit, "city": city}


tools = [custom_tool(get_weather)]

Funktionsnavnet bliver til værktøjsnavnet, det første afsnit af docstring’en bliver til beskrivelsen, og parametre uden standardværdier bliver obligatoriske. Parameterbeskrivelser udtrækkes dog ikke: For tvetydige parametre bør du vende tilbage til en Pydantic-model med Field(description=...).

Sammenligning af de tre metoder

MetodeFordeleBegrænsninger
Manuelt JSON-skemaFuld kontrol, ingen afhængighederOmstændeligt, tastefejl opdages ikke
Pydantic-model + tool()Argumentvalidering, beskrivelser pr. feltÉn klasse pr. værktøj
Brugerdefineret dekorationMest koncistIngen beskrivelser pr. parameter, kode der skal vedligeholdes

Bedste praksis for beskrivelser

Uanset hvilken metode du vælger, er beskrivelsen det, modellen læser for at beslutte, om den skal kalde værktøjet. Angiv hvornår det skal bruges, hvad det returnerer, og formatet på parametrene:

class SearchProductsParams(BaseModel):
    query: str = Field(description="Søgeord: produktnavn eller nøgleord")
    category: str = Field(default="all", description="Kategori: elektronik, tøj, fødevarer eller alle")
    max_results: int = Field(default=10, ge=1, le=50, description="Maksimalt antal resultater")


search = tool(
    name="search_products",
    description=(
        "Søg efter produkter i e-handelskataloget. Brug når "
        "brugeren leder efter et produkt efter navn, beskrivelse eller kategori. "
        "Returnerer en liste over produkter med pris, tilgængelighed og link."
    ),
    parameters=SearchProductsParams.model_json_schema(),
)

Vigtige pointer

  • Pydantic genererer JSON-skemaer fra Python-modeller med validering af argumenter
  • xAI SDK’et bygger værktøjer med tool(name=..., description=..., parameters=...)
  • SDK’et udfører ikke dine funktioner: Din kode gør det og returnerer derefter resultatet med tool_result
  • SDK’et har ingen @tool-dekoration; en brugerdefineret dekoration er mulig, men på bekostning af beskrivelser pr. parameter
  • Puds dine beskrivelser af: Modellen læser dem for at vælge et værktøj