← Documentation API Reference

Guide Analyste AISIA

Version : 4.15.0 Société : AISIA — Structure juridique en cours de création URL publique : https://aisia.fr/

---

Table des matières

1. Présentation 2. Benchmarking via /v1/runs 3. Export des résultats 4. Métriques Prometheus 5. Dashboards Grafana 6. Routage bandit : interprétation des scores 7. Circuit breaker : diagnostic 8. Domain routing : analyse par domaine 9. Scoring et reward 10. Boucle d'apprentissage 11. Requêtes analytiques avancées 12. Bonnes pratiques

---

1. Présentation

Ce guide est destiné aux analystes et data scientists qui utilisent AISIA pour :

Comparer les performances de providers IA (latence, qualité, coût)
Analyser les patterns de routage et optimiser la sélection des modèles
Exploiter les métriques Prometheus et les dashboards Grafana
Comprendre les algorithmes de routage (UCB1, Thompson Sampling)

AISIA orchestre 52 providers cloud (2415 modèles) et 83 modèles locaux (52 activés) à travers 15 domaines de routage spécialisés.

---

2. Benchmarking via /v1/runs

Le système de benchmark permet d'exécuter des campagnes de test comparatif sur un ensemble de providers et de prompts.

Créer un run de benchmark

POST /v1/runs Content-Type: application/json Authorization: Bearer TOKEN

{ "name": "Comparaison GPT-4 vs Claude vs Gemini", "prompts": [ {"text": "Explique la relativité restreinte en 3 phrases.", "category": "science"}, {"text": "Écris une fonction Python de tri rapide.", "category": "coding"}, {"text": "Traduis 'machine learning' en français technique.", "category": "translation"} ], "providers": ["openai", "anthropic", "gemini"], "max_concurrency": 10, "timeout_s": 30 }

Paramètres du benchmark

Paramètre	Type	Défaut	Description
`name`	string	requis	Nom identifiant du run
`prompts`	list	requis	Liste des prompts à tester
`providers`	list	tous	Sous-ensemble de providers à tester
`max_concurrency`	int	10	Nombre de requêtes parallèles
`timeout_s`	int	30	Timeout par requête individuelle

Consulter les résultats

# Lister les runs
GET /v1/runs

Détail d'un run
GET /v1/runs/{run_id}

Résultats détaillés
GET /v1/runs/{run_id}/results

Structure d'un résultat

Chaque résultat individuel contient :

{
  "request_id": "uuid",
  "run_id": "uuid",
  "provider_id": "openai",
  "prompt": "Explique la relativité...",
  "status": "success",
  "latency_ms": 1250.3,
  "ttfb_ms": 340.2,
  "tokens_used": 150,
  "tokens_per_second": 120.0,
  "http_code": 200,
  "text": "La relativité restreinte...",
  "error": null,
  "created_at": "2026-04-19T10:30:00Z"
}

Métriques clés par provider

À partir des résultats, calculez :

Métrique	Formule	Interprétation
Taux de succès	`success / total`	>95% = excellent, <80% = problème
Latence P50	Médiane des `latency_ms`	Temps typique de réponse
Latence P99	99e percentile	Temps maximum en conditions normales
TTFB moyen	Moyenne des `ttfb_ms`	Réactivité perçue par l'utilisateur
Débit	Moyenne des `tokens_per_second`	Vitesse de génération
Coût/requête	`tokens_used * pricing[provider]`	Budget prévisionnel

---

3. Export des résultats

Formats disponibles

# Export CSV
GET /v1/export?format=csv

Export Excel (XLSX)
GET /v1/export?format=xlsx

Export d'un run spécifique
GET /v1/export?format=xlsx&run_id=UUID

Contenu du fichier Excel

Le fichier XLSX contient deux feuilles :

1. Résultats : Toutes les lignes brutes (request_id, run_id, provider_id, prompt, status, latency_ms, ttfb_ms, tokens_used, http_code, error, created_at)

2. Résumé providers : Tableau agrégé par provider avec : - total : nombre de requêtes - successful : nombre de succès - avg_latency_ms : latence moyenne

Sauvegarde NFS

Si le chemin NFS est monté (/mnt/exports), les exports sont automatiquement sauvegardés avec un horodatage dans le nom de fichier : 20260419_103000_resultats.xlsx

---

4. Métriques Prometheus

