00 Configuration

Le contenu du workshop est maintenu dans le dépôt public langfuse/langfuse-workshop. Utilisez ce dépôt pour exécuter l’application, accéder aux branches de checkpoint et effectuer la configuration locale.

Afficher ce fichier Markdown

Guide du participant : 00 Configuration

Notes pour le formateur

• Utilisez checkpoint/00-setup comme checkout stable de l’application de base. Il doit être équivalent à checkpoint/01-base-app, et non à l’application de référence complète.
• main contient l’implémentation de référence complète, mais les participants doivent utiliser le checkpoint afin que la configuration et la prise en main partent du même état.
• Faites confirmer les deux services locaux : Vite sur 127.0.0.1:3333 et l’API Express sur 127.0.0.1:8787/api/health ou 127.0.0.1:8787/api/support-context.
• Insistez sur la valeur de l’hôte européen Langfuse : LANGFUSE_BASE_URL=https://cloud.langfuse.com.
• Le serveur Node et les scripts chargent le .env du dépôt avec l’override activé ; d’anciennes valeurs LANGFUSE_*, OPENAI_* ou DATASET_NAME exportées par un autre projet ne doivent donc pas prévaloir. Demandez aux participants de modifier .env lorsqu’ils changent de clés ou de projet.
• N’anticipez pas Project Settings → LLM Connections. Les participants configurent le modèle d’évaluation par défaut dans 04-monitoring, lorsque les évaluateurs LLM-as-a-judge deviennent pertinents.
• Soyez explicite sur les clés : les véritables clés API vont uniquement dans .env ou dans les champs secrets de Langfuse, jamais dans des conversations, notes ou chats partagés.
• Après un tour de chat réussi, demandez de passer à checkpoint/02-tracing pour la première étape d’implémentation.

Points d’attention

• Des valeurs manquantes dans .env. L’application peut s’afficher alors que les appels au modèle échouent.
• Une version de Node antérieure à ^20.19.0 || >=22.12.0. Exécutez node -v avant npm install : npm ignore silencieusement le binaire natif facultatif de Vite et l’échec n’apparaît que plus tard dans npm run dev. Après une mise à niveau, il faut exécuter npm ci, pas seulement redémarrer.
• Les personnes qui testent 127.0.0.1:8787/ en développement. L’API utilise ce port, mais Vite sert l’application web sur 127.0.0.1:3333 ; utilisez une route API pour vérifier le serveur. Cela évite aussi de masquer un Vite arrêté : concurrently garde l’API active et 8787/ répond ENOENT ... dist/index.html.
• Les participants qui modifient les exports du shell plutôt que .env. Le workshop considère volontairement .env comme la source de vérité côté Node.
• Les personnes qui s’attendent à configurer les évaluateurs dès l’installation. L’application peut fonctionner et tracer correctement avant la création d’une connexion LLM côté Langfuse.
• Les personnes qui attendent des traces sur checkpoint/00-setup ou checkpoint/01-base-app. Ces deux checkpoints sont volontairement non tracés ; le tracing commence uniquement après les modifications de 02-tracing.
• Les personnes qui restent sur main pour le tracing. main est déjà l’implémentation de référence terminée.