Programmer en IA

En bref

Ce guide répond à deux questions qui reviennent sans cesse. Que faut-il installer aujourd'hui pour faire de l'intelligence artificielle en Python ? Et comment livrer ensuite ce qu'on a construit ? Nous l'écrivons depuis décembre 2018 et nous le tenons à jour. Il sert tous les jours au laboratoire de mathématiques appliquées MAP5 et dans plusieurs entreprises de tailles différentes, publiques et privées, françaises et internationales.

Il s'adresse à plusieurs lecteurs, qui n'ont pas besoin des mêmes sections.

• Vous voulez une machine prête ce soir. Lisez la section 1, puis la recette de votre système en section 9.
• Vous hésitez entre un Mac, une carte NVIDIA ou le cloud. Le tableau de la section 3 et la section 5 vous orientent.
• Vous cherchez les bonnes bibliothèques. La section 4 les range par usage.
• Vous avez un outil qui marche et vous voulez le livrer à un collègue, à un programme ou à un agent d'IA. Les sections 7 et 8 sont pour vous.
• Vous avez un modèle en production à entretenir. La section 10 est la partie avancée.

1. Ce que nous installons aujourd'hui

Cette section sert à qui veut un environnement qui marche, tout de suite, sans lire le reste. Un environnement est un dossier isolé qui contient une version de Python et ses bibliothèques. Chaque projet a le sien : installer un paquet pour l'un ne casse jamais l'autre.

Il vous faut d'abord Miniconda, la version allégée d'Anaconda. Elle fournit la commande conda, qui crée ces environnements. La ligne d'installation dépend de votre système : prenez celle de votre machine en section 9, puis revenez. Si conda --version répond déjà, passez à la suite.

Le projet a ensuite besoin de trois petits fichiers. Le premier, environment.yaml, ne fait presque rien : il fixe la version de Python et passe la main au deuxième.

name: env4ml
channels:
  - conda-forge
dependencies:
  - python=3.13
  - pip
  - pip:
      - -r requirements.txt

Le deuxième, requirements.txt, est la liste complète des bibliothèques. C'est la seule.

numpy
pandas
scikit-learn
matplotlib
seaborn
jupyterlab
torch
torchvision
torchaudio

Le troisième, requirements-dev.txt, ajoute ce qui sert aux tests et ne part jamais chez l'utilisateur. Sa première ligne reprend la liste principale.

-r requirements.txt
pytest
ruff

Deux commandes créent alors l'environnement et l'activent :

conda env create -f environment.yaml
conda activate env4ml

Vous avez l'apprentissage automatique classique (scikit-learn), les outils de données (pandas, matplotlib, seaborn), les notebooks (JupyterLab) et l'apprentissage profond (PyTorch). Sur un Mac récent, PyTorch se sert de la puce graphique d'Apple sans réglage. Sur une carte NVIDIA, un détour est nécessaire, décrit en section 9.

Si vous ne voulez rien installer du tout, Google Colab ouvre un notebook dans votre navigateur, sur les machines de Google, carte graphique comprise.

Avant d'installer : quatre conseils

• Jamais d'installation à l'échelle du système. Un environnement par projet vous épargne les conflits de versions qui coûtent une journée à démêler.
• Pas de course au Python le plus récent. La version que fixe environment.yaml est celle pour laquelle toutes les bibliothèques de la section 4 publient leurs paquets compilés. Une version plus neuve attend souvent quelques mois que tout le monde suive.
• La carte graphique vient en dernier. C'est elle qui fait le plus mal à installer. Si le processeur suffit, livrez sur processeur, puis ajoutez la carte.
• Pour enseigner, la reproductibilité passe avant la vitesse. Une configuration un peu lente que toute la classe installe vaut mieux qu'une configuration rapide qui casse chez un tiers des étudiants.

2. Une seule liste, quatre façons de la lire

Cette section sert à qui maintient un projet dans la durée, seul ou en équipe. Elle explique pourquoi les trois fichiers de la section 1 sont découpés ainsi. Elle montre aussi comment uv et Docker s'y branchent sans rien dupliquer.

Le principe est simple : la liste des bibliothèques n'existe qu'à un seul endroit, requirements.txt. Deux listes finissent toujours par diverger. Le jour où un collègue installe depuis l'une et vous depuis l'autre, le même code donne deux résultats. Personne ne sait pourquoi. Le commentaire que nous mettons en tête de chaque environment.yaml le dit en une ligne : ce fichier passe la main à requirements.txt, donc il ne se désynchronise jamais.

Quatre outils lisent ensuite cette même liste.

• conda, par environment.yaml, pour créer l'environnement et choisir la version de Python.
• pip, directement : pip install -r requirements.txt.
• uv, un installeur écrit en Rust par Astral, qui remplace pip et va beaucoup plus vite. Dans un environnement conda activé, on l'installe une fois avec pip install uv, puis uv pip install -r requirements.txt fait le même travail que pip. La liste reste la même.
• Docker, pour reproduire l'environnement sur une autre machine.

Docker et docker compose

Docker sert à qui doit faire tourner le projet ailleurs que sur son portable : un serveur, une machine de calcul, l'ordinateur d'un client. Un conteneur est une petite machine Linux complète, décrite par un fichier texte, le Dockerfile. Il démarre à l'identique partout où Docker est installé.

Le Dockerfile lit le même requirements.txt. Il le copie et l'installe avant le reste du code : Docker garde chaque étape en cache, si bien qu'une modification du code ne relance pas l'installation des bibliothèques.

FROM python:3.13-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["python", "-m", "mon_projet"]

Un détail de taille, mesuré pendant notre essai. Sous Linux, le PyTorch par défaut embarque les bibliothèques de CUDA, même sans carte NVIDIA : notre image pesait 10,2 Go. Pour un serveur sans carte graphique, une option dans le Dockerfile seul va chercher le PyTorch pour processeur, et l'image descend à 2,2 Go. La liste, elle, ne change pas.

