08 Chat e Langfuse

Material do facilitador correspondente à lição 08 Chat e Langfuse do participante.

Cronograma

Cerca de 15 minutos. A chave de LLM usada em tempo de execução e as chaves do Langfuse já estão no .env.workshop desde o módulo 00; portanto, este módulo consiste principalmente em reiniciar o back-end e fazer o tour dos traces.

Roteiro de apresentação

• O painel de chat visto no módulo 02 passa a funcionar de verdade, e cada interação é rastreada.
• Mostre um trace no projetor: prompt, conclusão, tokens e custo.

Falhas comuns

• OPENAI_API_KEY ausente; POST /api/chat retorna 503 com uma orientação de configuração (o restante do aplicativo não é afetado). Uma chave sem créditos causa erro na chamada ao modelo.
• Região incorreta em LANGFUSE_BASE_URL (https://us.cloud.langfuse.com em vez de https://cloud.langfuse.com, ou vice-versa), portanto os traces não aparecem.
• O back-end não foi reiniciado depois do preenchimento do .env.workshop.
• O ensaio em ambiente limpo de julho de 2026 abrangeu este módulo; os modos de falha, tempos e etapas com intervenção humana foram validados nesse ensaio.

Etapas de redefinição

• Forneça uma chave de LLM de reserva com limite de gastos.
• Preencha novamente OPENAI_API_KEY / LLM_MODEL / LLM_BASE_URL e os três valores LANGFUSE_* no .env.workshop e execute docker compose --env-file .env.workshop -f docker-compose.workshop.yml -f docker-compose.otel.yml up -d --build backend para que a telemetria do ClickStack permaneça ativada.