Hoppa till huvudinnehåll
Svenska— Välj ett språk
Meny

Définir des fonctions avec JSON Schema

Lektion 3 av 14 Uppdaterad 29 juli 2026 Utvecklare
På denna sida
  1. Le contrat entre ton code et le modèle
  2. Anatomie d’une spécification d’outil
  3. Types JSON Schema pris en charge
  4. Exemple complet : deux fonctions complémentaires
  5. Paramètres obligatoires vs optionnels
  6. Bonnes pratiques pour les descriptions
  7. Viktiga punkter

Le contrat entre ton code et le modèle

Pour que le modèle Mistral appelle tes fonctions, il doit savoir ce qui existe et comment l’utiliser. C’est le rôle du JSON Schema : un format standardisé qui décrit chaque fonction—son nom, son action, les paramètres attendus et ceux qui sont obligatoires.

Garde une chose en tête tout au long de cette leçon : le modèle ne voit jamais ton code Python. Il ne voit que cette spécification. Si ta fonction gère les identifiants en minuscules sans problème mais que le schéma ne le précise pas, le modèle ignorera cette capacité. Plus ton schéma est précis et bien documenté, plus les arguments générés seront exacts.

Anatomie d’une spécification d’outil

Chaque outil envoyé à l’API Mistral suit la même structure :

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"]
        }
    }
}
ChampRôle
typeToujours "function" (d’autres types pourraient exister à l’avenir)
function.nameLe nom exact de ta fonction Python—c’est ce que le modèle renvoie dans tool_calls
function.descriptionUne phrase claire qui aide le modèle à choisir la bonne fonction
function.parametersUn objet JSON Schema décrivant les paramètres attendus
requiredLa liste des paramètres obligatoires

Types JSON Schema pris en charge

Le vocabulaire de types disponible pour décrire les paramètres est volontairement restreint, et chaque type guide le modèle différemment. Un enum, en particulier, fait plus que documenter : il ferme la porte aux valeurs inventées.

# String — texte libre ou contraint
{"type": "string", "description": "Transaction ID"}

# String avec enum — valeurs limitées
{"type": "string", "enum": ["asc", "desc"], "description": "Sort order"}

# Integer — nombre entier
{"type": "integer", "description": "Number of results to return"}

# Number — nombre décimal
{"type": "number", "description": "Amount in euros"}

# Boolean — vrai/faux
{"type": "boolean", "description": "Include canceled transactions"}

# Array — liste de valeurs
{
    "type": "array",
    "items": {"type": "string"},
    "description": "List of transaction IDs"
}

# Object — objet imbriqué
{
    "type": "object",
    "properties": {
        "city": {"type": "string"},
        "country": {"type": "string"}
    },
    "description": "Shipping address"
}

Distingue clairement integer et number : un montant en euros comme 125,50 nécessite un number, tandis qu’un nombre de résultats à retourner est un integer. Déclarer un montant comme integer forcera le modèle à l’arrondir.

Exemple complet : deux fonctions complémentaires

Voici un exemple réaliste avec deux fonctions liées aux paiements, inspiré de la documentation officielle de Mistral :

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

Les deux fonctions attendent exactement le même paramètre, transaction_id, pourtant le modèle doit choisir entre elles. Ce choix repose entièrement sur la description de la fonction. « Ce paiement est-il passé ? » correspond à retrieve_payment_status ; « Quand a-t-il eu lieu ? » correspond à retrieve_payment_date. Si tu avais rédigé deux descriptions vagues et interchangeables, le modèle se tromperait une fois sur deux—et tu blâmerais le modèle alors que la faute incombe au schéma.

Paramètres obligatoires vs optionnels

La distinction entre paramètres obligatoires et optionnels détermine ce que le modèle est autorisé à omettre.

{
    "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": "Filter by payment status"
                },
                "date_from": {
                    "type": "string",
                    "description": "Start date in YYYY-MM-DD format"
                },
                "date_to": {
                    "type": "string",
                    "description": "End date in YYYY-MM-DD format"
                },
                "min_amount": {
                    "type": "number",
                    "description": "Minimum amount in euros"
                }
            },
            "required": ["status"]
        }
    }
}

Ici, seul status est obligatoire ; les autres paramètres sont inclus uniquement si l’utilisateur les mentionne. Compare deux formulations. Pour « Affiche-moi les paiements échoués », le modèle génère simplement {"status": "failed"}. Pour « Affiche-moi les paiements échoués depuis mars 2026 », il ajoute date_from et date_to de lui-même. Rendre ces dates obligatoires aurait cassé la première requête, ou pire, poussé le modèle à inventer une plage de dates.

Bonnes pratiques pour les descriptions

La qualité des descriptions impacte directement la précision du modèle. Les contre-exemples ci-dessous sont plus instructifs que n’importe quelle règle abstraite.

# Mauvais — trop vague
{"description": "Retrieves data"}

# Bon — précis et contextuel
{"description": "Retrieves the status of a payment (paid, pending, failed) "
                "based on the unique transaction ID"}

# Mauvais — pas de description pour le paramètre
{"transaction_id": {"type": "string"}}

# Bon — description avec exemple
{"transaction_id": {
    "type": "string",
    "description": "Unique transaction ID (format: T followed by 4 digits, e.g., T1001)"
}}

Une bonne description énonce en une phrase ce que fait la fonction, spécifie le format attendu pour chaque paramètre et fournit un exemple chaque fois que ce format n’est pas évident—T1001 vaut mieux que « identifiant de transaction ». Lorsque les valeurs possibles sont limitées, ne les décris pas en prose : déclare-les avec enum. C’est le seul moyen de les rendre contraignantes.

Viktiga punkter

  • Le JSON Schema est le contrat entre ton code et le modèle—il décrit tes fonctions sans exposer le code
  • Chaque outil possède un name, une description et des parameters typés
  • Les types pris en charge incluent string, integer, number, boolean, array et object
  • La liste required distingue les paramètres obligatoires des optionnels
  • Des descriptions précises avec des exemples améliorent considérablement la précision du modèle