Fiche mémo IA appliquée

Appel d'API : structure d'une requête et réponse

Requête

• model : identifiant du modèle (à lire chaque jour chez le fournisseur)
• max_tokens : obligatoire ; plafond de sortie
• messages : alternance de user / assistant ; historique à renvoyer entièrement
• system : consigne (paramètre de premier niveau chez Anthropic, rôle ailleurs)
• stop_sequences : chaînes qui arrêtent la génération
• stream : réponse par flux d'événements
• tools : définitions d'outils (voir cours Agents)

Réponse

• content : liste de blocs (texte, outil demandé…)
• stop_reason : end_turn (fin naturelle), stop_sequence, tool_use, max_tokens (tronquée), refusal (refusée)
• usage : input_tokens, output_tokens ; plus cache_read_input_tokens, cache_creation_input_tokens si cache
• Toujours lire stop_reason avant d'exploiter le texte.

Erreurs courantes

Attente : min(30, 2^essai) + gigue aléatoire, max 4 essais.

Sortie structurée JSON

Trois niveaux (du plus faible au plus fort)

1. Demander du JSON dans la consigne : fragile, risque de prose autour
2. Mode JSON : syntaxe valide, forme non garantie
3. Schéma JSON : forme imposée par le service (Anthropic : output_config.format ; OpenAI : json_schema strict)

Validation côté client (toujours)

try:
    objet = json.loads(texte)
    # vérifier clés, types, énumérations, bornes (code pas présenté)
except (json.JSONDecodeError, ValueError, KeyError):
    # nouvelle tentative bornée ou erreur

Pièges : stop_reason = max_tokens (sortie tronquée), refusal (refusée), schéma non respecté en cascade. Le service garantit la syntaxe JSON, pas le sens.

Clés d'API et sécurité

• Ne jamais coder, committer, screenshotter, passer à un assistant
• Fichier d'environnement, Trousseau macOS ou gestionnaire de secrets
• En cas de fuite : révoquer immédiatement chez le fournisseur
• Une clé par usage et par environnement (test, prod)

Détection : git grep -n -I -E "(api[_-]?key|secret|bearer|token)" (lecture seule)

Coûts et budgets

Jetons

Facturés à l'usage en jetons d'entrée + sortie, tarifs différents. Aucun prix ici, à lire le jour même.

• Comptage avant envoi : API gratuite (selon Anthropic) mais soumise à ses propres limites ; estimation, pas exactitude
• Tokenizer different par génération de modèle : recompter avec le modèle visé

Gestion

class Budget:
    def __init__(self, max_entree, max_sortie):
        self.max_entree, self.max_sortie = max_entree, max_sortie
        self.entree = self.sortie = 0

    def enregistrer(self, usage):
        self.entree += usage["input_tokens"]
        self.sortie += usage["output_tokens"]
        if self.entree > self.max_entree or self.sortie > self.max_sortie:
            raise RuntimeError("budget épuisé")

Limites de débit

