DSPy : programmer et optimiser ses prompts en Python

Informations vérifiées le 15 octobre 2026 à partir de la documentation actuelle de DSPy, de PyPI et des tarifs des modèles Google. PyPI indique DSPy 3.4.1, publié le 12 octobre 2026, et une compatibilité avec Python à partir de 3.10 et avant 3.16. Le paquet à installer est dspy. Métadonnées du paquet sur PyPI.

Qu’est-ce que DSPy et que signifie « compiler » ?

DSPy est un framework Python open source qui permet de définir des tâches confiées à un modèle de langage sous forme de programmes, puis d’en améliorer les prompts ou, avec certains optimiseurs, les poids du modèle. Son intérêt : rendre l’amélioration reproductible selon vos propres critères de réussite. Rien ne garantit pour autant que le premier prompt généré fera mieux qu’un prompt soigneusement rédigé à la main. Présentation de DSPy.

Imaginez une répétition avant un spectacle. La signature donne les consignes, le module détermine la façon de jouer et la métrique fixe le critère d’appréciation. L’optimiseur modifie un élément, observe le résultat et conserve les changements utiles. Sans critère d’appréciation, on peut répéter indéfiniment de différentes façons sans jamais savoir si l’on progresse.

Les signatures définissent la tâche

Une signature déclare les entrées, les sorties et les instructions de la tâche. "ticket -> category" signifie qu’un ticket entre dans le programme et qu’une catégorie en sort. Une signature définie sous forme de classe peut ajouter des champs typés et une docstring qui explique la tâche. Le choix des champs reste déterminant : aucun optimiseur ne peut compenser une définition métier ambiguë de ce qui est « urgent ». Documentation des signatures.

Les modules DSPy déterminent le déroulement

Un module met en œuvre une stratégie pour accomplir la tâche. dspy.Predict est la brique de prédiction de base. dspy.ChainOfThought ajoute un champ de raisonnement avant la réponse. dspy.ReAct permet de créer une boucle qui associe raisonnement et utilisation d’outils. Lorsque le recours au modèle en une seule étape ne suffit pas, vous pouvez composer plusieurs modules en Python. Documentation des modules.

Pour orienter des tickets d’assistance, commencez par Predict. Ajouter une boucle d’utilisation d’outils pour classer un court message multiplie les éléments à gérer avant même d’en avoir démontré l’utilité.

La compilation est une procédure d’optimisation

Un optimiseur modifie certaines parties d’un programme à partir d’exemples et d’une métrique. Dans le cas de l’optimisation de prompts, .compile() renvoie un programme doté d’instructions ou de démonstrations révisées, c’est-à-dire d’exemples intégrés au prompt. Cette opération ne transforme pas l’application en exécutable natif et ne supprime pas les futurs appels au modèle. L’entraînement des poids relève d’un autre choix d’optimiseur. Guide de choix d’un optimiseur.

Tutoriel DSPy : l’exemple minimal de la documentation actuelle

Le programme de démarrage actuel génère un haïku. Ce petit exemple permet de découvrir l’interface sans base de données, sans outils et sans recherche d’optimisation.

Installez la version vérifiée dans votre environnement Python :

python -m pip install 'dspy[litellm]==3.4.1'

Renseignez une clé API Google Gemini valide dans la variable d’environnement GEMINI_API_KEY. Enregistrez le code suivant dans first_dspy.py, puis lancez python first_dspy.py :

import os
import dspy

lm = dspy.LM(
    "gemini/gemini-2.5-flash-lite",
    api_key=os.environ["GEMINI_API_KEY"],
    engine="litellm",
)
dspy.configure(lm=lm)

haiku_signature = "subject -> haiku"
haiku_generator = dspy.Predict(haiku_signature)
result = haiku_generator(subject="computer science")
print(result.haiku)

Les quatre dernières lignes constituent le premier programme de la documentation actuelle. La configuration suit le schéma de configuration des modèles de DSPy, en remplaçant le modèle par Google Gemini 2.5 Flash-Lite pour utiliser un seul modèle peu coûteux dans l’expérience ci-dessous. L’identifiant du fournisseur suit l’intégration Gemini de LiteLLM ; le choix explicite du backend est pris en charge par l’API LM de DSPy.

DSPy construit un prompt à partir de la signature, l’envoie au modèle configuré et extrait le champ haiku de la réponse. Il s’agit d’un exemple d’inférence, pas d’une exécution d’optimisation. Cet exemple ne revendique ni poème particulier ni gain de qualité.

Optimiser les prompts avec DSPy exige une métrique