AISIA expose 14 métriques Prometheus sur l'endpoint /metrics au format OpenMetrics. Ces métriques sont collectées par le Prometheus du cluster et visualisées dans Grafana.

Métriques de requêtes et latence

Métrique	Type	Labels	Description
`ai_requests_total`	Counter	provider, status	Nombre total de requêtes par provider et statut (success/error)
`ai_request_latency_seconds`	Histogram	provider	Latence totale des requêtes (buckets: 0.1, 0.25, 0.5, 1, 2, 5, 10, 30s)
`ai_request_ttfb_seconds`	Histogram	provider	Time To First Byte (buckets: 0.05, 0.1, 0.25, 0.5, 1, 2, 5s)
`ai_tokens_per_second`	Histogram	provider	Débit en tokens/seconde (buckets: 1, 5, 10, 25, 50, 100, 200, 500)

Métriques de disponibilité

Métrique	Type	Labels	Description
`ai_provider_up`	Gauge	provider	Disponibilité du provider (1=OK, 0=KO) -- temps réel
`ai_provider_health_up`	Gauge	provider	Résultat du dernier health-check (1=OK, 0=KO)
`ai_provider_health_latency_seconds`	Histogram	provider	Latence du health-check (buckets: 0.1, 0.5, 1, 5, 15, 30s)

Métriques d'erreurs

Métrique	Type	Labels	Description
`ai_errors_total`	Counter	provider, code	Erreurs HTTP par provider et code
`ai_429_total`	Counter	provider	Nombre de rate-limits (HTTP 429)

Métriques de routage et système

Métrique	Type	Labels	Description
`ai_bandit_choice_total`	Counter	provider, strategy	Provider sélectionné par le bandit
`ai_run_active_total`	Gauge	--	Nombre de runs de benchmark actifs
`ai_circuit_breaker_state`	Gauge	provider	État du circuit breaker (0=CLOSED, 1=HALF_OPEN, 2=OPEN)
`ai_learning_proposals_total`	Counter	type	Propositions d'apprentissage générées
`ai_discovery_candidates`	Gauge	--	Candidats providers découverts

Requetes PromQL utiles

# Taux de succès par provider (5 dernières minutes)
rate(ai_requests_total{status="success"}[5m])
/ (rate(ai_requests_total{status="success"}[5m]) + rate(ai_requests_total{status="error"}[5m]))

Latence P95 par provider
histogram_quantile(0.95, rate(ai_request_latency_seconds_bucket[5m]))

TTFB P50
histogram_quantile(0.5, rate(ai_request_ttfb_seconds_bucket[5m]))

Providers avec circuit breaker ouvert
ai_circuit_breaker_state == 2

Rate-limits par heure
increase(ai_429_total[1h])

Débit moyen tokens/sec
rate(ai_tokens_per_second_sum[5m]) / rate(ai_tokens_per_second_count[5m])

---

5. Dashboards Grafana

Grafana est accessible à l'adresse interne du cluster. AISIA fournit 11 dashboards pré-configurés couvrant tous les aspects de l'observabilité.

Dashboards principaux

Dashboard	Contenu
Overview AISIA	Vue d'ensemble : requêtes/sec, latence, taux erreurs, providers actifs
Provider Performance	Comparaison détaillée : latence, TTFB, débit, taux de succès
Routing Analytics	Décisions du bandit, distribution des choix, exploration vs exploitation
Circuit Breakers	État des circuit breakers par provider, historique des transitions
Error Analysis	Répartition des erreurs par code HTTP, providers les plus instables
Local-First	Performance des modèles locaux, taux de confiance, fallback cloud
Cluster Health	Santé des 21 noeuds, CPU, mémoire, disque, réseau
Learning Loop	Propositions générées, paires d'entraînement, qualité moyenne
Bot Activity	Cycles du bot, modèles testés, erreurs détectées
Billing	Coûts estimés par jour/provider/utilisateur
RGPD Compliance	Purges exécutées, consentements, exports demandés

Variables de dashboard

Les dashboards utilisent des variables Grafana pour le filtrage interactif :

$provider : filtre par provider (multi-valeur)
$interval : intervalle d'agrégation (1m, 5m, 15m, 1h)
$status : filtre par statut (success, error, all)

---

6. Routage bandit : interprétation des scores

Algorithme UCB1

