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âches | Concept HF | Bibliothèque | Fichier de référence |
|---|---|---|---|
| Classification de texte | AutoModelForSequenceClassification | transformers | references/text-classification.md |
| Classification de jetons (NER) | AutoModelForTokenClassification | transformers | references/token-classification-ner.md |
| Embeddings de texte | modèle d'embedding de phrases | sentence-transformers | references/embeddings.md |
| Génération d'images | pipeline de diffusion | diffusers | references/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
uvicornsur 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.0ou 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 installou ne démarrezuvicornvous-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 exempledistilbert-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>-apidans 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_familycorrespond à 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 lemodel_idest soit erroné/mal orthographié, soit que le dépôt est restreint/privé. Il ne peut pas vous dire lequel. D'abord, reconfirmez lemodel_idexact 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'environnementHF_TOKEN(HF_TOKEN=hf_xxx python scripts/inspect_model.py <model_id>) ouhuggingface-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, voirreferences/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 middleware413dansmain.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 gestionnaireasync 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.pyrenvoietask_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--taskexplicitement à 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.mdplutôt que de le forcer dans l'un des quatre fichiers de référence. - L'installation du
requirements.txtgénéré est lente/énorme :torchetdiffuserssont volumineux ; avertissez l'utilisateur avant qu'il n'exécutepip installsi la famille de tâches les attire.