Communitygithub.com

nynuz/ml-serving-skills

Une collection de compétences d'agent pour servir des modèles de machine learning, du backend API au frontend.

Qu'est-ce que ml-serving-skills ?

Cette compétence d'agent spécialisée construit un projet FastAPI de qualité production, autonome et local, à partir d'un simple `model_id` Hugging Face. Elle génère automatiquement la structure complète du projet : une application FastAPI avec chargement unique du modèle au démarrage, des points de terminaison d'inférence adaptés à la tâche, la validation des entrées/sorties, des sondes de santé, une gestion structurée des erreurs, et des scripts optionnels d'évaluation et de benchmark. Elle prend en charge quatre familles de tâches majeures via des bibliothèques spécifiques : classification de texte (transformers), NER (transformers), embeddings (sentence-transformers) et génération d'images (diffusers). L'agent suit un workflow en huit étapes : collecte des entrées, inspection du modèle, lecture du fichier de référence correspondant, génération du projet, vérification des aspects transversaux de production, exécution des tests, et évaluation/benchmark si demandé. La compétence est conçue exclusivement pour un usage local sans authentification ni limitation de débit, et elle impose des limites explicites (taille de batch, longueur des chaînes, taille du corps de la requête) pour éviter des coûts excessifs. Elle se concentre strictement sur le backend et ne génère jamais de code frontend ni de déploiement cloud, ce qui en fait un outil idéal pour les développeurs souhaitant exposer rapidement leurs modèles via une API REST robuste et auto-documentée.

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add nynuz/ml-serving-skills

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Constructeur FastAPI à partir d'un modèle HF

Ce que fait cette compétence

Prend un model_id Hugging Face et génère autour de lui un projet FastAPI autonome, local et de qualité production : structure d'application en couches, modèle chargé une fois au démarrage (jamais par requête), point de terminaison d'inférence adapté à la tâche, regroupement par lots avec limites explicites, validation d'entrée/sortie, sondes de santé et de disponibilité, gestion structurée des erreurs, et scripts optionnels d'évaluation/benchmark.

Elle prend en charge quatre familles de tâches, chacune avec une forme de point de terminaison et une bibliothèque sous-jacente différentes :

Famille de tâchesConcept HFBibliothèqueFichier de référence
Classification de texteAutoModelForSequenceClassificationtransformersreferences/text-classification.md
Classification de jetons (NER)AutoModelForTokenClassificationtransformersreferences/token-classification-ner.md
Embeddings de textemodèle d'embedding de phrasessentence-transformersreferences/embeddings.md
Génération d'imagespipeline de diffusiondiffusersreferences/image-generation.md

Limites du périmètre — lisez ceci avant de commencer

  • Local uniquement. Pas de Docker, pas de Kubernetes, pas de déploiement cloud (Railway, AWS, etc.). Le résultat est un projet que l'utilisateur exécute avec uvicorn sur sa propre machine.
  • Backend uniquement. Ne générez jamais de code frontend/client (React, Next.js, appels fetch, etc.). Si l'utilisateur souhaite une interface utilisateur pour appeler l'API, dites-lui que c'est un sujet distinct et arrêtez-vous à la limite de l'API. Il est acceptable d'activer le CORS local permissif pour qu'un serveur de développement frontend puisse appeler l'API plus tard — c'est une préoccupation de configuration backend, pas de code frontend.
  • Service, pas entraînement. Si l'utilisateur souhaite affiner ou entraîner un modèle, cette compétence n'est pas l'outil approprié — dites-le.
  • Modèle de menace local, mono-utilisateur. Les services générés n'ont AUCUNE authentification et AUCUNE limitation de débit par conception — ils sont destinés à fonctionner sur localhost. Ils imposent des limites de coût d'entrée (taille de lot, longueur par chaîne, paramètres de génération et une limite de taille du corps de la requête -> 413). Dites toujours à l'utilisateur de ne pas lier le service à 0.0.0.0 ou de l'exposer au-delà de localhost sans d'abord ajouter une authentification, une limitation de débit et une politique CORS renforcée — ces éléments sont hors de portée ici.
  • N'installez et ne lancez rien sans demander. Échafaudez le projet et donnez à l'utilisateur les commandes exactes à exécuter. N'effectuez pip install ou ne démarrez uvicorn vous-même que si l'utilisateur vous demande explicitement de vérifier que cela fonctionne — certaines de ces dépendances (torch, diffusers) sont de gros téléchargements.

Flux de travail

Étape 1 : Collecter les entrées

Vous avez besoin de :

  • model_id (obligatoire) — l'ID du Hub Hugging Face, par exemple distilbert-base-uncased-finetuned-sst-2-english.
  • Répertoire de sortie (demandez s'il n'est pas fourni, sinon par défaut ./<nom-modèle-en-slug>-api dans le répertoire de travail actuel).
  • Facultatif : un chemin vers un petit jeu de données d'évaluation étiqueté (pour l'évaluation de la correction plus tard), un port (par défaut 8000).

Si l'utilisateur décrit uniquement ce qu'il a fait dans un notebook (« Je le charge avec pipeline(...), il classifie les sentiments »), demandez le model_id exact s'il n'est pas indiqué — tout ce qui suit en dépend.