La formule UCB1 utilisée par AISIA :

score_i = mean_reward_i + exploration_bonus * sqrt(ln(total_pulls) / pulls_i) + cost_bonus + latency_bonus

Où :

mean_reward_i = récompense moyenne du provider i (entre 0 et 1)
exploration_bonus = sqrt(2) par défaut (configurable via BANDIT_EXPLORATION_BONUS)
total_pulls = nombre total de requêtes sur tous les providers
pulls_i = nombre de requêtes envoyées au provider i
cost_bonus = max(0, 1.0 - cost/10.0) * cost_weight (défaut cost_weight=0.1)
latency_bonus = max(0, 1.0 - avg_latency/30.0) * latency_weight (défaut latency_weight=0.15)

Interprétation des scores UCB1

Composante	Plage	Signification
Mean reward	0.0 - 1.0	Qualité historique du provider
Exploration term	>0	Plus élevé = moins exploré, mérite plus d'essais
Cost bonus	0.0 - 0.1	Avantage des providers économiques
Latency bonus	0.0 - 0.15	Avantage des providers rapides

Un provider inexploré (pulls=0) est toujours sélectionné en priorité pour garantir l'exploration initiale.

Algorithme Thompson Sampling

sample_i ~ Beta(alpha_i, beta_i)

alpha = nombre de succès + 1 (initialisé à 1.0)
beta = nombre d'échecs + 1 (initialisé à 1.0)
Un succès est défini par reward >= 0.5

L'échantillonnage Thompson est naturellement plus exploratoire que UCB1 et converge plus rapidement vers le meilleur provider dans les cas à forte variance.

Consulter les statistiques bandit

GET /admin/bandit/stats

Retourne pour chaque provider :

pulls : nombre de requêtes
mean_reward : récompense moyenne
alpha / beta : paramètres de la distribution Beta

Cost-aware routing

Coûts approximatifs utilisés pour le routage (USD par million de tokens) :

Provider	Coût/1M tokens
Cerebras	$0.20
Groq	$0.30
DeepSeek	$0.50
DeepInfra	$0.60
Together	$0.80
Fireworks	$0.90
Cohere	$1.00
Perplexity	$1.00
Gemini	$1.25
AI21	$1.50
Mistral	$2.00
OpenRouter	$3.00
OpenAI	$5.00
Anthropic	$8.00

Latency-aware routing

La latence moyenne est calculée par Exponential Moving Average (EMA) :

new_avg_lat = avg_lat  0.8 + last_latency  0.2

Cette moyenne lissée donne plus de poids aux mesures récentes tout en conservant la mémoire des performances passées.

---

7. Circuit breaker : diagnostic

Chaque provider dispose d'un circuit breaker async-safe avec état persisté dans Redis.

États et transitions