RUN pip install --no-cache-dir --extra-index-url https://download.pytorch.org/whl/cpu -r requirements.txt

docker compose décrit, dans un fichier docker-compose.yml, comment lancer un ou plusieurs conteneurs : le port ouvert, le dossier partagé avec la machine, le redémarrage automatique. Une commande suffit ensuite, docker compose up --build. Dans nos dépôts, compose lance l'interface HTTP du projet. L'accès pour les agents d'IA est monté sur la même application (voir la section 7).

services:
  mon-projet:
    build: .
    ports:
      - "8000:8000"
    volumes:
      - ./data:/data
    restart: unless-stopped

Deux limites à connaître avant de tout mettre en conteneur, parce qu'elles touchent la carte graphique.

• Sur un Mac, un conteneur n'atteint pas la puce graphique d'Apple. Docker y fait tourner une machine Linux virtuelle, qui ne voit que le processeur. Pour entraîner sur un Mac, restez dans l'environnement conda.
• Sur Linux, une carte NVIDIA demande le NVIDIA Container Toolkit, puis l'option --gpus all au lancement. Sans lui, le conteneur tourne sur processeur sans rien signaler.

3. Quelle configuration pour quelle situation

Cette section sert à qui ne se reconnaît pas dans le cas général de la section 1. Cherchez votre ligne et suivez-la.

4. Le socle Python pour l'apprentissage automatique

Cette section sert à qui choisit ses bibliothèques. Elle les range par usage et dit, pour chacune, quand la sortir.

En quelques décennies, le domaine est passé de Java à MATLAB, puis à Python. Les grandes entreprises du numérique s'y sont arrêtées, la recherche a suivi avec ses financements et ses outils. Nous conseillons Python pour cette raison : c'est là que paraissent les articles, les modèles et les bibliothèques.

Les boîtes à outils que nous conseillons

• Vision par ordinateur. Cinq usages, du pixel brut au service en ligne :
  • Vision classique : OpenCV. Traitement d'image, transformations géométriques, calibration de caméra, suivi d'objets. Pour tout ce qui ne demande pas d'apprentissage, c'est encore la bonne réponse.
  • Détection et segmentation : Detectron2, de Meta, quand vous voulez la main sur l'architecture. Pour aller plus vite, la lignée YOLO d'Ultralytics (pip install ultralytics) domine le prêt-à-l'emploi : détection, segmentation, pose, boîtes orientées. Licence AGPL-3.0, avec une licence commerciale pour un usage fermé.
  • Annotation : CVAT, sous licence MIT, est la référence libre pour étiqueter images et vidéos : classes, boîtes, segmentation, points clés, texte. Avec un agent de code à côté, vous montez une chaîne d'annotation sans écrire la plomberie vous-même.
  • Plateforme hébergée : Roboflow couvre toute la chaîne, entraîner, déployer, servir, avec Roboflow Universe comme dépôt public de modèles et de jeux de données.
  • Représentations sans étiquettes : DINOv3, de Meta, apprend d'excellentes représentations d'images sans annotation. À utiliser comme couche figée pour classer, chercher ou segmenter quand vous avez peu d'étiquettes.
• Apprentissage automatique classique. scikit-learn, la bibliothèque de référence pour classer, prédire un nombre, regrouper et choisir un modèle. Interface stable, réglages par défaut sensés, documentation remarquable. Commencez là, sauf si votre problème réclame vraiment l'apprentissage profond.
• Apprentissage profond. Nous commencerions aujourd'hui par PyTorch : c'est là que se fait la recherche et là que les architectures nouvelles arrivent en premier. TensorFlow garde son outillage de production et le déploiement sur mobile par LiteRT. Keras tourne désormais sur TensorFlow, JAX ou PyTorch. PyTorch Lightning vous débarrasse du code répétitif de la boucle d'entraînement.
• Langage et grands modèles. Cinq usages, du découpage en mots jusqu'à l'évaluation :
  • Traitement classique : spaCy découpe, reconnaît les entités et analyse la grammaire, à l'échelle industrielle. fastText, de Meta, classe du texte multilingue très vite et reste une référence difficile à battre pour son coût.
  • Transformeurs et embeddings : Hugging Face Transformers pour les modèles pré-entraînés, sentence-transformers pour transformer une phrase en vecteur et chercher par le sens.
  • Faire tourner un grand modèle chez soi : Ollama est le plus simple, un service local qui enveloppe llama.cpp. Pour servir en production, avec beaucoup d'utilisateurs à la fois, prenez vLLM. Pour le modèle lui-même, c'est la taille qui tranche : sur un portable ou un téléphone, la famille Qwen est la plus solide ; avec une vraie carte graphique, Gemma tient mieux.
  • Recherche documentaire : LangChain ou LlamaIndex assemblent recherches, consignes et appels d'outils. Pour l'index de vecteurs, FAISS, de Meta, est la référence. Quand la mémoire compte, turbovec comprime les vecteurs sur 2 ou 4 bits et range une dizaine de millions de vecteurs dans 4 Go, sans perdre grand-chose. C'est notre index préféré en local. Qdrant ou Chroma quand il vous faut un service à part.
  • Évaluer un grand modèle : DeepEval écrit des tests en forme d'assertions, avec un modèle comme juge. Ragas mesure ce qui est propre à la recherche documentaire : pertinence du contexte, fidélité, justesse de la réponse.
• Équité, explicabilité, causalité. À passer avant que le modèle parte, pas le jour où un régulateur pose la question :
  • Mesurer et corriger les biais : Fairlearn, de Microsoft.
  • Expliquer une prédiction : SHAP attribue à chaque variable sa part dans la décision. Shapash, de la MAIF, ajoute une couche lisible par le métier, avec des libellés clairs et des rapports exportables. Prenez-le quand l'explication s'adresse à quelqu'un qui n'est pas de l'équipe.
  • Et si on changeait l'entrée ? DiCE, de Microsoft, répond à « quel changement minimal ferait basculer cette prédiction ? » en proposant plusieurs réponses.
  • Attribution sur réseaux profonds : Captum, de Meta et PyTorch.
  • Causalité : PyWhy rassemble les outils libres. Sa bibliothèque centrale, DoWhy, répond à « est-ce que X cause Y ? » et non à « peut-on prédire Y à partir de X ? ». La différence se voit sur un exemple : les ventes de glaces prédisent les coups de soleil, sans les causer.
