Funktionen mit JSON Schema definieren
Auf dieser Seite
Der Vertrag zwischen Ihrem Code und dem Modell
Damit das Mistral-Modell Ihre Funktionen aufrufen kann, muss es wissen, was verfügbar ist und wie es diese verwenden soll. Dies ist die Aufgabe des JSON Schema: eines standardisierten Formats, das jede Funktion beschreibt – ihren Namen, ihre Funktion, die erwarteten Parameter und welche davon zwingend sind.
Halten Sie während dieser Lektion Folgendes im Hinterkopf: Das Modell sieht Ihren Python-Code niemals. Es sieht nur diese Spezifikation. Wenn Ihre Funktion kleine IDs (lowercase IDs) elegant verarbeitet, ignoriert das Modell diese Fähigkeit, wenn das Schema dies nicht explizit sagt. Je präziser und besser dokumentiert Ihr Schema ist, desto genauer werden die generierten Argumente.
Anatomie einer Tool-Spezifikation
Jedes Tool, das an die Mistral API gesendet wird, folgt derselben Struktur:
tool = {
"type": "function",
"function": {
"name": "function_name",
"description": "Klare Beschreibung dessen, was die Funktion tut",
"parameters": {
"type": "object",
"properties": {
"param1": {
"type": "string",
"description": "Parameter-Beschreibung"
},
"param2": {
"type": "integer",
"description": "Parameter-Beschreibung"
}
},
"required": ["param1"]
}
}
}
| Feld | Rolle |
|---|---|
type | Immer "function" (andere Typen könnten in Zukunft existieren) |
function.name | Der exakte Name Ihrer Python-Funktion – dies ist das, was das Modell in tool_calls zurückgibt |
function.description | Ein klarer Satz, der dem Modell hilft, die richtige Funktion auszuwählen |
function.parameters | Ein JSON-Objekt, das die erwarteten Parameter beschreibt |
required | Die Liste der zwingenden Parameter |
Unterstützte JSON-Schema-Typen
Das Vokabular für die Beschreibung von Parametern ist absichtlich eingeschränkt, und jeder Typ leitet das Modell unterschiedlich. Ein enum tut beispielsweise mehr als nur zu dokumentieren: Es schließt die Tür für erfundene Werte.
# String — freier Text oder eingeschränkt
{"type": "string", "description": "Transaktions-ID"}
# String mit Enum — begrenzte Werte
{"type": "string", "enum": ["asc", "desc"], "description": "Sortierreihenfolge"}
# Integer — ganze Zahl
{"type": "integer", "description": "Anzahl der zurückzugebenden Ergebnisse"}
# Number — Dezimalzahl
{"type": "number", "description": "Betrag in Euro"}
# Boolean — wahr/falsch
{"type": "boolean", "description": "Abgebrochene Transaktionen einschließen"}
# Array — Liste von Werten
{
"type": "array",
"items": {"type": "string"},
"description": "Liste von Transaktions-IDs"
}
# Object — verschachteltes Objekt
{
"type": "object",
"properties": {
"stadt": {"type": "string"},
"land": {"type": "string"}
},
"description": "Versandadresse"
}
Unterscheiden Sie klar zwischen integer und number: Ein Betrag in Euro wie 125,50 erfordert ein number, während eine Anzahl von Ergebnissen ein integer ist. Die Deklaration eines Betrags als integer führt dazu, dass das Modell diesen rundet.
Komplettes Beispiel: zwei komplementäre Funktionen
Hier ist ein realistisches Beispiel mit zwei zahlungsbezogenen Funktionen, inspiriert von der offiziellen Mistral-Dokumentation:
tools = [
{
"type": "function",
"function": {
"name": "retrieve_payment_status",
"description": "Ruft den Status einer Zahlung (bezahlt, ausstehend, fehlgeschlagen) "
"basierend auf der Transaktions-ID ab.",
"parameters": {
"type": "object",
"properties": {
"transaction_id": {
"type": "string",
"description": "Die eindeutige Transaktions-ID (z. B. T1001)"
}
},
"required": ["transaction_id"]
}
}
},
{
"type": "function",
"function": {
"name": "retrieve_payment_date",
"description": "Ruft das Datum ab, an dem eine Zahlung getätigt wurde "
"basierend auf der Transaktions-ID.",
"parameters": {
"type": "object",
"properties": {
"transaction_id": {
"type": "string",
"description": "Die eindeutige Transaktions-ID (z. B. T1001)"
}
},
"required": ["transaction_id"]
}
}
}
]
Beide Funktionen erwarten exakt denselben Parameter, transaction_id, doch das Modell muss zwischen ihnen wählen. Diese Entscheidung beruht ausschließlich auf der Funktionsbeschreibung. „Ist diese Zahlung durchgegangen?” passt zu retrieve_payment_status; „Wann war das?” passt zu retrieve_payment_date. Hätten Sie zwei vage, austauschbare Beschreibungen verfasst, hätte das Modell es halb der Zeit falsch gemacht – und Sie würden das Modell beschuldigen, obwohl die Schuld beim Schema liegt.
Zwingende vs. optionale Parameter
Die Unterscheidung zwischen zwingenden und optionalen Parametern bestimmt, was das Modell weglassen darf.
{
"type": "function",
"function": {
"name": "search_transactions",
"description": "Durchsucht Transaktionen basierend auf verschiedenen Kriterien",
"parameters": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": ["bezahlt", "ausstehend", "fehlgeschlagen"],
"description": "Nach Zahlungstatus filtern"
},
"date_from": {
"type": "string",
"description": "Startdatum im Format YYYY-MM-DD"
},
"date_to": {
"type": "string",
"description": "Enddatum im Format YYYY-MM-DD"
},
"min_amount": {
"type": "number",
"description": "Mindestbetrag in Euro"
}
},
"required": ["status"]
}
}
}
Hier ist nur status zwingend; die anderen Parameter werden nur hinzugefügt, wenn der Nutzer sie erwähnt. Vergleichen Sie zwei Formulierungen. Bei „Zeige mir fehlgeschlagene Zahlungen” generiert das Modell einfach {"status": "fehlgeschlagen"}. Bei „Zeige mir fehlgeschlagene Zahlungen aus März 2026” fügt es date_from und date_to von sich aus hinzu. Würden Sie diese Daten als zwingend deklarieren, würde die erste Abfrage brechen, oder schlimmer noch, das Modell würde versuchen, einen Datumsbereich zu erfinden.
Best Practices für Beschreibungen
Die Qualität der Beschreibung wirkt sich direkt auf die Modellgenauigkeit aus. Die untenstehenden Gegenbeispiele sind lehrreicher als jede abstrakte Regel.
# Schlecht — zu vage
{"description": "Ruft Daten ab"}
# Gut — präzise und kontextbezogen
{"description": "Ruft den Status einer Zahlung (bezahlt, ausstehend, fehlgeschlagen) "
"basierend auf der eindeutigen Transaktions-ID ab"}
# Schlecht — keine Beschreibung für den Parameter
{"transaction_id": {"type": "string"}}
# Gut — Beschreibung mit Beispiel
{"transaction_id": {
"type": "string",
"description": "Eindeutige Transaktions-ID (Format: T gefolgt von 4 Ziffern, z. B. T1001)"
}}
Eine gute Beschreibung formuliert in einem Satz, was die Funktion tut, gibt das erwartete Format für jeden Parameter an und liefert ein Beispiel, wann dieses Format nicht offensichtlich ist – T1001 ist besser als „Transaktions-ID”. Wenn mögliche Werte begrenzt sind, beschreiben Sie diese nicht in Prosa: deklarieren Sie sie mit enum. Das ist der einzige Weg, sie verbindlich zu machen.
Kernaussagen
- JSON Schema ist der Vertrag zwischen Ihrem Code und dem Modell – es beschreibt Ihre Funktionen, ohne den Code preiszugeben
- Jedes Tool hat einen
name, einedescriptionund typisierteparameters - Unterstützte Typen umfassen
string,integer,number,boolean,arrayundobject - Die
required-Liste unterscheidet zwingende von optionalen Parametern - Präzise Beschreibungen mit Beispielen verbessern die Modellgenauigkeit erheblich