Étape 2 : Inspecter le modèle

Exécutez l'inspecteur fourni — il n'interroge que l'API publique du HF Hub, il ne télécharge jamais les poids du modèle :

python scripts/inspect_model.py <model_id>

Il imprime du JSON avec task_family, pipeline_tag, library_name, architectures, id2label (si disponible), num_labels, un nombre approximatif de paramètres et une note de recommandation de périphérique.

  • Si task_family correspond à l'une des quatre familles prises en charge, continuez.
  • S'il renvoie "unknown" ou si vous n'êtes pas d'accord avec l'estimation (certains dépôts ont des métadonnées manquantes/erronées), demandez à l'utilisateur laquelle des quatre familles de tâches s'applique — ne faites pas de supposition erronée en silence, toute la forme du point de terminaison en dépend.
  • Si le script signale not_found_or_gated, l'API publique de HF a renvoyé 401/403/404 — cela signifie que le model_id est soit erroné/mal orthographié, soit que le dépôt est restreint/privé. Il ne peut pas vous dire lequel. D'abord, reconfirmez le model_id exact avec l'utilisateur (les fautes de frappe et les mauvais espaces de noms d'organisation sont la cause la plus courante) ; seulement s'il est confirmé correct, traitez-le comme restreint et demandez à l'utilisateur d'accepter la licence sur la page du modèle et de s'authentifier. Préférez passer le jeton via la variable d'environnement HF_TOKEN (HF_TOKEN=hf_xxx python scripts/inspect_model.py <model_id>) ou huggingface-cli login — évitez le drapeau --token, car un jeton sur la ligne de commande fuit dans l'historique du shell et la liste des processus.

Étape 3 : Lire le fichier de référence correspondant

