00 Configuration

Guide d'animation de la leçon 00 Configuration.

Avant la session — provisionner une clé partagée pour les participants (usage équitable)

Lors d'une session publique animée par un formateur, ne donnez pas votre clé OpenRouter personnelle — ni une clé sans plafond — à des inconnus. L'API de gestion (provisionnement) d'OpenRouter crée par programmation des clés dédiées avec un plafond strict de crédits, afin que la dépense de l'atelier reste limitée et équitable.

1. Créez une clé de gestion (une seule fois). OpenRouter → Settings → Management API Keys (openrouter.ai/settings/management-keys) → Create New Key. Elle peut créer, inspecter et supprimer d'autres clés, et dépenser sur votre compte ; traitez-la comme un identifiant administrateur.

export OPENROUTER_PROVISIONING_KEY=sk-or-v1-<management-key>   # instructor only — never share

2. Provisionnez la clé partagée avec un plafond strict. Le dépôt fournit l'utilitaire (scripts/provision_workshop_keys.py), qui appelle POST https://openrouter.ai/api/v1/keys :

# one shared key the whole room uses, capped at $20 total (reset daily at 00:00 UTC):
python -m scripts.provision_workshop_keys --name "Agent Arena $(date +%F)" --limit 20 --daily

La réponse de création affiche la chaîne de la clé une seule fois ; copiez-la et donnez-la aux participants comme OPENROUTER_API_KEY. Ensuite, seul son hash reste récupérable pour l'inspecter ou la supprimer. Vous préférez curl ? C'est le même appel :

curl -s https://openrouter.ai/api/v1/keys \
  -H "Authorization: Bearer $OPENROUTER_PROVISIONING_KEY" \
  -H "content-type: application/json" \
  -d '{"name":"Agent Arena workshop","limit":20}'

python -m scripts.provision_workshop_keys --name "Agent Arena $(date +%F)" --limit 2 --count 30

3. Surveillez et nettoyez. Consultez les dépenses pendant la session et supprimez les clés à la fin :

python -m scripts.provision_workshop_keys --list
python -m scripts.provision_workshop_keys --delete <keyHash>

Dimensionnement : les modèles appartiennent à la catégorie économique flash-lite et la grille ne compte que 6 × 3 = 18 configurations. Un plafond partagé de 20 $ couvre confortablement une salle entière exécutant l'Arena plusieurs fois ; c'est un garde-fou contre les boucles incontrôlées, pas un budget serré.

Timing

~25 à 30 minutes si les comptes existent déjà ; prévoyez plus pour leur création.

• 5 min — créer les trois comptes (OpenRouter, Langfuse Cloud et ClickHouse Cloud) si cela n'a pas été fait la veille.
• 5 min — cloner le dépôt, créer l'environnement virtuel et installer les dépendances.
• 5 min — renseigner .env.
• 5 min — exécuter source .env && scripts/arena.sh up et confirmer le dashboard sur http://localhost:5174.

Avant la session, ouvrez OpenRouter → Settings → Privacy → Data Policies → Zero Data Retention, désactivez Non-frontier (gris/désactivé), puis testez Qwen avec la clé participant. Qwen utilise l'endpoint sans ZDR d'Alibaba ; activer le ZDR non-frontier produit No endpoints available matching your guardrail restrictions and data policy même si Alibaba est autorisé et les guardrails assouplis. Ce réglage appartient au compte et ne peut pas être assoupli via l'API de gestion ou un paramètre de requête. Utilisez-le uniquement pour la charge synthétique de l'atelier et respectez les exigences de votre organisation pour les données réelles.

Fil conducteur

• Commencez par nommer les trois comptes — OpenRouter, ClickHouse Cloud et Langfuse Cloud — et dites clairement que Langfuse intervient dès le premier module, avant tout choix de modèle. Ce n'est pas un ajout de production au Module 03 : il exécutera la compétition et conservera les preuves pendant la publication, l'enquête et l'amélioration.
• Montrez le chemin de code partagé : agents/ est utilisé par eval/harness.py (benchmark) et serving/api.py (production), de sorte que ce qui est mesuré aujourd'hui correspond à ce qui sera publié au Module 03.
• Décrivez ce que fait scripts/arena.sh up : il crée la base arena, l'utilisateur en lecture seule arena_ro, génère les données e-commerce synthétiques dans ClickHouse, crée les vues v_*, puis démarre l'API et l'interface web du dashboard.
• Prévenez que l'onglet Leaderboard sera vide à la fin. C'est normal et prépare le Module 01.

Problèmes fréquents

• Placeholder OPENROUTER_API_KEY laissé à sk-or-... — le harness échouera avec 401 lors du premier appel de modèle au Module 01. Faites vérifier maintenant qu'une vraie clé se trouve dans .env.
• ARENA_RO_PASSWORD vide — scripts/arena.sh up crée tout de même arena_ro, mais la politique de mots de passe du service peut faire rejeter le client. Définissez n'importe quelle valeur non vide.
• Service ClickHouse Cloud encore en cours de provisionnement — un nouveau service peut mettre quelques minutes à accepter les connexions ; attendez et relancez scripts/arena.sh up.
• .env non chargé — exécutez source .env && scripts/arena.sh up sur la même ligne ; scripts/arena.sh up seul dans un nouveau shell échoue faute de variables CLICKHOUSE_CLOUD_*.
• Port 5174 (ou 8000) déjà utilisé — un ancien processus tourne encore. scripts/arena.sh stop nettoie les serveurs avant de répéter up.

Procédures de reprise

• Recréez tout avec source .env && scripts/arena.sh up. La commande est idempotente, n'utilise ni Aurora, ni ClickPipes, ni ClickStack, et recrée la base arena, l'utilisateur arena_ro, les données synthétiques et les vues v_*, puis redémarre l'API et l'interface. Les résultats du benchmark restent dans Langfuse.
• Si seuls les serveurs locaux sont bloqués, scripts/arena.sh stop suivi de scripts/arena.sh serve est plus rapide qu'un up complet.
• Vérifiez l'état avec scripts/arena.sh status : il affiche l'API, l'interface et le nombre de lignes de chaque vue v_*.
• Si .env contient encore des placeholders, obtenez la vraie clé ou le véritable identifiant, puis relancez scripts/arena.sh up.