Définir des fonctions en Python
Na ovoj stranici
De la théorie au code
Tu maîtrises maintenant le processus en cinq étapes et la structure du schéma JSON. Il est temps d’écrire du vrai code Python. Dans cette leçon, tu vas créer des fonctions, rédiger leurs spécifications et tout préparer pour l’API Mistral : tout ce qui doit exister avant d’effectuer le premier appel réseau.
Installer le SDK Mistral
Commence par installer le paquet officiel :
pip install mistralai
Configure ensuite ta clé API. Les bonnes pratiques imposent de ne jamais la coder en dur dans tes fichiers sources. Lis-la plutôt depuis une variable d’environnement afin de pouvoir committer ton code en toute sécurité dans le contrôle de version.
export MISTRAL_API_KEY="your-api-key"
import os
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
Créer des fonctions Python
Examinons un exemple concret : un système de suivi des paiements adossé à un DataFrame Pandas. C’est un cas classique de la documentation Mistral, qui illustre parfaitement le concept ; ici, le DataFrame joue le rôle qu’occuperait une base de données en production.
import pandas as pd
import json
# Payment data
data = {
"transaction_id": ["T1001", "T1002", "T1003", "T1004", "T1005"],
"customer_id": ["C001", "C002", "C003", "C002", "C001"],
"payment_amount": [125.50, 89.99, 350.00, 45.00, 210.75],
"payment_date": ["2026-03-15", "2026-03-16", "2026-03-17", "2026-03-17", "2026-03-18"],
"payment_status": ["paid", "paid", "pending", "paid", "failed"]
}
df = pd.DataFrame(data)
Vient ensuite le code qui accède réellement à ces données. Ce sont des fonctions Python standards ; rien dans leur implémentation n’indique qu’un LLM les pilotera.
def retrieve_payment_status(df: pd.DataFrame, transaction_id: str) -> str:
"""Retrieves the status of a payment by its ID."""
if transaction_id in df["transaction_id"].values:
status = df[df["transaction_id"] == transaction_id]["payment_status"].values[0]
return json.dumps({"status": status})
return json.dumps({"error": f"Transaction {transaction_id} not found"})
def retrieve_payment_date(df: pd.DataFrame, transaction_id: str) -> str:
"""Retrieves the date of a payment by its ID."""
if transaction_id in df["transaction_id"].values:
date = df[df["transaction_id"] == transaction_id]["payment_date"].values[0]
return json.dumps({"date": date})
return json.dumps({"error": f"Transaction {transaction_id} not found"})
Deux détails d’implémentation méritent ton attention. Premièrement, ces fonctions retournent toujours une chaîne JSON, jamais un objet Python brut. C’est le format attendu par le modèle comme résultat d’outil, donc json.dumps() est incontournable. Deuxièmement, elles gèrent explicitement le cas où une transaction est introuvable au lieu de lever une exception. Cette erreur, formatée en JSON, revient au modèle comme n’importe quel autre résultat, lui permettant d’informer poliment l’utilisateur que la transaction T9999 n’existe pas. Tu verras plus loin dans le cours pourquoi ce réflexe est essentiel.
Rédiger les spécifications JSON
Chaque fonction nécessite une spécification pour que le modèle puisse la comprendre. Ici, tu appliques la structure de la leçon précédente aux deux fonctions ci-dessus. Note la correspondance stricte entre les champs name et les noms réels des fonctions Python.
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": "Unique transaction identifier (e.g., T1001)"
}
},
"required": ["transaction_id"]
}
}
},
{
"type": "function",
"function": {
"name": "retrieve_payment_date",
"description": "Retrieves the date a payment was made "
"based on the transaction ID.",
"parameters": {
"type": "object",
"properties": {
"transaction_id": {
"type": "string",
"description": "Unique transaction identifier (e.g., T1001)"
}
},
"required": ["transaction_id"]
}
}
}
]
Organiser les fonctions dans un dictionnaire
Le modèle renvoie un nom de fonction sous forme de chaîne. Tu dois pouvoir mapper cette chaîne vers l’objet appelable correspondant sans recourir à eval ni à une cascade d’instructions if. Un dictionnaire de répartition résout ce problème en trois lignes.
from functools import partial
# Bind the DataFrame to each function
available_functions = {
"retrieve_payment_status": partial(retrieve_payment_status, df),
"retrieve_payment_date": partial(retrieve_payment_date, df),
}
functools.partial répond à une difficulté concrète et récurrente. Tes fonctions attendent deux arguments — le DataFrame et l’ID — mais le modèle n’en fournit qu’un. Le modèle ne connaît rien de df, et c’est tant mieux. partial pré-remplit ce premier paramètre une fois pour toutes. Ce même mécanisme s’applique aux connexions de base de données, aux clients HTTP ou aux jetons d’authentification. L’invocation dynamique devient alors triviale.
function_name = "retrieve_payment_status"
function_params = {"transaction_id": "T1001"}
result = available_functions[function_name](**function_params)
# → '{"status": "paid"}'
L’option tool_choice
Lors de l’envoi de ces outils à l’API, le paramètre tool_choice décide du degré de liberté accordé au modèle. Trois valeurs sont possibles.
# The model decides whether to use a tool or respond directly (default)
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
tools=tools,
tool_choice="auto"
)
# Force the model to use a tool
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
tools=tools,
tool_choice="any"
)
# Prevent the model from using tools
response = client.chat.complete(
model="mistral-large-latest",
messages=messages,
tools=tools,
tool_choice="none"
)
Le mode "auto" est le plus courant en production, et pour cause : un assistant de suivi des paiements doit pouvoir dire „bonjour“ sans déclencher une requête en base de données. Le modèle répond directement aux questions générales et n’utilise les fonctions que lorsque c’est pertinent. Une leçon entière plus loin dans le cours couvre les cas d’usage spécifiques de any et none.
Ključne točke
- Les fonctions doivent retourner des chaînes JSON, jamais d’objets Python bruts
- Utilise un dictionnaire de répartition pour mapper les noms de fonctions à leurs implémentations
functools.partialest idéal pour pré-remplir des paramètres comme les connexions DB ou les DataFramestool_choicecontrôle si le modèle peut ou doit utiliser des fonctions (auto,any,none)- Gère toujours les cas d’erreur dans tes fonctions (paramètres invalides, données manquantes)