• RPM (requêtes par minute), ITPM/OTPM (jetons d'entrée/sortie par minute)
• Seau à jetons : capacité reconstituée en continu, pas de remise à zéro à l'heure
• Plafonds de dépense mensuels (selon l'offre)
• Jetons lus du cache : ne comptent pas vers ITPM chez Anthropic et OpenAI (sauf exceptions) ; bonne raison de cacher

Fenêtre de contexte et mise en cache

Contexte

• Limite par modèle (Anthropic : jusqu'à 1 M jetons selon le modèle)
• Contient : consigne, tous les messages, outils, sortie générée
• Pas d'accumulation côté service : vous renvoyez l'historique entier
• Dépassement : 400 si entrée seule dépasse ; stop_reason = model_context_window_exceeded si entrée + max_tokens dépasse (modèles récents)

Pourriture de contexte : précision baisse quand la taille grandit. Tronquer, résumer ou utiliser le RAG.

Cache de prompts

• Réutilise un préfixe identique à l'octet près (gains : latence et coût d'entrée sur ce préfixe)
• Placer d'abord le contenu stable (consigne, documents), puis le variable (question, horodatage)
• Durée : 5 min (Anthropic par défaut), 1 h en option, ou selon la politique du fournisseur
• Invalidation : changement d'outils, consigne, ou configuration invalide le cache à partir de ce point
• Mesure : usage.cache_read_input_tokens, cache_creation_input_tokens

RAG (Retrieval-Augmented Generation)

Préparation (hors ligne)

1. Découpage : passages assez courts pour être précis, assez longs pour garder du sens (à tester)
2. Embeddings : vecteur par passage (même modèle pour indexer et interroger)
3. Stockage : base vectorielle ou simple JSON/SQLite pour commencer

À chaque question

4. Recherche : k passages les plus proches (embeddings + BM25 lexical)
5. Reclassement : un second score réordonne les candidats
6. Contexte : passages identifiés ([d1#0]), délimités, jamais confondus avec la consigne
7. Génération : consigne « réponds uniquement à partir des passages » + passage + question
8. Vérification : chaque citation [id] doit exister et être vérifiable

Limites et hallucinations

• Recherche rate le bon passage → modèle comble le vide
• Modèle cite un passage sans le soutenir vraiment (impossible à détecter sans juge sémantique)
• Passages contradictoires → réponse fausse
• Passages non fiables (injection indirecte, LLM08 OWASP) → défense en couches (voir Sécurité)
• Droits d'accès : la base ne doit renvoyer que ce que l'utilisateur peut lire

Évaluation

Jeu de tests

• Cas typiques, limites (vide, très long, ambiguë, hors sujet), pièges (injection, données sensibles)
• Versions avec le code ; jamais de données réelles
• Priorité : nombre de cas notés automatiquement plutôt que quelques cas à la main

Notation

LLM-as-judge : rubrique explicite, sortie vérifiable (1–5, oui/non), modèle différent de celui qui génère, connaître les biais.

Régression

def regression(score, reference_json, tolerance=0):
    ref = json.loads(pathlib.Path(reference_json).read_text())
    return score >= ref["score"] - tolerance

Rejouer après chaque changement (consigne, modèle, paramètre, découpage).

Sécurité et confidentialité

Injection de prompt

Directe (utilisateur adversaire) : présélection avec petit modèle, liste blanche d'actions, validation.

Indirecte (contenu tiers) : mettre dans les résultats d'outils, dire au modèle d'où vient le contenu, encoder en JSON, consigne explicite que c'est une donnée, vérifier avant passage au modèle.

Sorties non fiables : ne jamais les exécuter

❌ eval(), exec(), os.system(), concaténation SQL/chemin/URL, HTML brut
✓ Liste blanche d'actions validées, arguments contrôlés, requêtes paramétrées

Fuite de données

• Aucun secret, identifiant, adresse IP, détail d'infrastructure en requête
• Pseudonymiser ou remplacer par exemples (exemple.test, 192.0.2.10)
• Filtrer côté code avant l'appel
• Consigne système : ne rien mettre qui ne doive pas partir sur le réseau
• Journal : métadonnées seules, texte masqué ou absent, durée de conservation limitée

Moindre privilège

Donner à un outil le strict minimum : lecture seule par défaut, dossier restreint, compte dédié, budget et durée bornés, confirmation pour tout effet irréversible.

Cadre de gestion (NIST AI RMF 1.0)

Quatre fonctions : Govern (qui valide), Map (risques), Measure (tests), Manage (bornes et surveillance).

Hébergé ou local (Ollama)

Décider d'abord sur les données (sensibilité) ; qualité ensuite ; coût en dernier.

Ollama local : http://localhost:11434/api (sans auth) ; Ollama cloud : clé d'API ; modèles :cloud envoient les données au cloud.

Checklist avant usage en production

1. ✓ Clé hors code, dépôt, journaux, prompts ; procédure de révocation.
2. ✓ max_tokens, budget jetons, plafond dépense fixés ; essais bornés.
3. ✓ stop_reason lu ; sorties JSON validées côté client.
4. ✓ Contexte maîtrisé (troncature ou résumé) ; cache avec préfixe stable.
5. ✓ RAG : seuil, citations vérifiées, « je ne sais pas » possible.
6. ✓ Jeu de tests versionné, régression testée à chaque changement.
7. ✓ Journal de métadonnées, texte masqué ou absent, durée de conservation.
8. ✓ Contenu tiers en données ; aucune sortie exécutée ; liste blanche ; moindre privilège.
9. ✓ Rien de sensible envoyé ; hébergé ou local justifié.
10. ✓ Tout relu et validé avant application à un vrai outil.

Références rapides

Statut du service : lire le jour même (tarifs, limites, modèles, changements).

En cas d'erreur 429 : attendre retry-after s'il est présent, sinon min(30, 2^essai) + gigue, max 4 essais.

Pour les sorties structurées : valider JSON, vérifier le type et les bornes, traiter refusal et troncature séparément.

Pour le RAG : même modèle pour embeddings entrée/sortie ; reclassement + citation = fiabilité ; pas d'hallucination éliminée, juste réduite.

Pour la sécurité : données sensibles → local ; contenu tiers → donnée ; sorties → liste blanche ; moindre privilège toujours.