• Préparer des données en tableau. skrub, de l'équipe Probabl et de l'Inria autour de scikit-learn, transforme des tableaux sales en variables exploitables : jointures sur des noms mal orthographiés, catégories innombrables, plus une chaîne complète en un appel, tabular_pipeline().
• Modèles de fondation pour les tableaux. Des transformeurs pré-entraînés égalent ou battent désormais des arbres de décision bien réglés sur des tableaux de taille petite à moyenne, sans aucun entraînement sur vos données. Deux comptent : TabPFN, du laboratoire de Frank Hutter, puis TabICL, de l'équipe SODA de l'Inria. Tous deux lisent votre tableau d'entraînement comme une série d'exemples et prédisent les lignes de test en une seule passe. Essayez-en un avant de sortir une pile qu'il faut entraîner.
• Modèles pré-entraînés. Hugging Face : le dépôt de modèles et les bibliothèques transformers, diffusers et datasets. Un from_pretrained() d'une ligne y joue le rôle qu'avait le pip install.
• Tester une IA. Un chiffre de justesse sur un jeu de validation teste une chose. Ces outils testent le reste :
  • Analyser un modèle ou un agent : Giskard cherche en un appel ce qui cloche : robustesse, hallucination, injection de consigne, biais.
  • Attaquer son propre système : PyRIT, de Microsoft, automatise l'attaque d'une IA générative. garak, de NVIDIA, sonde les fuites de données et les contournements de garde-fous.
  • Valider les données : Great Expectations et Pandera vérifient les données avant qu'elles atteignent le modèle. On ne teste pas un modèle dont on ne sait pas auditer les entrées.
• Évaluer et comparer des modèles. skore, de Probabl, se pose sur scikit-learn et rend une évaluation qui prend parti, une comparaison de modèles et des diagnostics. À sortir dès que vous avez plus d'un modèle à départager.

AI Helpers : la plomberie que nous ne réécrivons plus

AI Helpers rassemble dix-sept bibliothèques Python libres, sous licence BSD-3-Clause, que Warith Harchaoui maintient avec Mohamed Chelali et Bachir Zerroug. Chacune couvre un coin précis de la chaîne IA et médias : charger et convertir du son, transcrire une voix, extraire des images d'une vidéo, télécharger un média, envoyer un fichier sur un serveur, convertir du Markdown en Word, choisir le grand modèle local qui tient dans votre mémoire, détecter un coude sur une courbe. Le local est le défaut : vos données ne quittent pas la machine, sauf pour les deux bibliothèques dont c'est le métier, le stockage S3 et le transfert SFTP.

Nous les citons ici surtout pour leur forme. Toutes suivent les mêmes conventions de dépôt. Ce sont ces conventions que décrivent les sections 7 et 8.

5. Carte graphique : NVIDIA CUDA ou Apple Silicon

Cette section sert à qui doit choisir une machine, ou comprendre pourquoi un entraînement est lent. Une carte graphique (GPU) fait des milliers de petits calculs en même temps, exactement ce que demande un réseau de neurones. Deux familles se partagent le travail. Elles ne servent pas aux mêmes choses.

NVIDIA CUDA

La configuration de référence pour entraîner sérieusement. CUDA est la couche logicielle de NVIDIA qui permet aux programmes de parler à ses cartes. Elle a la plus grande collection de modèles et d'outils. C'est aussi le seul chemin réaliste pour l'entraînement à grande échelle.

• Pour : l'apprentissage profond à grande échelle, les gros lots, l'inférence en production.
• Installation : la recette Ubuntu de la section 9, puis le sélecteur officiel de PyTorch.
• Cartes gratuites pour la recherche : le programme de dotation académique de NVIDIA.

Apple Silicon (série M)

Une option sérieuse pour travailler en local. La mémoire unifiée est partagée entre le processeur et la puce graphique. Avec le silence de la machine, elle rend agréables l'expérimentation, le prototypage et l'enseignement. Elle suffit à quantité de travaux de taille moyenne. Quand les modèles grossissent, CUDA reprend l'avantage.

• Pour : le développement local, le prototypage, l'enseignement.
• PyTorch par le moteur Metal Performance Shaders, appareil mps, sans rien installer de plus.
• MLX, développé par Apple, pour une recherche à la manière de NumPy sur ses propres puces.

La règle pratique : développez sur la machine que vous avez sous la main. Quand l'expérience déborde du portable, passez sur une machine CUDA, une carte louée dans le cloud ou une grappe de calcul. Installer une carte graphique coûte toujours du temps : déménagez quand le déménagement est rentable, pas avant.

6. Notebooks, éditeurs et agents de code

Cette section sert à qui se demande où écrire son code. Trois couches se touchent tous les jours : les notebooks pour explorer, les éditeurs pour le travail suivi, enfin les agents de code, qui se posent désormais par-dessus.

Les notebooks

Un notebook mélange du code, ses résultats et du texte dans un même document, cellule par cellule.

• JupyterLab : le notebook de référence dans le navigateur, pour explorer, montrer et enseigner. Il est déjà dans requirements.txt ; lancez jupyter lab.
• marimo : un notebook enregistré en simple fichier .py, donc lisible dans un historique Git. Ses cellules se recalculent d'elles-mêmes quand une valeur change en amont. Fini les séances où l'on cherche dans quel ordre Jupyter a bien pu exécuter les choses.
• Google Colab : un notebook qui tourne sur les machines de Google. Pour quelques heures de calcul, ou pour une classe où tout le monde part du même environnement.

Les éditeurs

