Spring til hovedindhold
Dansk— Vælg et sprog
Menu

Definér funktioner med JSON Schema

Lektion 3 af 14 Opdateret 29. juli 2026 Udvikler
På denne side
  1. Kontrakten mellem din kode og modellen
  2. Anatomien af en værktøjsspecifikation
  3. Understøttede JSON Schema-typer
  4. Komplet eksempel: To komplementære funktioner
  5. Obligatoriske kontra valgfrie parametre
  6. Bedste praksis for beskrivelser
  7. Vigtige pointer

Kontrakten mellem din kode og modellen

For at Mistral-modellen kan kalde dine funktioner, skal den vide, hvad der findes, og hvordan den skal bruge det. Det er her, JSON Schema kommer ind i billedet: et standardiseret format, der beskriver hver funktion – dens navn, hvad den gør, hvilke parametre den forventer, og hvilke der er obligatoriske.

Husk én ting gennem hele denne lektion: Modellen ser aldrig din Python-kode. Den ser kun denne specifikation. Hvis din funktion håndterer små bogstaver i ID’er uden problemer, men skemaet ikke siger det, ignorerer modellen den mulighed. Jo mere præcis og veldokumenteret dit skema er, desto mere nøjagtige bliver de genererede argumenter.

Anatomien af en værktøjsspecifikation

Hvert værktøj, der sendes til Mistral API, følger samme struktur:

tool = {
    "type": "function",
    "function": {
        "name": "function_name",
        "description": "Clear description of what the function does",
        "parameters": {
            "type": "object",
            "properties": {
                "param1": {
                    "type": "string",
                    "description": "Parameter description"
                },
                "param2": {
                    "type": "integer",
                    "description": "Parameter description"
                }
            },
            "required": ["param1"]
        }
    }
}
FeltRolle
typeAltid "function" (andre typer kan eksistere i fremtiden)
function.nameDet nøjagtige navn på din Python-funktion – dette er det, modellen returnerer i tool_calls
function.descriptionEn klar sætning, der hjælper modellen med at vælge den rigtige funktion
function.parametersEt JSON Schema-objekt, der beskriver de forventede parametre
requiredListen over obligatoriske parametre

Understøttede JSON Schema-typer

Ordforrådet af typer til beskrivelse af parametre er bevidst begrænset, og hver type guider modellen forskelligt. En enum gør mere end blot at dokumentere: den lukker døren for opdigtede værdier.

# String — fri tekst eller begrænset
{"type": "string", "description": "Transaktions-ID"}

# String med enum — begrænsede værdier
{"type": "string", "enum": ["asc", "desc"], "description": "Sorteringsrækkefølge"}

# Integer — heltal
{"type": "integer", "description": "Antal resultater, der skal returneres"}

# Number — decimaltal
{"type": "number", "description": "Beløb i euro"}

# Boolean — sand/falsk
{"type": "boolean", "description": "Inkluder annullerede transaktioner"}

# Array — liste over værdier
{
    "type": "array",
    "items": {"type": "string"},
    "description": "Liste over transaktions-ID'er"
}

# Object — indlejret objekt
{
    "type": "object",
    "properties": {
        "city": {"type": "string"},
        "country": {"type": "string"}
    },
    "description": "Leveringsadresse"
}

Skeln tydeligt mellem integer og number: Et beløb i euro som 125,50 kræver en number, mens et antal resultater, der skal returneres, er et integer. Hvis du definerer et beløb som integer, vil modellen runde det.

Komplet eksempel: To komplementære funktioner

Her er et realistisk eksempel med to betalingsrelaterede funktioner, inspireret af den officielle Mistral-dokumentation:

tools = [
    {
        "type": "function",
        "function": {
            "name": "retrieve_payment_status",
            "description": "Retrieves the status of a payment (paid, pending, failed) "
                           "based on the transaction ID.",
            "parameters": {
                "type": "object",
                "properties": {
                    "transaction_id": {
                        "type": "string",
                        "description": "The unique transaction ID (e.g., T1001)"
                    }
                },
                "required": ["transaction_id"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "retrieve_payment_date",
            "description": "Retrieves the date when a payment was made "
                           "based on the transaction ID.",
            "parameters": {
                "type": "object",
                "properties": {
                    "transaction_id": {
                        "type": "string",
                        "description": "The unique transaction ID (e.g., T1001)"
                    }
                },
                "required": ["transaction_id"]
            }
        }
    }
]

Begge funktioner forventer præcis samme parameter, transaction_id, alligevel skal modellen vælge mellem dem. Dette valg hviler udelukkende på funktionsbeskrivelsen. „Er denne betaling gået igennem?” mapper til retrieve_payment_status; „Hvornår var det?” mapper til retrieve_payment_date. Hvis du havde skrevet to vague, udskiftelige beskrivelser, ville modellen tage fejl halvdelen af tiden – og du ville give modellen skylden, når fejlen egentlig ligger i skemaet.

Obligatoriske kontra valgfrie parametre

Skellet mellem obligatoriske og valgfrie parametre afgør, hvad modellen har lov til at udelade.

{
    "type": "function",
    "function": {
        "name": "search_transactions",
        "description": "Searches for transactions based on various criteria",
        "parameters": {
            "type": "object",
            "properties": {
                "status": {
                    "type": "string",
                    "enum": ["paid", "pending", "failed"],
                    "description": "Filtrer efter betalingsstatus"
                },
                "date_from": {
                    "type": "string",
                    "description": "Startdato i formatet ÅÅÅÅ-MM-DD"
                },
                "date_to": {
                    "type": "string",
                    "description": "Slutdato i formatet ÅÅÅÅ-MM-DD"
                },
                "min_amount": {
                    "type": "number",
                    "description": "Mindstebeløb i euro"
                }
            },
            "required": ["status"]
        }
    }
}

Her er kun status obligatorisk; de andre parametre inkluderes kun, hvis brugeren nævner dem. Sammenlign to formuleringer. Ved „Vis mig mislykkede betalinger” genererer modellen blot {"status": "failed"}. Ved „Vis mig mislykkede betalinger fra marts 2026” tilføjer den selvstændigt date_from og date_to. Havde du gjort disse datoer obligatoriske, ville det have ødelagt den første forespørgsel, eller værre endnu, presset modellen til at opdigte et datointerval.

Bedste praksis for beskrivelser

Kvaliteten af beskrivelser påvirker modellens nøjagtighed direkte. Modeksemplerne nedenfor er mere lærerige end enhver abstrakt regel.

# Dårlig — for vag
{"description": "Henter data"}

# God — præcis og kontekstuel
{"description": "Henter status for en betaling (betalt, afventer, mislykket) "
                "baseret på den unikke transaktions-ID"}

# Dårlig — ingen beskrivelse for parameteren
{"transaction_id": {"type": "string"}}

# God — beskrivelse med eksempel
{"transaction_id": {
    "type": "string",
    "description": "Unik transaktions-ID (format: T efterfulgt af 4 cifre, f.eks. T1001)"
}}

En god beskrivelse angiver i én sætning, hvad funktionen gør, specificerer det forventede format for hver parameter og giver et eksempel, når formatet ikke er indlysende – T1001 er bedre end „transaktions-ID”. Når mulige værdier er begrænsede, så beskriv dem ikke i løbende tekst: erklær dem med enum. Det er den eneste måde at gøre dem bindende på.

Vigtige pointer

  • JSON Schema er kontrakten mellem din kode og modellen – det beskriver dine funktioner uden at afsløre koden
  • Hvert værktøj har et name, en description og typede parameters
  • Understøttede typer inkluderer string, integer, number, boolean, array og object
  • Listen required skelner mellem obligatoriske og valgfrie parametre
  • Præcise beskrivelser med eksempler forbedrer modellens nøjagtighed markant