Sans métrique, l’optimisation n’a pas de sens. Une métrique est une fonction qui transforme une prédiction en score. Pour orienter des tickets, elle peut comparer la catégorie prédite à une étiquette validée par une personne. Pour une réponse générée, vérifier la justesse peut nécessiter une grille d’évaluation ou un contrôle exécutable. L’interface de métriques de DSPy accepte votre fonction de notation ; le framework ne décide pas de ce que votre entreprise doit valoriser. Métriques et évaluation.

C’est pourquoi un petit jeu d’évaluation annoté compte autant. Si vous en avez assez de remplacer « soyez concis » par « répondez brièvement », collectez plutôt de vrais échecs : une demande de remboursement envoyée au support technique, un problème de connexion pris pour une question de facturation ou un message contenant deux demandes. Annotez le résultat attendu avant de regarder la réponse produite par un nouveau prompt.

Pour un premier pilote, partez de 60 exemples distincts, répartis délibérément en 20 exemples d’entraînement, 20 de validation et 20 de test final. Ces volumes sont une proposition de protocole, pas des exigences de DSPy ni une preuve de fiabilité en production.

• Les exemples d’entraînement fournissent la matière dont l’optimiseur peut tirer parti.
• Les exemples de validation servent à comparer les versions et à orienter les choix pendant le développement.
• Les exemples de test final restent à l’écart jusqu’à ce que la version candidate et les règles d’évaluation soient figées.

Regroupez dans un même lot les tickets liés à un même client ou à un même incident. Sinon, des exemples presque identiques risquent de donner l’impression que le prompt optimisé généralise mieux qu’en réalité. Incluez les échecs rares qui comptent, au lieu de remplir chaque lot de cas faciles.

L’affirmation « sans métrique » appelle une nuance précise. Un programme DSPy non optimisé peut fonctionner sans métrique, et LabeledFewShot peut lui joindre des exemples sans les noter. Il s’agit alors de configuration, pas d’une preuve que le changement améliore la tâche. Toutes les tâches n’exigent pas non plus une réponse de référence rédigée à la main : un contrôle exécutable de la justesse peut fournir le signal nécessaire. Pour la classification métier, des étiquettes validées constituent généralement le point de départ le plus clair. Version de référence avec quelques exemples.

Les optimiseurs DSPy dans la documentation actuelle

Commencez par l’optimiseur le plus simple qui répond à un échec que vous savez décrire. Élargir la recherche n’est utile que si la métrique permet de départager les meilleurs candidats des moins bons.

L’index actuel de l’API des optimiseurs répertorie exactement les entrées suivantes : BetterTogether, BootstrapFewShot, BootstrapFewShotWithRandomSearch, BootstrapFinetune, BootstrapRS, COPRO, Ensemble, GEPA, InferRules, KNN, KNNFewShot, LabeledFewShot, MIPROv2 et SIMBA.

Ces entrées ne correspondent pas toutes à des algorithmes de recherche indépendants. BootstrapRS est un alias de BootstrapFewShotWithRandomSearch ; KNN est le composant de recherche d’exemples utilisé par KNNFewShot. Le guide de sélection actuel mentionne aussi AvatarOptimizer pour les programmes de type agent, bien qu’il ne figure pas dans cet index d’API. Détail de cette famille d’optimiseurs, guide de sélection.

MIPROv2 propose des instructions et utilise l’optimisation bayésienne, une méthode de recherche guidée par les scores précédents, pour explorer des combinaisons d’instructions et de démonstrations. SIMBA procède par mini-lots et propose des règles ou des démonstrations. Ce sont des approches distinctes, pas de simples variantes renommées de BootstrapFewShot. API MIPROv2, API SIMBA.

GEPA utilise un modèle de réflexion pour analyser les retours d’exécution et proposer des changements d’instructions. Un score accompagné d’une explication précise, par exemple « les demandes de remboursement relèvent de la facturation, même lorsqu’elles mentionnent une fonctionnalité défaillante », lui fournit un signal plus utile qu’un simple score d’échec. La documentation détaillée autorise les métriques purement numériques, tout en précisant qu’elles font perdre la richesse de ces retours. Fonctionnement de GEPA.

Fixer des limites au premier essai d’optimisation

Une petite expérience avec BootstrapFewShot est plus facile à budgéter qu’une recherche d’instructions sans limites précises. Le protocole suivant utilise un seul module Predict, une métrique déterministe sur les étiquettes et le même modèle pour produire les démonstrations et les prédictions.

DSPy BootstrapFewShot : un essai volontairement limité