VS Code reste le choix sûr au quotidien. Des dérivés tournés vers l'IA sont apparus depuis : Cursor, le premier du genre, puis Google Antigravity, pensé pour plusieurs agents qui travaillent en parallèle. L'équivalent libre est Cline, une extension de VS Code qui accepte n'importe quel fournisseur de modèles, Ollama local compris. Cette liste se renouvelle tous les deux ou trois mois : jugez sur pièce.

Les agents de code, une couche de plus

La programmation a toujours avancé par couches. Le code machine a cédé à l'assembleur, l'assembleur au C, le C à Python, JavaScript et Rust. Chaque couche a laissé le programmeur exprimer davantage son intention et confier davantage de mécanique à un outil, le compilateur. Les grands modèles de langage ajoutent la couche suivante : la langue naturelle devient la source ; le code devient ce que la machine en tire.

« Le langage de programmation le plus en vogue, c'est l'anglais. »

Andrej Karpathy, message public du 24 janvier 2023. Source.

C'est le point de vue de l'optimiste. Vue depuis l'autre extrémité de la pile, la même observation donne ceci, de la part du créateur de Linux :

« L'IA est un formidable outil nouveau, mais c'est un outil, et quand je vois des gens dire « Hé, 99 % de notre code est écrit par l'IA », ça me met vraiment en colère, parce que ces mêmes gens, je peux à peu près vous le garantir, ont 100 % de leur code écrit par des compilateurs. »

Linus Torvalds, discours d'ouverture de l'Open Source Summit North America, Minneapolis, mai 2026. Extrait vidéo.

Les deux ont raison en même temps. Karpathy décrit ce qui devient accessible : la plupart des gens obtiendront un programme utile en écrivant de l'anglais plutôt que du Python. Torvalds rappelle ce qui ne se délègue pas. Quelqu'un comprend ce que le compilateur, ou le modèle, a réellement produit. C'est encore lui qui saura le corriger, l'accélérer et le livrer. Un agent de code amplifie une intention ; il ne la fournit pas. Traitez-le comme le compilateur suivant : dites clairement ce que vous voulez, puis relisez d'un œil critique ce qui revient.

Les deux agents que nous employons le plus :

• Claude Code, l'agent en ligne de commande d'Anthropic. Il lit votre dépôt, lance des commandes, modifie des fichiers et suit les skills installées dans ~/.claude/skills/. Il excelle en relecture, en débogage de bout en bout et sur les modifications qui touchent plusieurs fichiers.
• OpenCode, un agent libre dans le terminal, qui pilote Claude, GPT ou des modèles locaux derrière la même interface. À choisir pour ne pas dépendre d'un seul fournisseur, ou pour garder un code sensible sur un modèle local.

Les deux lisent le même format de skills, décrit en section 7.

7. Du notebook aux cinq surfaces

Cette section sert à qui a un outil qui marche et veut que d'autres s'en servent. Les projets suivent presque tous la même trajectoire :

Notebook → script → bibliothèque → cinq surfaces

Vous trouvez d'abord ce qui marche dans un notebook. Vous promouvez les cellules utiles en script, pour que l'expérience se rejoue. Vous rangez ensuite les fonctions dans une bibliothèque, un paquet Python qu'on installe avec pip et qu'on teste. Il reste à la rendre accessible.

Streamlit, Gradio et Taipy existent pour ça : ils font d'un script un formulaire web. Gradio appartient à Hugging Face depuis 2021. Huit Spaces sur dix parmi les mille plus suivis du site en sont faits. Nous préférons une interface plus sobre et plus libre, en HTML ordinaire, que Sprezzature fabrique depuis la ligne de commande.

Un humain, un programme et un agent d'IA n'entrent pas dans un outil par le même endroit. Nous appelons surface chacune de ces entrées. Nous en donnons cinq à chaque bibliothèque : une ligne de commande, une interface graphique, une interface HTTP, un serveur MCP et une skill. La règle qui les tient ensemble : aucune surface ne refait le calcul. Toutes appellent la même fonction de la bibliothèque. Une correction faite une fois vaut pour les cinq. Deux surfaces ne donnent jamais deux réponses différentes à la même question.

Les exemples qui suivent viennent d'elbow-helper, une bibliothèque d'AI Helpers qui dit s'il y a un coude sur une courbe et, si oui, où.

La ligne de commande, avec click

La ligne de commande sert au collègue qui travaille dans un terminal, aux scripts et aux chaînes d'intégration continue. Elle s'appelle aussi CLI, pour command-line interface.

Python fournit argparse pour lire les options d'une commande. click fait le même travail avec moins de code. Il ajoute quatre choses que nous ne voulons plus écrire à la main :

• Des sous-commandes rangées en groupe : elbow-helper knee, elbow-helper elbow, elbow-helper diagnostics. Chacune est une fonction Python ordinaire, décorée.
• Une aide générée : --help décrit chaque option, son type et sa valeur par défaut, sans une ligne de plus.
• Des options vérifiées : --language n'accepte que en ou fr ; click refuse le reste avec un message clair.
• Des tests sans terminal : CliRunner lance la commande dans un test et récupère sa sortie.

import click

@click.group()
def cli():
    """Trouve un coude, ou s'abstient."""

@cli.command()
@click.option("--language", type=click.Choice(["en", "fr"]), default="en")
@click.argument("fichier")
def diagnostics(fichier, language):
    ...

Une ligne de pyproject.toml, elbow-helper = "elbow_helper.cli:main", fait le reste : pip install elbow-helper installe la commande.

L'interface graphique, avec Sprezzature

L'interface graphique sert à la personne qui n'ouvrira jamais de terminal : un client, un collègue d'un autre métier, un étudiant.

Sprezzature est une suite libre de skills pour agents de code, que nous développons pour tout ce qui finit sur un écran. L'une d'elles, sprezzature-cli-gui, lit directement le code de votre ligne de commande, qu'elle soit écrite avec argparse, click ou Typer. Elle en tire une page HTML : chaque option devient le bon contrôle de formulaire, une case à cocher, une liste, un champ numérique. Le résultat est du HTML et du Tailwind ordinaires, que vous lisez et retouchez, sans cadriciel qui vous retient.

