00 Configuração

O material do workshop é mantido no repositório público langfuse/langfuse-workshop. Use o repositório para executar a aplicação, acessar os branches de checkpoint e fazer a configuração local.

Ver este arquivo Markdown

Guia do participante: 00 Configuração

Notas para o instrutor

• Use checkpoint/00-setup como checkout estável da aplicação base. Ele deve ser equivalente a checkpoint/01-base-app, não à aplicação de referência completa.
• main contém a implementação de referência completa, mas os participantes devem usar o checkpoint para que a configuração e a orientação pela aplicação base partam do mesmo estado.
• Peça aos participantes que confirmem os dois serviços locais: Vite em 127.0.0.1:3333 e a API Express em 127.0.0.1:8787/api/health ou 127.0.0.1:8787/api/support-context.
• Destaque o valor do host europeu do Langfuse: LANGFUSE_BASE_URL=https://cloud.langfuse.com.
• O servidor Node e os scripts auxiliares carregam o .env do repositório com override habilitado, então valores antigos de LANGFUSE_*, OPENAI_* ou DATASET_NAME exportados por outro projeto não prevalecem. Oriente os participantes a editar .env ao trocar chaves ou projetos.
• Não antecipe Project Settings → LLM Connections aqui. O modelo padrão de avaliação será configurado em 04-monitoring, quando avaliadores LLM-as-a-judge se tornarem relevantes.
• Seja explícito sobre as chaves: chaves reais de API ficam apenas em .env ou nos campos secretos do Langfuse, nunca em conversas, anotações ou chats compartilhados.
• Depois de um turno de chat bem-sucedido, peça que mudem para checkpoint/02-tracing para a primeira etapa de implementação.

Fique atento

• Valores ausentes em .env. A aplicação pode renderizar mesmo com falha nas chamadas ao modelo.
• Node anterior a ^20.19.0 || >=22.12.0. Vale executar node -v antes de npm install: o npm ignora silenciosamente o binário nativo opcional do Vite e a falha só aparece depois em npm run dev. Quem atualizar o Node depois precisa executar npm ci, não apenas reiniciar.
• Pessoas testando 127.0.0.1:8787/ em desenvolvimento. A API usa essa porta, mas a aplicação web é servida pelo Vite em 127.0.0.1:3333; use uma rota de API para verificar o servidor. Isso também evita esconder um Vite encerrado: concurrently mantém a API de pé, e 8787/ responde com ENOENT ... dist/index.html.
• Participantes editando exports do shell em vez de .env. O workshop trata .env intencionalmente como fonte da verdade do Node.
• Pessoas esperando configurar avaliadores durante a preparação inicial. A aplicação pode executar e criar traces antes de existir uma conexão LLM no Langfuse.
• Pessoas esperando traces em checkpoint/00-setup ou checkpoint/01-base-app. Ambos são intencionalmente sem tracing; ele começa somente após as edições de 02-tracing.
• Pessoas permanecendo em main para implementar tracing. main já é a referência concluída.