00 Configuración

El material del workshop se mantiene en el repositorio público langfuse/langfuse-workshop. Usa el repositorio para ejecutar la aplicación, acceder a las ramas de checkpoint y realizar la configuración local.

Ver este archivo Markdown

Guía del participante: 00 Configuración

Notas para el instructor

• Usa checkpoint/00-setup como checkout estable de la aplicación base. Debe ser equivalente a checkpoint/01-base-app, no a la aplicación de referencia completa.
• main contiene la implementación de referencia completa, pero los participantes deben usar el checkpoint para que la configuración y la orientación por la aplicación base partan del mismo estado.
• Haz que confirmen ambos servicios locales: Vite en 127.0.0.1:3333 y la API de Express en 127.0.0.1:8787/api/health o 127.0.0.1:8787/api/support-context.
• Destaca el valor del host europeo de Langfuse: LANGFUSE_BASE_URL=https://cloud.langfuse.com.
• El servidor Node y los scripts auxiliares cargan el .env del repositorio con override activado, de modo que valores antiguos de LANGFUSE_*, OPENAI_* o DATASET_NAME exportados por otro proyecto no prevalecen. Indica que deben editar .env al cambiar claves o proyectos.
• No anticipes Project Settings → LLM Connections. El modelo predeterminado de evaluación se configura en 04-monitoring, cuando los evaluadores LLM-as-a-judge pasan a ser relevantes.
• Sé explícito con las claves: las claves reales de API solo van en .env o en campos secretos de Langfuse, nunca en conversaciones, notas o chats compartidos.
• Después de un turno de chat correcto, haz que cambien a checkpoint/02-tracing para el primer paso de implementación.

Presta atención

• Valores ausentes en .env. La aplicación puede renderizar aunque fallen las llamadas al modelo.
• Node anterior a ^20.19.0 || >=22.12.0. Conviene ejecutar node -v antes de npm install: npm omite silenciosamente el binario nativo opcional de Vite y el fallo solo aparece después en npm run dev. Quien actualice Node después necesita ejecutar npm ci, no solo reiniciar.
• Personas que prueben 127.0.0.1:8787/ en desarrollo. La API usa ese puerto, pero Vite sirve la aplicación web en 127.0.0.1:3333; utiliza una ruta de API para comprobar el servidor. Esto también evita ocultar un Vite caído: concurrently mantiene la API activa y 8787/ responde con ENOENT ... dist/index.html.
• Participantes que editen exports del shell en vez de .env. El workshop considera .env intencionadamente la fuente de verdad de Node.
• Personas que esperen configurar evaluadores durante la preparación inicial. La aplicación puede ejecutarse y crear traces antes de que exista una conexión LLM en Langfuse.
• Personas que esperen traces en checkpoint/00-setup o checkpoint/01-base-app. Ambos están intencionadamente sin tracing; comienza solo tras los cambios de 02-tracing.
• Personas que permanezcan en main para implementar tracing. main ya contiene la referencia terminada.