elbow-helper va un cran plus loin. Sa page fait tourner la vraie bibliothèque dans le navigateur, grâce à Pyodide, un Python compilé pour le web. La page se dépose sur n'importe quel hébergement statique, sans serveur à faire tourner. C'est elle qui est en ligne sur deraison.ai/elbow-helper.

L'interface HTTP, avec FastAPI

L'interface HTTP sert aux autres programmes : un site web, une application mobile, un service d'une autre équipe, écrit dans n'importe quel langage. On l'appelle aussi API, pour application programming interface.

FastAPI transforme une fonction Python en adresse web. Les types déclarés dans la fonction deviennent le contrat : FastAPI vérifie chaque requête et publie une documentation interactive à l'adresse /docs, où l'on essaie chaque route depuis le navigateur. C'est cette interface que lance le docker compose de la section 2.

Le serveur MCP, avec FastAPI-MCP

Le serveur MCP sert aux agents d'IA. MCP, pour Model Context Protocol, est un protocole ouvert qui permet à un agent comme Claude Code de découvrir des outils et de les appeler. Sans lui, l'agent devine une commande et lit sa sortie ; avec lui, il reçoit la liste des outils, leurs paramètres et leurs types.

FastAPI-MCP monte un serveur MCP sur l'application FastAPI qui existe déjà. Chaque outil MCP est une route de l'API. Les deux surfaces ne divergent donc jamais : elles partagent le même code, la même validation et la même documentation.

from fastapi_mcp import FastApiMCP

mcp = FastApiMCP(app, include_operations=["knee", "elbow", "diagnostics"])
mcp.mount_http()   # le serveur MCP répond sur /mcp

Reste une question que le protocole ne règle pas : quand l'agent doit-il appeler l'outil ? Il le décide d'après une courte description. C'est là que la plupart des outils échouent. Un agent ne pense pas à elbow-helper quand on lui demande « combien de groupes dois-je prendre pour mon k-means ? », sauf si quelqu'un a écrit que cette phrase-là doit le déclencher. Nous écrivons donc, pour chaque dépôt, un fichier TRIGGERS.md : le catalogue complet de ce que l'outil sait faire, la commande, la fonction et la route qui correspondent à chaque opération, puis les phrases qui doivent le déclencher et celles qui ne le doivent pas. Il en existe deux exemplaires identiques, l'un à la racine du dépôt pour les humains, l'autre dans le dossier de la skill pour l'agent.

La skill

La skill sert à l'agent de code qui travaille avec vous dans votre projet. C'est un dossier qui contient un fichier SKILL.md : en tête, un nom et une description ; dessous, les instructions d'un métier précis ; à côté, des références et des scripts. L'agent ne lit au départ que la description. Il ne charge le reste que si votre demande y correspond, si bien que cent skills installées ne l'encombrent pas.

Ce format est né chez Anthropic, qui l'a publié comme norme ouverte sous le nom Agent Skills. Le même dossier se lit aujourd'hui dans Claude Code, OpenCode, Codex d'OpenAI, Gemini CLI de Google, Cursor, GitHub Copilot et goose. Plusieurs de ces agents cherchent les skills dans un dossier commun, .agents/skills. Une skill écrite une fois sert donc avec n'importe quel modèle, commercial ou local.

La description est la pièce maîtresse : c'est la seule chose que l'agent lit avant de décider. Elle fait moins de 1 024 caractères. Elle dit ce que fait l'outil, quand s'en servir avec les mots de l'utilisateur, puis ce qu'il ne fait pas. Le détail part dans references/triggers.md, le jumeau de TRIGGERS.md.

Pour fabriquer une skill à partir d'un dépôt en cours de construction, nous appliquons la méthode du guide d'Anthropic :

• Partir de deux ou trois cas d'usage concrets : ce que l'utilisateur dit, ce que l'agent fait, ce qui en sort. La skill se construit autour d'eux, pas autour de la liste des fonctions.
• Écrire la description en deux temps : ce que fait l'outil, puis quand s'en servir. Un « aide à gérer les projets » trop vague échoue ; une description technique sans les mots de l'utilisateur aussi.
• Garder SKILL.md court et précis. Des étapes numérotées, avec la commande exacte et la sortie attendue. Le détail va dans references/, que l'agent n'ouvre qu'au besoin.
• Confier les vérifications à un script. Un script donne toujours la même réponse ; une consigne en prose s'interprète.
• Tester le déclenchement. Une vingtaine de demandes : des évidentes, des reformulées, puis des hors sujet qui ne doivent pas la déclencher. Le guide vise neuf déclenchements justes sur dix.
• Comparer avec et sans la skill, sur la même tâche : moins d'appels, moins d'erreurs, ou elle ne sert à rien.
• Demander à l'agent « Quand utiliserais-tu cette skill ? ». Sa réponse montre ce qu'il a compris de la description.

Le guide ne traite pas le cas d'un dépôt existant. Le nôtre a un avantage : TRIGGERS.md, EXAMPLES.md et les tests du dépôt fournissent déjà les cas d'usage, les phrases de déclenchement et les sorties attendues. La skill se fabrique en les condensant. Un agent de code fait ce travail très bien quand on lui donne le guide et le dépôt.

8. Ce qui rend un dépôt lisible

Cette section sert à qui publie du code et veut qu'on s'en serve sans lui écrire. Un dépôt se lit d'abord par ses fichiers en majuscules, à la racine. Voici ceux que nous mettons partout, avec ce que chacun prouve.

README et LISEZMOI

Le README dit ce que fait l'outil, comment l'installer et comment s'en servir en une minute. Il existe en deux langues, README.md et LISEZMOI.md, avec un lien de l'un à l'autre en première ligne. Chaque fichier en majuscules qui suit a la même paire.

EXAMPLES et EXEMPLES

