ai-lab-transformers-playground/POSTMAN_GUIDE.md

📮 Collection Postman - AI Lab API

📋 Overview

Cette collection Postman complète contient tous les endpoints de l'API AI Lab avec des exemples prêts à utiliser pour tester chaque pipeline NLP.

📁 Fichiers inclus

• AI_Lab_API.postman_collection.json - Collection principale avec tous les endpoints
• AI_Lab_API.postman_environment.json - Environnement avec variables configurables
• POSTMAN_GUIDE.md - Ce guide d'utilisation

🚀 Installation et Configuration

1. Importer dans Postman

1. Ouvrez Postman
2. Cliquez sur Import (bouton en haut à gauche)
3. Sélectionnez Upload Files
4. Importez les deux fichiers :
   • AI_Lab_API.postman_collection.json
   • AI_Lab_API.postman_environment.json

2. Configurer l'environnement

1. Cliquez sur l'icône Settings (⚙️) en haut à droite
2. Sélectionnez "AI Lab API Environment"
3. Modifiez base_url si nécessaire (par défaut : http://localhost:8000)

3. Démarrer l'API

Avant d'utiliser Postman, assurez-vous que l'API est démarrée :

# Dans le dossier du projet
python -m src.main --mode api
# ou
poetry run python src/main.py --mode api --host 0.0.0.0 --port 8000

📊 Structure de la Collection

🏠 Core Endpoints

• Root - Informations générales de l'API
• Health Check - Statut de l'API et pipelines chargés

💭 Sentiment Analysis

• Analyze Sentiment - Positive - Test avec texte positif
• Analyze Sentiment - Negative - Test avec texte négatif
• Analyze Sentiment - Custom Model - Test avec modèle personnalisé
• Batch Sentiment Analysis - Traitement par lot

🏷️ Named Entity Recognition

• Extract Entities - People & Organizations - Entités personnes/organisations
• Extract Entities - Geographic - Entités géographiques
• Batch NER Processing - Traitement par lot

❓ Question Answering

• Simple Q&A - Questions simples
• Technical Q&A - Questions techniques

🎭 Fill Mask

• Fill Simple Mask - Masques simples
• Fill Technical Mask - Masques techniques
• Batch Fill Mask - Traitement par lot

🛡️ Content Moderation

• Check Safe Content - Contenu sûr
• Check Potentially Toxic Content - Contenu potentiellement toxique
• Batch Content Moderation - Traitement par lot

✍️ Text Generation

• Generate Creative Text - Génération créative
• Generate Technical Text - Génération technique
• Batch Text Generation - Traitement par lot

🧪 Testing & Examples

• Complete Pipeline Test - Test complet
• Error Handling Test - Empty Text - Gestion d'erreurs (texte vide)
• Error Handling Test - Invalid Model - Gestion d'erreurs (modèle invalide)

🔧 Utilisation Avancée

Variables d'environnement disponibles

Variable	Description	Valeur par défaut
base_url	URL de base de l'API	http://localhost:8000
api_version	Version de l'API	1.0.0
timeout	Timeout des requêtes (ms)	30000
default_*_model	Modèles par défaut	Voir environnement

Personnalisation des modèles

Vous pouvez tester différents modèles en modifiant le champ model_name dans le body des requêtes :

{
	"text": "Your text here",
	"model_name": "cardiffnlp/twitter-roberta-base-sentiment-latest"
}

Tests automatiques

Chaque requête inclut des tests automatiques :

• ✅ Temps de réponse < 30 secondes
• ✅ Header Content-Type présent
• ✅ Logs automatiques dans la console

📈 Exemples d'utilisation

1. Test rapide de l'API

1. Exécutez "Health Check" pour vérifier que l'API fonctionne
2. Testez "Analyze Sentiment - Positive" pour un premier test

2. Test complet d'un pipeline

1. Commencez par un test simple (ex: sentiment positif)
2. Testez avec un modèle personnalisé
3. Testez le traitement par lot
4. Testez la gestion d'erreurs

3. Benchmark de performance

1. Utilisez "Batch Text Generation" avec plusieurs prompts
2. Surveillez les temps de réponse dans l'onglet Tests
3. Ajustez le timeout si nécessaire

🐛 Dépannage

API non accessible

• Vérifiez que l'API est démarrée sur le bon port
• Modifiez base_url dans l'environnement si nécessaire

Erreurs 422 (Validation Error)

• Vérifiez le format JSON du body
• Assurez-vous que les champs requis sont présents

Erreurs 503 (Service Unavailable)

• Pipeline non chargé - vérifiez les logs de l'API
• Redémarrez l'API si nécessaire

Timeouts

• Augmentez la valeur timeout dans l'environnement
• Certains modèles peuvent être lents au premier chargement

🎯 Bonnes Pratiques

1. Démarrez toujours par Health Check pour vérifier l'état de l'API
2. Utilisez l'environnement pour centraliser la configuration
3. Consultez les logs dans la console Postman pour déboguer
4. Testez progressivement : simple → personnalisé → batch → erreurs
5. Documentez vos tests en ajoutant des descriptions aux requêtes

🔗 Liens Utiles

• Documentation Swagger : http://localhost:8000/docs (quand l'API est active)
• Documentation ReDoc : http://localhost:8000/redoc
• Schéma OpenAPI : http://localhost:8000/openapi.json

---

Happy Testing! 🚀