2026-10-20

Tracer chaque tentative d’une requête d’API IA

Guide de production : Tracer chaque tentative d’une requête d’API IA. Il comprend un artefact déterministe, des limites d’échec, des contrôles de déploiement et des sources vérifiées.

Décider d’abord

Tracer chaque tentative d’une requête d’API IA est un contrat de production explicite, pas une modification isolée. Définissez réussite, échec terminal et rollback avant de déplacer le trafic ; l’artefact sépare preuve et hypothèse.

Commencez par request, prouvez attempt avec un cas déterministe et faites de privacy une condition de mise en production.

Artefact réutilisable

Une ligne ne passe que si sa preuve vient de la même requête, fenêtre de test ou version de configuration.

Point de contrôle	Preuve à conserver	Condition de réussite
`request`	`request_id,tenant_pseudonym,operation,accepted_at`	Le relevé relie une requête logique et une tentative précise.
`attempt`	`attempt_number,route_version,model,channel_pseudonym`	Le relevé relie une requête logique et une tentative précise.
`timing`	`connect,headers,first_event,first_output,idle,total`	La valeur est préservée et comparée exactement à la frontière du protocole.
`terminal`	`HTTP,provider_class,cancellation_source,retry_decision`	Owner, source, date et limite sont consignés.
`usage`	`normalized_input/output/cache_categories_and_provenance`	Réservation, observation et valeur finale se rapprochent dans un registre durable.
`privacy`	`allowlisted_attributes_only;no_prompt,secret,or_raw_arguments`	La limite est explicite et l’échec est fermé.

Exemple détaillé

L’exemple est synthétique et déterministe. Utilisez vos valeurs revues, sans secret ni donnée client.

trace_id: 7f3a...synthetic
request_id: req_demo_001
operation: responses
attempts:
  - attempt: 1
    route_version: rv_42
    model: model_alias
    timings_ms: { headers: 812, first_output: 1240, total: 3100 }
    terminal: upstream_503
  - attempt: 2
    timings_ms: { headers: 620, first_output: 980, total: 2400 }
    terminal: success
usage: { input: 1800, output: 220, source: provider_normalized }

Procédure de mise en œuvre

Figer requête, réponse, configuration et référence observable.
Exécuter un cas positif déterministe et conserver le résultat complet.
Exécuter le cas négatif ou limite associé.
Relier les tentatives à un ID logique et consigner temps, état final et usage sans contenu sensible.
Déployer sur une cohorte bornée avec critères d’arrêt.
Relire l’état durable et le comportement public ; revenir en arrière si une invariance échoue.

Modes d’échec

Ces échecs invalident le résultat même si le HTTP externe semble réussir :

Prompts, clés ou arguments sensibles entrent dans la télémétrie.
Les fragments sont reliés par position plutôt que par ID stable.
Un champ pratique est lu et les sorties typées, tools, refus ou résultats partiels sont perdus.
Des percentiles sont publiés sans workload, concurrence, échecs, région ni fenêtre.

Limite de Modelflare

Modelflare centralise routage compatible OpenAI, clés, groupes, usage et erreurs, mais une route configurée ne prouve aucune capacité optionnelle. Vérifiez modèle et canal par le protocole natif, conservez les zéros explicites et prenez le règlement durable comme vérité de facturation.

La page parente couvre la décision générale et la documentation la configuration actuelle.

Liste avant publication

Répondre à la question principale avant le contexte.
Nommer un owner pour chaque champ, état, métrique et formule.
N’utiliser que des identifiants synthétiques.
Conserver structure, code, limites et avertissements dans toutes les langues.
Revérifier contrats, support et prix à T-1 ; déplacer la date si un fait change.
Avant l’heure, exclure de l’API publique, des routes et du sitemap.

Sources et date de vérification

Sources vérifiées le 2026-08-07 ; elles ne prouvent pas une route non testée.