Un exemple qui n'a jamais tourné finit toujours par mentir : une option change de nom, l'exemple reste. Dans EXAMPLES.md, chaque extrait de code a été exécuté contre la version annoncée en tête du fichier. Le bloc qui le suit est sa sortie réelle, collée telle quelle. Le lecteur voit ce qu'il obtiendra, erreurs et abstentions comprises.

LANDSCAPE et PAYSAGE

LANDSCAPE.md compare l'outil à toutes les autres façons de faire le même travail. Un tableau note chaque concurrent de une à cinq étoiles, critère par critère. Puis standpoint, une autre bibliothèque d'AI Helpers, transforme ce tableau en carte de positionnement. Elle publie les coordonnées de chaque point pour que le placement se vérifie.

Deux règles rendent ce fichier honnête. Chaque concurrent est noté sur le travail de ce projet, sans être pénalisé parce qu'il excelle ailleurs. Et la liste comprend toujours la solution du pauvre : estimer à l'œil, ou demander à un grand modèle de langage. Si l'outil ne fait pas mieux que cette ligne-là, il n'a pas lieu d'être.

TRIGGERS

Décrit en section 7 : ce que l'outil sait faire, puis les phrases qui doivent le déclencher. C'est le fichier qui sert à la fois au lecteur humain et à l'agent.

Les langues de l'interface, des messages et des consignes

Un outil documenté en deux langues qui répond dans une seule s'arrête en chemin. Nous traduisons trois sortes de textes. Nous les rangeons séparément, parce qu'elles ne se traduisent pas avec les mêmes règles.

• Les messages de la ligne de commande et de l'interface. Le module standard gettext de Python lit des catalogues de traductions, des fichiers .po écrits par le traducteur puis compilés en .mo. Le guide de better-i18n décrit bien la méthode. Trois de ses conseils évitent les erreurs les plus courantes. Les variables restent nommées dans la phrase à traduire, %(nom)s, pour que le traducteur puisse changer leur ordre. Les pluriels passent par ngettext, parce que chaque langue a ses règles : le polonais a quatre formes. Les nombres et les dates passent par Babel, qui sait qu'en français une espace insécable précède le signe pour cent. Nous compilons les .mo nous-mêmes, au premier usage, pour ne pas imposer un outil de plus à l'installation.
• Les textes de la page web. Une table JSON par langue, lue par le navigateur, si bien que la page change de langue sans Python.
• Les consignes envoyées à un modèle de langue. Elles vivent dans un fichier à part, prompts.yaml. Un libellé d'interface se traduit librement ; une consigne, non. Elle nomme des champs que le programme relit ensuite : une traduction trop libre fait rejeter la réponse du modèle.

Une dernière règle tient à qui lit la sortie. La ligne de commande ne suit pas la langue du système, elle répond à une variable dédiée, parce que des scripts lisent sa sortie et qu'une commande qui change de langue quand LANG vaut fr_FR casse tous ces scripts. L'interface graphique, elle, suit la langue du navigateur : un navigateur qui demande du français, c'est une personne qui demande.

9. Les recettes d'installation

Cette section sert à qui prépare une machine neuve. Une recette par système, à coller dans l'ordre. Chaque fois qu'il faut ouvrir un nouveau terminal ou redémarrer, la recette le dit : c'est l'étape que tout le monde saute. Elle est la cause de la moitié des « conda : commande introuvable ».

Partout, le projet contient les trois fichiers de la section 1 ; l'environnement s'appelle env4ml.

macOS (Apple Silicon)

Nous avons rejoué cette recette en novembre 2026 sur un Mac Apple Silicon, avec un Miniconda installé dans un dossier neuf, un environnement neuf et un terminal vierge. PyTorch y voit la puce graphique d'Apple à condition d'avoir macOS 15 ou plus récent.

Étape 1. Les outils de développement d'Apple. Ils fournissent le compilateur et Git.

xcode-select --install

Étape 2. Miniconda.

mkdir -p ~/miniconda3
curl https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-arm64.sh -o ~/miniconda3/miniconda.sh
bash ~/miniconda3/miniconda.sh -b -u -p ~/miniconda3
rm ~/miniconda3/miniconda.sh
~/miniconda3/bin/conda init zsh

Fermez le terminal et ouvrez-en un nouveau. La dernière commande a modifié la configuration du shell, que seul un nouveau terminal relit.

Étape 3. L'environnement, depuis le dossier du projet :

conda env create -f environment.yaml
conda activate env4ml

Étape 4. La vérification. La commande affiche mps:0, le nom de la puce graphique d'Apple :

python -c "import torch; x = torch.ones(3, device='mps'); print(x.device)"

Un détail nous a surpris pendant l'essai : juste après pip install -r requirements-dev.txt, la commande pytest lancée dans le même terminal était une ancienne copie installée ailleurs sur la machine. Le shell zsh garde en mémoire l'emplacement des commandes qu'il connaît. Tapez rehash, ou ouvrez un nouveau terminal, après avoir installé un outil en ligne de commande.

Ubuntu

Étape 1. Miniconda.

mkdir -p ~/miniconda3
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -O ~/miniconda3/miniconda.sh
bash ~/miniconda3/miniconda.sh -b -u -p ~/miniconda3
rm ~/miniconda3/miniconda.sh
~/miniconda3/bin/conda init bash

Fermez le terminal et ouvrez-en un nouveau.

Étape 2. L'environnement, depuis le dossier du projet :

conda env create -f environment.yaml
conda activate env4ml

Sans carte NVIDIA, vous avez fini.

Étape 3. Le pilote NVIDIA et CUDA. Nous suivons les instructions de Google Cloud, qui fournissent un script d'installation testé sur les versions récentes d'Ubuntu :

curl -L https://storage.googleapis.com/compute-gpu-installation-us/installer/latest/cuda_installer.pyz --output cuda_installer.pyz
sudo python3 cuda_installer.pyz install_driver

