00 Configuration

Faites fonctionner l’application du workshop localement avec les identifiants OpenAI et Langfuse. Vous pourrez ensuite parcourir 01-base-app et commencer à construire dans 02-tracing.

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

Objectif

Faites fonctionner l’application du workshop localement avec les identifiants OpenAI et Langfuse. Vous pourrez ensuite parcourir 01-base-app et commencer à construire dans 02-tracing.

Prérequis

Node.js ^20.19.0 || >=22.12.0 — vérifiez avec node -v et mettez à niveau avant l’installation si votre version est inférieure (nvm install 22, ou l’équivalent pour asdf, fnm ou volta).

Une ancienne version échoue d’une manière facile à mal interpréter. Le binaire Vite propre à la plateforme est une dépendance facultative ; npm l’ignore donc sans signaler d’erreur : npm install semble réussir et le problème n’apparaît que plus tard, lorsque npm run dev ne peut pas démarrer Vite. Si vous mettez Node à niveau après l’installation, relancez npm ci pour récupérer le binaire ignoré.

Point de départ

Clonez le dépôt du workshop, entrez dans le répertoire, puis faites un checkout du checkpoint de configuration de ce chapitre :

git clone https://github.com/langfuse/langfuse-workshop.git
cd langfuse-workshop
git checkout checkpoint/00-setup

Ce checkpoint contient volontairement la même application de base sans tracing que checkpoint/01-base-app. Utilisez-le pour confirmer vos clés API, dépendances et ports locaux avant de passer aux chapitres de construction. Les clés Langfuse sont configurées maintenant, mais les traces ne commencent qu’après l’ajout de l’instrumentation dans 02-tracing.

Étape 1 — Obtenir les clés API

OpenAI — accédez à platform.openai.com → API Keys → créez-en une. Copiez la valeur sk-....
Langfuse — inscrivez-vous sur langfuse.com dans la région EU, créez un projet et copiez les clés publique et secrète depuis Settings → API Keys.

Étape 2 — Installer la skill et la CLI Langfuse

Les modules suivants pilotent Langfuse au moyen d’un agent de programmation, qui a besoin de la skill langfuse et de la CLI Langfuse.

Collez cette instruction dans votre agent pour installer les deux :

« Installe la skill langfuse depuis https://github.com/langfuse/skills/tree/main/skills/langfuse, puis installe la CLI Langfuse avec npm install -g langfuse-cli. »

Si vous préférez les installer vous-même :

# Langfuse CLI
npm install -g langfuse-cli

# Langfuse Skill:
npx skills add langfuse/skills --skill "langfuse"

Étape 3 — Configurer `.env`

cp .env.example .env

Renseignez :

OPENAI_API_KEY=sk-...
LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_BASE_URL=https://cloud.langfuse.com

Laissez les autres valeurs par défaut inchangées.

L’application charge toujours le fichier .env de ce dépôt pour le serveur et les scripts auxiliaires. Les valeurs LANGFUSE_*, OPENAI_* ou DATASET_NAME exportées dans votre shell par un autre projet ne remplacent pas ce fichier. Pour changer la configuration du workshop, modifiez .env.

Conservez ces valeurs uniquement dans votre .env local. Ne collez jamais de véritables clés API dans des notes, transcriptions, captures d’écran ou chats partagés.

Étape 4 — Installer et exécuter

npm install
npm run dev

Ouvrez http://127.0.0.1:3333.

Pour vérifier le serveur séparément, consultez http://127.0.0.1:8787/api/health ou http://127.0.0.1:8787/api/support-context. Pendant npm run dev, 127.0.0.1:8787/ n’est pas l’URL principale de l’application.

Si rien ne se charge sur 127.0.0.1:3333, remontez la sortie de npm run dev jusqu’aux lignes [dev:client]. concurrently maintient l’API en activité même si Vite s’est arrêté ; le terminal semble donc toujours actif. Ouvrir 127.0.0.1:8787/ dans cet état renvoie ENOENT ... dist/index.html, ce qui signifie seulement que le build de production est absent et n’explique pas l’échec réel. Une erreur Cannot find native binding dans les lignes [dev:client] indique la version de Node ; consultez les Prérequis.

Étape 5 — Confirmer ce qui s’affiche

Vous devriez voir le chat Dad IT Support Agent :

la mascotte Specs en haut
un message d’accueil de Specs
des suggestions sous le message d’accueil
le panneau iPhone à droite ("Dad" + détails de l’iPhone 15)

Comment Specs traite une demande : un agent, deux outils, un modèle et chaque étape sous forme d’observation dans le trace.

Comment vérifier que vous avez terminé

npm run dev fonctionne et écoute sur http://127.0.0.1:3333 (client) et http://127.0.0.1:8787 (serveur API).
http://127.0.0.1:8787/api/health ou http://127.0.0.1:8787/api/support-context renvoie une véritable réponse.
Le navigateur affiche le message d’accueil de Specs, pas une erreur.
L’envoi d’une suggestion produit une véritable réponse du modèle à propos de l’iPhone.

État final

Votre environnement est prêt. Pour construire le workshop pas à pas, parcourez 01-base-app si vous souhaitez découvrir l’application, puis faites un checkout de checkpoint/02-tracing pour les premières modifications de code.