CLOSED (normal) --> OPEN (trop d'echecs) --> HALF_OPEN (test) --> CLOSED

État	Comportement	Valeur Prometheus
CLOSED	Requêtes normales, compteur d'échecs décrémenté à chaque succès	0
OPEN	Toutes les requêtes sont bloquées pendant `timeout_s`	2
HALF_OPEN	Permet `half_open_max_calls` appels de test	1

Paramètres par défaut

Paramètre	Variable	Défaut	Description
Seuil d'échecs	`CB_FAILURE_THRESHOLD`	5	Nombre d'échecs avant ouverture
Timeout	`CB_TIMEOUT_S`	60	Durée en secondes de l'état OPEN
Max appels half-open	`CB_HALF_OPEN_MAX_CALLS`	3	Succès requis pour fermer

Diagnostic

# Providers avec circuit ouvert
ai_circuit_breaker_state == 2

Historique des transitions
changes(ai_circuit_breaker_state[1h])

---

8. Domain routing : analyse par domaine

AISIA détecte automatiquement le domaine d'une requête parmi 15 spécialisations et oriente vers les modèles les plus adaptés.

Domaines détectés

Domaine	Patterns détectés (exemples)
math	calcul, équation, dérivée, intégrale, matrice, probabilité
coding	code, function, class, python, javascript, algorithme, debug
reasoning	raisonne, explique pourquoi, analyse complexe, step by step
image	genere image, dessine, illustre, stable diffusion
voice	text to speech, synthèse vocale, voix
transcription	transcrire, speech to text, whisper
translation	traduis, traduction, en anglais, en français
vision	cette image, décris image, OCR
embedding	embed, vectorise, similarity, semantic search
medical	médical, diagnostic, symptôme, patient
finance	financ, bourse, stock, trading, investissement
science	physique, chimie, biologie, molécule
classification	classifie, catégorise, label, spam, toxic
sentiment	sentiment, opinion, positif négatif, satisfaction
legal	juridique, contrat, réglementation, RGPD, droit

Mécanisme de routage

1. Le DomainRouter analyse le prompt avec des regex compilées 2. Si un domaine est détecté (>=1 match), il filtre les providers ayant le champ specialized correspondant dans providers.yaml 3. Si des spécialistes existent, le BanditRouter choisit parmi eux 4. Sinon, fallback sur les généralistes

---

9. Scoring et reward

Le module scoring.py calcule la récompense (reward) après chaque appel LLM. Cette récompense alimente le BanditRouter.

Le reward est un float entre 0 et 1, calculé à partir de :

Succès de la requête (status HTTP 200)
Latence relative (plus rapide = meilleur score)
Présence de contenu dans la réponse
Respect du timeout

Un reward >= 0.5 est considéré comme un succès pour Thompson Sampling.

---

10. Boucle d'apprentissage

La boucle d'apprentissage (LearningLoop) collecte les meilleures réponses et les stocke dans Qdrant pour améliorer continuellement le système.

Paramètres

Variable	Défaut	Description
`LEARNING_LOOP_ENABLED`	true	Active la boucle
`LEARNING_LOOP_POLL_INTERVAL_S`	60	Intervalle de vérification
`LEARNING_TRIGGER_EVERY_N`	100	Déclenche après N requêtes
`MIN_DATASET_SIZE_FOR_TRAINING`	50	Taille minimale pour entraînement
`MIN_QUALITY_SCORE_FOR_TRAINING`	0.6	Score qualité minimal

Métriques associées

# Propositions par type
ai_learning_proposals_total

Paires d'entrainement en attente
(via API admin)
GET /admin/learning/status

---

11. Requêtes analytiques avancées

Analyse comparative multi-providers

# Comparer 3 providers sur le meme prompt
curl -X POST https://aisia.fr/v1/invoke \
  -H "Authorization: Bearer TOKEN" \
  -d '{
    "input": {"prompt": "Explique la photosynthese"},
    "routing_hints": {"provider_id": "openai"}
  }'
Repeter avec provider_id: "anthropic" et "gemini"

Export pour analyse Python

import pandas as pd
import requests

Télécharger les résultats CSV
resp = requests.get(
    "https://aisia.fr/v1/export?format=csv",
    headers={"Authorization": "Bearer TOKEN"}
)
df = pd.read_csv(pd.io.common.StringIO(resp.text))

Analyse de latence par provider
print(df.groupby("provider_id")["latency_ms"].describe())

Taux de succès
print(df.groupby("provider_id")["status"].value_counts(normalize=True))

Corrélation latence / qualité

Pour analyser si les providers les plus rapides produisent des réponses de moindre qualité, croisez les métriques de latence avec les scores de reward du bandit.

---

12. Bonnes pratiques

Pour le benchmarking

1. Exécutez des runs suffisamment longs (>50 requêtes par provider) pour obtenir des résultats statistiquement significatifs. 2. Variez les catégories de prompts : math, coding, creative, factual, translation. 3. Testez à différentes heures pour capturer les variations de charge des providers. 4. Exportez en XLSX pour les rapports : la feuille de résumé est prête à l'emploi.

Pour le monitoring

1. Configurez des alertes Grafana sur : - ai_circuit_breaker_state == 2 (circuit ouvert) - Taux d'erreur > 10% sur 5 minutes - Latence P95 > 10 secondes 2. Surveillez le rate limiting : increase(ai_429_total[1h]) > 50 3. Vérifiez le bot : s'assurer qu'il complète ses cycles régulièrement.

Pour le routage

1. Laissez le bandit explorer au début (les providers inexplorés sont priorisés). 2. Ajustez BANDIT_EXPLORATION_BONUS : augmenter pour plus d'exploration, diminuer pour plus d'exploitation du meilleur provider connu. 3. Activez Thompson Sampling (BANDIT_STRATEGY=thompson) si vous avez beaucoup de providers avec des performances proches.

---

Document AISIA v4.21.0