Le script redémarre parfois la machine en cours de route. Si c'est le cas, relancez la même commande : il reprend où il s'était arrêté. Une fois le pilote installé, redémarrez la machine. Le script ne fonctionne pas quand le démarrage sécurisé (Secure Boot) est actif : Google le traite dans une section à part de la même page.

Étape 4. La vérification.

nvidia-smi
python -c "import torch; print(torch.cuda.is_available())"

La première commande affiche la carte, la seconde True. Sur Linux, le PyTorch par défaut de requirements.txt embarque déjà CUDA : rien à changer dans la liste. Ne passez par le sélecteur officiel de PyTorch que si vous avez besoin d'une autre version de CUDA.

Windows 11

Pour l'apprentissage automatique sous Windows, nous conseillons fortement WSL2, le sous-système Windows pour Linux. Il fait tourner un vrai Ubuntu à l'intérieur de Windows, si bien que les mêmes commandes marchent sur votre portable, sur un serveur et dans un conteneur.

Étape 1. Le pilote NVIDIA, côté Windows, si vous avez une carte NVIDIA. Prenez le pilote Windows habituel sur le site de NVIDIA. C'est le seul pilote à installer : le guide de NVIDIA pour WSL interdit d'en installer un second à l'intérieur d'Ubuntu.

Étape 2. WSL2, depuis un PowerShell ouvert en administrateur :

wsl --install

Redémarrez l'ordinateur. Au redémarrage, Ubuntu termine son installation et vous demande un nom d'utilisateur et un mot de passe.

Étape 3. Ouvrez Ubuntu depuis le menu Démarrer. Suivez la recette Ubuntu ci-dessus, sans l'étape 3 : le pilote Windows sert aussi à WSL.

S'il vous faut vraiment du Windows natif, par exemple parce qu'un kit de développement n'existe que là, installez Miniconda depuis l'invite de commandes :

curl https://repo.anaconda.com/miniconda/Miniconda3-latest-Windows-x86_64.exe -o miniconda.exe
start /wait "" miniconda.exe /S
del miniconda.exe

Puis ouvrez l'application « Anaconda Prompt (miniconda3) » depuis le menu Démarrer : l'installation silencieuse n'ajoute pas conda à l'invite de commandes ordinaire. Dans cette fenêtre, les deux commandes de la section 1 fonctionnent telles quelles. Pour une carte NVIDIA, prenez la commande que donne le sélecteur de PyTorch pour Windows : le PyTorch par défaut y tourne sur processeur.

Si vous débutez et cherchez à pratiquer, les cours gratuits de Kaggle sont un bon point de départ, une fois l'environnement en place.

10. Pour aller plus loin : MLflow et Airflow

Cette section est la partie avancée. Elle sert à qui a un modèle en production à réentraîner, le comparer à l'ancien et le remplacer sans casse. Si vous découvrez PyTorch, revenez-y plus tard.

Le problème apparaît vers le troisième modèle. Lequel tourne en production ? Avec quelles données a-t-il été entraîné ? Pourquoi le nouveau est-il moins bon ? Sans trace écrite, personne ne sait répondre. Un jour, la réponse devient « le fichier modele_final_v3_bis.onnx, sur le portable d'un stagiaire parti depuis ».

MLflow garde la trace. Chaque entraînement est enregistré avec ses paramètres, ses mesures et le modèle produit. Le meilleur modèle entre dans un registre, avec un numéro de version. L'équipe sait à tout moment lequel est en service. MLflow sait enregistrer un modèle au format ONNX, décrit dans la section suivante :

import mlflow

with mlflow.start_run():
    mlflow.log_param("profondeur", 6)
    mlflow.log_metric("justesse", 0.93)
    mlflow.onnx.log_model(modele_onnx, name="modele", registered_model_name="detecteur")

Le fichier qui partira sur les appareils est donc celui qu'on a mesuré et versionné, pas un export fait à la main un vendredi soir.

Airflow fait tourner la chaîne sans qu'on y pense. On y décrit, en Python, une suite de tâches et leurs dépendances : récupérer les nouvelles données, réentraîner, évaluer, exporter en ONNX, enregistrer dans MLflow. Airflow la lance chaque semaine, ou dès que de nouvelles données arrivent. Si le nouveau modèle fait moins bien que l'ancien, la chaîne s'arrête et l'ancien reste en service. Depuis sa troisième génération, Airflow garde aussi la version de la chaîne avec laquelle chaque exécution a commencé : une modification en cours de route ne mélange plus deux versions dans le même résultat.

Ces deux outils ont des concurrents, commerciaux et libres, ainsi qu'un service géré dans chaque grand cloud. Nous les citons parce qu'ils sont libres et répandus. Ils s'installent aussi avec la même liste que le reste.

11. Le logiciel libre, groupe électrogène de secours

Cette section sert à qui décide d'un outillage pour une équipe, un laboratoire ou une entreprise. Elle explique pourquoi nous gardons, à côté de chaque service commercial, un équivalent libre installé et testé.

« L'IA est la nouvelle électricité. »

Andrew Ng, Stanford Graduate School of Business, janvier 2017.

La formule a été répétée au point de paraître évidente, mais le chemin qu'elle décrit est réel. L'électricité est passée de technologie de pointe à service public, puis à quelque chose auquel plus personne ne pense. L'IA suit la même route. La comparaison sert ici pour une raison précise : l'électricité est aussi le cas d'école de la bonne façon de dépendre de quelque chose.

Dans n'importe quel pays de l'OCDE, un hôpital est raccordé à un réseau conçu, régulé, surveillé et très largement fiable. Il garde quand même un groupe électrogène au sous-sol. Personne ne fait tourner la réanimation dessus un mardi ordinaire : il est là pour le jour où le réseau tombe, parce que « nous faisions confiance au fournisseur » n'est pas une réponse défendable.

L'IA entre dans la même catégorie que l'électricité, l'eau et les routes. Hôpitaux, ministères, laboratoires, écoles et petites entreprises en dépendent déjà. La différence avec le réseau électrique : les fournisseurs d'IA sont quelques entreprises privées, dans quelques pays, chacune avec ses tarifs, ses règles et son historique de pannes.