Préparez train.jsonl, validation.jsonl et test.jsonl, contenant chacun 20 tickets distincts annotés par une personne. Chaque ligne est un objet JSON avec les champs text et label ; les étiquettes autorisées sont billing, technical, account et other. Une demande de modification de l’adresse de facturation pourrait, par exemple, recevoir l’étiquette billing. Utilisez vos propres exemples, pas le haïku généré plus haut.

Enregistrez ce script distinct sous le nom optimize_tickets.py, puis exécutez-le après avoir configuré la même clé API :

import json
import os
from typing import Literal
import dspy

lm = dspy.LM(
    "gemini/gemini-2.5-flash-lite",
    api_key=os.environ["GEMINI_API_KEY"],
    engine="litellm",
    cache=False,
)
dspy.configure(lm=lm)

class RouteTicket(dspy.Signature):
    """Choose the support queue responsible for the ticket's main request."""
    text: str = dspy.InputField()
    label: Literal["billing", "technical", "account", "other"] = (
        dspy.OutputField()
    )

def load_examples(path):
    with open(path, encoding="utf-8") as source:
        rows = [json.loads(line) for line in source if line.strip()]
    assert len(rows) == 20
    return [dspy.Example(**row).with_inputs("text") for row in rows]

train = load_examples("train.jsonl")
validation = load_examples("validation.jsonl")
test = load_examples("test.jsonl")
assert len({e.text for e in train + validation + test}) == 60

def correct_label(example, prediction, trace=None):
    return prediction.label == example.label

program = dspy.Predict(RouteTicket)
evaluate = dspy.Evaluate(
    devset=validation, metric=correct_label, num_threads=1
)
print("Baseline validation:", evaluate(program).score)

optimizer = dspy.BootstrapFewShot(
    metric=correct_label,
    max_bootstrapped_demos=4,
    max_labeled_demos=0,
    max_rounds=1,
)
optimized = optimizer.compile(program, trainset=train)
print("Optimized validation:", evaluate(optimized).score)

# Freeze this candidate before opening the final test results.
final_test = dspy.Evaluate(
    devset=test, metric=correct_label, num_threads=1
)
print("Baseline final test:", final_test(program).score)
print("Optimized final test:", final_test(optimized).score)
optimized.save("candidate_ticket_router.json")

Ce code adapte le constructeur documenté de BootstrapFewShot et l’interface d’évaluation ; il ne prétend pas fournir un résultat de benchmark. Il demande jusqu’à quatre démonstrations réussies, autorise une tentative de bootstrap par exemple d’entraînement et n’ajoute aucune démonstration annotée brute. Le fichier enregistré est une version candidate à examiner, pas une mise en production automatique.

Voici le décompte pour ce protocole :

• Version de référence sur le jeu de validation : 20 exécutions du programme.
• Bootstrap sur le jeu d’entraînement : jusqu’à 20 exécutions du modèle enseignant, éventuellement moins si suffisamment de démonstrations sont validées.
• Programme optimisé sur le jeu de validation : 20 exécutions du programme.
• Les deux versions sur le jeu de test final : 40 exécutions du programme.

Cela représente jusqu’à 100 exécutions à une seule étape, évaluation comprise ; la compilation seule en représente au maximum 20. Avec une requête réussie au modèle par exécution, sans nouvelle tentative ni mécanisme de repli en cas d’échec du parsing, on obtient au plus 100 appels au modèle chargé de la tâche. Le test de fonctionnement avec le haïku, effectué plus haut, est compté à part. Un LLM utilisé comme juge, une boucle d’agent, de nouvelles tentatives ou un autre essai d’optimisation modifient ce total.

Au tarif catalogue payant Standard de Google pour le texte avec Gemini 2.5 Flash-Lite, soit $0.10 par million de tokens en entrée et $0.40 par million de tokens en sortie, 100 appels consommant en moyenne, par hypothèse, 1,000 tokens en entrée et 100 en sortie coûtent $0.014 : 100,000 ÷ 1,000,000 × $0.10 + 10,000 ÷ 1,000,000 × $0.40. Tarifs Google.

Ce calcul porte uniquement sur le modèle : ce n’est ni une facture mesurée ni un plafond de dépense. L’hypothèse sur les entrées doit inclure la mise en forme de DSPy et les démonstrations jointes. Des tickets plus longs, des sorties plus volumineuses et du raisonnement facturable augmentent le montant. L’estimation ne comprend aucune remise liée au traitement par lots ou au cache. L’usage réel enregistré par votre fournisseur fait foi pour la facturation.

DSPy, prompts rédigés à la main ou fine-tuning : que choisir ?

Utilisez DSPy si vous avez besoin d’une méthode reproductible pour améliorer un programme dont les résultats sont mesurables. Conservez un prompt rédigé à la main s’il répond déjà aux exigences de la tâche. Envisagez le fine-tuning lorsque des éléments concrets montrent que modifier les prompts ne suffit pas et que l’entraînement d’un modèle est compatible avec vos contraintes de déploiement.