Avant l'échafaudage, lisez references/<famille-de-tâches>.md pour la famille de tâches de l'étape 2. Il contient le code exact de chargement du pipeline/modèle, le schéma de requête/réponse et les pièges spécifiques à la tâche (par exemple, le mappage d'étiquettes pour la classification, l'agrégation d'entités pour la NER, la stratégie de pooling pour les embeddings, l'encodage d'image pour la génération). Parcourez également references/architecture.md une fois par session — il couvre les parties identiques pour les quatre familles de tâches (chargement de la durée de vie, sondes de santé, CORS, gestion des erreurs) afin que vous n'ayez pas à les redériver à chaque fois.

Utilisez la compétence transformers-huggingface déjà installée pour tout ce qui concerne le chargement de modèle, la tokenisation, le placement sur périphérique (CPU/CUDA/MPS) ou le choix de dtype qui dépasse ce que couvre le fichier de référence — elle contient les modèles faisant autorité pour la bibliothèque transformers elle-même.

Étape 4 : Échafauder le projet

Exécutez le générateur avec la famille de tâches et toute information d'étiquette/configuration que vous avez obtenue à l'étape 2 :

python scripts/scaffold_project.py \
  --model-id "<model_id>" \
  --task <text-classification|token-classification|embeddings|image-generation> \
  --output-dir "<output_dir>" \
  --id2label-json "<chemin-vers-json-ou-json-en-ligne>"   # facultatif, classification/NER uniquement

Exécutez python scripts/scaffold_project.py --help pour voir tous les drapeaux (port, taille de lot maximale, longueur d'entrée maximale / taille d'image, etc.) — transmettez tout ce qui est pertinent que vous avez appris à l'étape 2 au lieu de laisser les valeurs par défaut générées si vous avez de meilleures valeurs.

Cela produit :

<output_dir>/
├── app/
│   ├── main.py            # FastAPI() + durée de vie (charger le modèle une fois, échauffement), CORS, montage du routeur
│   ├── core/
│   │   ├── config.py      # pydantic-settings : MODEL_ID, DEVICE, MAX_BATCH_SIZE, etc. depuis l'env
│   │   └── model.py       # fonction load_model() / inférence pour la famille de tâches choisie
│   ├── api/
│   │   └── routes.py      # point de terminaison de tâche + /health/live + /health/ready + /v1/info
│   └── schemas.py         # Modèles Pydantic de requête/réponse avec contraintes Field
├── tests/
│   ├── test_health.py
│   └── test_inference.py  # cas nominal + un cas d'erreur de validation
├── requirements.txt       # uniquement ce dont cette famille de tâches a besoin
├── .env.example
├── README.md              # instructions d'exécution, documentation du point de terminaison, note CORS
└── .gitignore

L'échafaudeur remplit ce qu'il peut déterminer par programme (id du modèle, famille de tâches, étiquettes si vous les avez passées). Vous devez toujours examiner les fichiers générés app/core/model.py et app/schemas.py par rapport au fichier de référence de l'étape 3 — l'échafaudeur n'appelle pas le modèle, il ne peut donc pas connaître des détails comme l'ensemble exact d'étiquettes si vous n'avez pas passé --id2label-json, ou si un modèle NER a besoin de aggregation_strategy="simple". Remplissez tous les marqueurs # TODO qu'il laisse.

Étape 5 : Vérifier les préoccupations transversales de production

Chaque projet généré doit avoir tout cela — vérifiez-les explicitement, il est facile de les abandonner en silence lors de l'édition manuelle du code généré :

  • Modèle chargé dans lifespan, pas au moment de l'importation ou par requête (app/main.py)
  • Un appel d'échauffement (une inférence factice) juste après le chargement, afin que la première vraie requête ne soit pas la lente — voir references/architecture.md
  • /health/live (processus en vie, aucune vérification de dépendance) est une fonction différente de /health/ready (vérifie que le modèle est chargé) — les confondre provoque des cascades de redémarrage, voir references/architecture.md
  • Chaque réponse d'inférence inclut l'ID/version du modèle — non négociable, c'est ainsi que vous déboguez « quel modèle a produit ceci » plus tard
  • L'entrée par lot a une longueur/taille maximale appliquée par le serveur (Field(..., max_length=...)) — un lot non limité est une dépense GPU/CPU illimitée. L'échafaudeur limite également chaque chaîne individuelle (StringConstraints(max_length=...), ajustez avec --max-chars-per-text) et rejette les corps de requête trop volumineux via un middleware 413 dans main.py (--max-request-mb) — vérifiez que les deux ont survécu à toute édition manuelle, car la vérification de la taille du corps est le seul garde-fou qui se déclenche avant que la charge utile ne soit analysée en mémoire
  • L'inférence liée au CPU/GPU s'exécute via anyio.to_thread.run_sync(...), jamais directement dans un gestionnaire async def — sinon, elle bloque la boucle d'événements pour toutes les autres requêtes en vol
  • Les erreurs de validation renvoient 422 avec un message utile ; les erreurs de modèle/d'exécution sont interceptées et mappées à une erreur HTTP typée, jamais un 500 non géré avec une trace de pile fuyant vers le client

Voir references/batching.md pour le modèle de tableau de lots utilisé par défaut, et quand (rarement, pour une configuration mono-utilisateur locale) le micro-lot dynamique vaudrait la complexité supplémentaire.

Étape 6 : Tests

L'échafaudeur génère tests/test_health.py et tests/test_inference.py en utilisant fastapi.testclient.TestClient (voir references/testing-and-evaluation.md). Parcourez-les, ajustez l'entrée d'exemple/la forme attendue pour correspondre au modèle réel, et dites à l'utilisateur d'exécuter :

pytest

Étape 7 : Évaluation et benchmark (facultatif, uniquement si l'utilisateur le souhaite)

Deux scripts indépendants sont fournis — copiez-les dans le répertoire du projet généré (ils ne font pas partie de l'application FastAPI elle-même, ce sont des outils qui appellent le serveur en cours d'exécution) :

  • scripts/evaluate.py — correction : exécute un jeu de données étiqueté (CSV/JSONL) contre l'API en cours d'exécution et rapporte la précision/F1 (classification, NER) ou des vérifications de cohérence de similarité cosinus (embeddings). Nécessite les données étiquetées de l'utilisateur — demandez un chemin, ou ignorez ceci s'il n'en a pas encore.
  • scripts/benchmark.py — performances : envoie des requêtes concurrentes à l'API en cours d'exécution et rapporte la latence p50/p95/p99 et le débit. Nécessite aucune donnée étiquetée, juste quelques exemples d'entrées.

Voir references/testing-and-evaluation.md pour l'utilisation exacte et comment interpréter la sortie.

Étape 8 : Conclusion

Donnez à l'utilisateur les commandes exactes à exécuter localement :

cd <output_dir>
python -m venv .venv && source .venv/bin/activate   # ou .venv\Scripts\activate sur Windows
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000

Dirigez-les vers /docs pour des tests interactifs (interface utilisateur OpenAPI automatique de FastAPI). Indiquez explicitement ce que vous n'avez pas fait : aucune image Docker, aucun déploiement cloud, aucun code frontend. S'ils veulent l'un de ces éléments ensuite, c'est en dehors de cette compétence.

Dépannage

  • inspect_model.py renvoie task_family: unknown : les métadonnées du dépôt sont incomplètes. Demandez directement à l'utilisateur laquelle des quatre familles il s'agit, et passez --task explicitement à l'échafaudeur.
  • Le modèle nécessite trust_remote_code=True / du code personnalisé : signalez-le à l'utilisateur avant l'échafaudage — cela signifie que du code arbitraire du Hub s'exécute localement ; obtenez une confirmation explicite avant de générer un projet qui définit ce drapeau.
  • L'utilisateur veut une famille de tâches qui n'est pas dans le tableau (par exemple, parole, traduction, VQA) : dites clairement que cette compétence ne couvre actuellement que les quatre familles répertoriées, et proposez de construire le wrapper FastAPI à la main en utilisant les mêmes modèles architecturaux de references/architecture.md plutôt que de le forcer dans l'un des quatre fichiers de référence.
  • L'installation du requirements.txt généré est lente/énorme : torch et diffusers sont volumineux ; avertissez l'utilisateur avant qu'il n'exécute pip install si la famille de tâches les attire.

Skills associés