La réponse pratique est celle de l'hôpital. Prenez une IA commerciale quand c'est le bon outil. Gardez un équivalent libre installé et testé, idéalement chez vous ou sur vos propres serveurs. Un jour, une facture, un changement de conditions, une limite de débit, une clé révoquée ou une décision politique mettra l'option commerciale hors de portée. L'IA libre est, au minimum, le groupe électrogène de la centrale payante.

Une double pile

• Côté commercial : Claude, ChatGPT, Gemini, Mistral. Capacité de pointe, calcul hébergé, engagements de service.
• Côté libre : les modèles à poids ouverts de Meta Llama, Google Gemma, Qwen, Mistral et DeepSeek, que vous faites tourner chez vous par Ollama, llama.cpp ou vLLM.
• Agent de code : le même schéma une couche plus haut. Claude Code au quotidien, OpenCode au sous-sol, qui pilote les mêmes skills avec un modèle local, pour le jour où le service en amont devient injoignable.

Un cercle vertueux

Au-delà de l'argument du secours, les deux côtés se nourrissent. Les laboratoires commerciaux avancent la frontière ; le libre rattrape, souvent en quelques mois, puis l'avance à son tour avec des idées que la version commerciale suivante reprend. La filiation se lit facilement : TensorFlow et PyTorch ouverts par Google et Meta, l'article fondateur sur le Transformer déposé en accès libre, Hugging Face et son dépôt de modèles, llama.cpp qui fait tourner des modèles sérieux sur un portable, les recettes de raisonnement de DeepSeek-R1. Chacun a fait chuter un coût ou débloqué une technique sur laquelle le monde commercial a bâti.

L'IA moderne n'aurait pas pu se construire en vase clos. Ses articles, ses jeux d'épreuve et la communauté mondiale qui les lit et les améliore avaient besoin de la porte ouverte. Sans logiciel libre, pas de PyTorch dont on apprend, pas de prépublication qu'on reproduit un vendredi soir, pas de notebook Kaggle qu'on reprend à son compte.

La double pile est donc deux choses à la fois. Une bonne pratique : le groupe tourne une fois par mois, l'équipe sait le démarrer. Le jour où le réseau tombe, l'hôpital continue. Et une dette reconnue : tous les autres jours, le réseau lui-même tourne sur du code ouvert, des articles ouverts et des poids ouverts.

12. De Python à Rust, par ONNX

Cette dernière section sert à qui doit faire tourner un modèle ailleurs que dans Python : sur un téléphone, dans un appareil embarqué, dans un navigateur, ou dans un programme livré en un seul fichier.

Python est le bon endroit pour chercher. Les bibliothèques, les articles et les modèles y paraissent en premier. Tout ce guide repose sur lui. Mais Python ne va pas partout. Sur un iPhone ou un téléphone Android, on n'embarque pas un interpréteur Python et sa pile scientifique dans une application. Sur une machine industrielle, on ne demande pas à l'exploitant d'installer conda.

La chaîne que nous suivons a trois étapes.

1. On met au point en Python. C'est là qu'on entraîne, qu'on mesure et qu'on compare, avec tout ce que décrivent les sections précédentes.

2. On fige le modèle au format ONNX. ONNX, pour Open Neural Network Exchange, est un format de fichier ouvert qui décrit un modèle entraîné : ses calculs et ses poids, sans le code Python qui l'a produit. PyTorch, TensorFlow et scikit-learn savent tous exporter vers ONNX. Le moteur qui exécute ce fichier, ONNX Runtime, est libre, maintenu par une communauté où Microsoft tient une grande place. Il tourne sur tous les systèmes.

3. On déploie en Rust. Rust est un langage compilé, aussi rapide que le C, qui interdit à la compilation la plupart des erreurs de mémoire. Un programme Rust se livre en un seul fichier exécutable par plateforme : rien à installer, pas d'interpréteur à lancer, peu de mémoire consommée. La bibliothèque Rust ort, encore en préversion, appelle ONNX Runtime et fournit des binaires prêts pour Windows, macOS, Linux, iOS, Android et le navigateur. Sur chaque appareil, elle passe par l'accélérateur local : Core ML chez Apple, NNAPI ou la puce Qualcomm sur Android.

L'argument est la portabilité, pas la vitesse. Nous l'avons mesuré sur la diarisation de vocal-helper, qui dit qui parle quand dans un enregistrement. Le modèle ONNX occupe 99,8 % du temps de calcul. Il tourne dans le même code C++ qu'on l'appelle depuis Python ou depuis Rust. Réécrire le reste en Rust ferait gagner au mieux 0,2 %. Sa réécriture, vocal-helper-rs, existe pour une autre raison : elle tourne là où Python n'arrive pas. Cinq autres bibliothèques d'AI Helpers ont leur jumelle Rust, publiée sur crates.io, pour les machines sans Python.

D'autres outils Rust méritent d'être connus :

• tract, de Sonos, exécute un modèle ONNX en Rust pur, sans dépendre d'ONNX Runtime. Il est petit et autonome, fait pour l'embarqué.
• candle, de Hugging Face, puis burn : deux cadriciels d'apprentissage écrits en Rust. Tous deux savent importer un modèle ONNX ; burn le transforme même en code Rust ordinaire.
• UniFFI, de Mozilla, génère à partir d'une bibliothèque Rust les liaisons pour Swift sur iOS et Kotlin sur Android. Le même cœur Rust sert alors l'application de chaque téléphone.

La boucle se referme ainsi. Ce guide commence par un environnement Python, parce que c'est là qu'on trouve. Il finit par Rust, parce que c'est par là que ce qu'on a trouvé sort de Python pour aller sur chaque système et chaque appareil. Entre les deux, ONNX joue le rôle d'un contrat : un seul fichier, que le chercheur produit et que l'appareil exécute. Le site arewelearningyet.com tient la chronique de l'apprentissage automatique en Rust.