Ces techniques sont compatibles. DSPy comprend BootstrapFinetune, et BetterTogether combine optimisation des prompts et des poids. La différence pratique tient à ce que vous modifiez et entretenez, pas au nom qui paraît le plus sophistiqué. Optimisation des prompts et des poids.

Le choix se joue sur le terrain : si chaque changement de modèle ou nouveau cas d’échec oblige un ingénieur à retoucher manuellement plusieurs prompts, une boucle d’optimisation fondée sur un score devient intéressante. Si un prompt court satisfait déjà vos critères d’acceptation, rien ne démontre l’intérêt de le remplacer par un framework.

Qui devrait se lancer, attendre ou passer son tour ?

Les ingénieurs devraient se lancer lorsqu’ils disposent d’une tâche récurrente, d’une version de référence fonctionnelle et d’échecs représentatifs. L’orientation des tickets et l’extraction structurée sont de bons points de départ, car leurs sorties attendues peuvent être vérifiées. Optimisez un petit composant avant d’étendre le système. La limite de DSPy reste la qualité de l’objectif : il peut sélectionner un candidat mieux noté alors que votre métrique récompense le mauvais comportement.

Les responsables opérationnels doivent prendre en charge les étiquettes et la hiérarchisation des erreurs. Un responsable du support peut accorder bien plus d’importance à un incident d’accès au compte mal orienté qu’à une simple question de facturation. Si le score traite les deux de la même façon, l’optimisation risque de contredire ses priorités. Tranchez cette règle métier avant de demander à un ingénieur d’améliorer le score.

Les acheteurs doivent exiger des résultats sur des exemples jamais vus pendant le développement. Demandez quelle version de référence a servi à la comparaison, quels cas ont régressé, ce que contient désormais le programme utilisé en production et si le workflow respecte toujours ses exigences de latence. Le nom d’un optimiseur ne suffit pas à valider une solution. Le test de Promptfoo publié sur le site complète cette lecture pour les équipes qui organisent leur travail d’évaluation.

Une équipe métier devrait écarter DSPy pour de la rédaction occasionnelle, une recherche ponctuelle ou un workflow qui change avant de pouvoir réunir assez d’exemples. Même conseil si personne ne peut maintenir le code Python ou si l’équipe ne parvient pas à s’accorder sur une règle de notation. Un bon prompt, une checklist et une validation humaine peuvent former un dispositif plus proportionné. Attendez si votre vrai problème est l’absence de données sources ou un processus mal défini : optimiser la formulation ne résoudra ni l’un ni l’autre.

Quelles promesses autour de DSPy faut-il relativiser ?

« Programmer plutôt que rédiger des prompts » ne fait pas disparaître les prompts. DSPy les crée et les gère ; les humains continuent de définir la tâche, d’analyser les échecs et de décider si le résultat est acceptable.

« Compiler » ne signifie pas que le modèle a appris de façon permanente. Avec les optimiseurs de prompts, les éléments appris sont des instructions ou des démonstrations. Il faut toujours appeler un modèle lors de l’inférence, et les démonstrations occupent de la place dans le prompt. Vous pouvez enregistrer l’état appris en JSON et le charger dans un nouveau programme. Enregistrement et chargement.

« Optimisation automatique » ne signifie pas amélioration garantie. La comparaison utile porte sur votre approche actuelle, face à des entrées jamais utilisées pendant le développement. Un meilleur score de développement peut refléter du surapprentissage, un juge trop indulgent ou un jeu de données qui omet les échecs coûteux.

Enfin, les appels à la métrique ne sont pas les appels au fournisseur. Dans GEPA, max_metric_calls limite le nombre d’appels à la fonction de notation ; la réflexion sollicite elle aussi un modèle, et le programme évalué peut lui-même effectuer plusieurs requêtes. Les réglages auto ne correspondent donc pas à un montant de facture universel. Réglages du budget de GEPA.

Les questions techniques fréquentes sur DSPy

Par quoi commencer concrètement ?

Dès lundi, choisissez un échec récurrent d’orientation de tickets ou d’extraction, puis demandez au responsable du processus d’annoter des exemples représentatifs. Figez une version de référence, définissez une règle de notation et menez une expérience aux limites précises. Examinez les réponses qui ont changé avant de valider la version candidate. Si vous ne savez pas définir le score, la prochaine étape utile consiste à vous accorder sur la règle métier.

Recevez des décryptages pratiques sur l’ingénierie de l’IA dans la newsletter.