00 设置

工作坊资料在公开的 langfuse/langfuse-workshop 仓库中维护。使用该仓库获取可运行的应用、检查点分支和本地设置。

查看此 Markdown 文件

学习者指南：00 设置

讲师笔记

• 使用 checkpoint/00-setup 作为稳定的基础应用检查点。它应该等同于 checkpoint/01-base-app，而不是完整的参考应用。
• main 包含完整的参考实现，但学习者应该使用检查点，以便设置和基础应用定向共享相同的起始状态。
• 让学习者确认两个本地服务：Vite 在 127.0.0.1:3333，Express API 在 127.0.0.1:8787/api/health 或 127.0.0.1:8787/api/support-context。
• 强调欧盟 Langfuse 主机值：LANGFUSE_BASE_URL=https://cloud.langfuse.com。
• Node 服务器和帮助程序脚本加载仓库 .env 并启用覆盖，所以来自另一个本地项目的旧导出 LANGFUSE_*、OPENAI_* 或 DATASET_NAME 值不会赢。当学习者需要切换密钥或项目时，让他们编辑 .env。
• 不要在此处预加载 项目设置 → LLM 连接。学习者在 04-monitoring 中配置默认评估器模型，当 LLM 作为评判的评估器首次变得相关时。
• 保持密钥处理明确：真实 API 密钥只进入 .env 或 Langfuse 秘密字段，永远不进入共享的代码记录、笔记或聊天。
• 在成功进行一次聊天对话后，让学习者切换到 checkpoint/02-tracing 进行第一次构建步骤。

注意事项

• 缺少 .env 值。应用可能会渲染，而模型调用失败。
• Node 旧于 ^20.19.0 || >=22.12.0。值得在房间中进行 node -v 检查，然后有人运行 npm install，因为 npm 默认跳过 Vite 的可选原生二进制，失败只在 npm run dev 内部才会出现。之后升级的学习者需要 npm ci，而不仅仅是重启。
• 人们在开发中检查 127.0.0.1:8787/。API 服务器在该端口上运行，但浏览器应用由 Vite 在 127.0.0.1:3333 上提供，所以使用 API 路由进行服务器检查。它还隐藏了一个崩溃的 Vite：concurrently 保持 API 服务器启动，8787/ 回答 ENOENT ... dist/index.html。
• 学习者编辑 shell 导出而不是 .env。工作坊有意将 .env 视为 Node 端的真实来源。
• 人们在初始设置期间期望评估器设置。应用可以在 Langfuse 端 LLM 连接存在之前正确运行和追踪。
• 人们期望在 checkpoint/00-setup 或 checkpoint/01-base-app 上进行追踪。两者都有意未追踪；追踪只在 02-tracing 编辑之后才开始。
• 人们留在 main 进行追踪。main 已经是完成的参考实现。