00 设置

让研讨会应用在本地运行，并配置 OpenAI 和 Langfuse 凭证。从这里你可以浏览 01-base-app，然后开始在 02-tracing 中构建。

研讨会材料在公共 langfuse/langfuse-workshop 存储库中维护。使用存储库获取可运行的应用、检查点分支和本地设置。

目标

让研讨会应用在本地运行，并配置 OpenAI 和 Langfuse 凭证。从这里你可以浏览 01-base-app，然后开始在 02-tracing 中构建。

先决条件

Node.js ^20.19.0 || >=22.12.0 — 使用 node -v 检查并在低于该版本时升级（nvm install 22，或等效的 asdf、fnm 或 volta）。

旧版本会以容易被误解的方式失败。Vite 的平台特定二进制是可选依赖，所以 npm 会跳过它 不报告错误：npm install 看起来成功了，问题只在 npm run dev 无法启动 Vite 时才出现。如果在安装后升级了 Node，请重新运行 npm ci 以获取被跳过的二进制。

起点

克隆研讨会存储库，进入它，然后检出本章的设置检查点：

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

此检查点故意包含与 checkpoint/01-base-app 相同的无跟踪基础应用。使用它来确认你的 API 密钥、依赖和本地端口在切换到构建章节前有效。Langfuse 密钥现在已配置，但跟踪仅在你在 02-tracing 中添加检测后才开始。

步骤 1 — 获取 API 密钥

OpenAI — platform.openai.com → API Keys → 创建一个。复制 sk-... 值。
Langfuse — 在 langfuse.com 上的 EU 区域 注册，创建一个项目，并从 Settings → API Keys 复制公钥和私钥。

步骤 2 — 安装 Langfuse 技能和 CLI

后续模块通过编码代理驱动 Langfuse，需要 langfuse 技能和 Langfuse CLI。

将此粘贴到你的编码代理中以安装两者：

"请从 https://github.com/langfuse/skills/tree/main/skills/langfuse 安装 langfuse 技能，并使用 npm install -g langfuse-cli 安装 Langfuse CLI。"

更喜欢自己安装：

# Langfuse CLI
npm install -g langfuse-cli

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

步骤 3 — 配置 `.env`

cp .env.example .env

填写：

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

将其余默认值保持原样。

研讨会应用始终为服务器和帮助程序脚本加载此存储库的 .env 文件。如果你在 shell 中从另一个项目导出了 LANGFUSE_*、OPENAI_* 或 DATASET_NAME 值，它们不会覆盖此文件。要更改研讨会配置，请编辑 .env。

仅在你的本地 .env 中保留这些值。不要将真实的 API 密钥粘贴到共享的研讨会笔记、转录、屏幕截图或聊天消息中。

步骤 4 — 安装和运行

npm install
npm run dev

打开 http://127.0.0.1:3333。

如果你想单独验证服务器，请检查 http://127.0.0.1:8787/api/health 或 http://127.0.0.1:8787/api/support-context。在 npm run dev 期间，127.0.0.1:8787/ 不是主应用 URL。

如果 127.0.0.1:3333 上没有加载任何内容，请将 npm run dev 输出向上滚动到 [dev:client] 行。concurrently 使 API 服务器在 Vite 崩溃时保持运行，所以终端看起来仍然活跃 — 在该状态下打开 127.0.0.1:8787/ 会返回 ENOENT ... dist/index.html，这仅意味着生产构建不存在，对实际失败没有说什么。这些 [dev:client] 行中的 Cannot find native binding 崩溃是 Node 版本；参见先决条件。

步骤 5 — 确认你看到的内容

你应该看到 Dad IT Support Agent 聊天：

顶部的 Specs 吉祥物
来自 Specs 的问候
问候下方的建议芯片
右侧的 iPhone 面板（"Dad" + iPhone 15 详情）

Specs 如何处理票证 — 一个代理、两个工具、一个模型，每一跳都是跟踪中的一个观测。

如何验证你已完成

npm run dev 运行并监听 http://127.0.0.1:3333（客户端）和 http://127.0.0.1:8787（API 服务器）。
http://127.0.0.1:8787/api/health 或 http://127.0.0.1:8787/api/support-context 返回真实响应。
浏览器显示 Specs 问候，而不是错误。
发送其中一个建议芯片会从模型返回真实的 iPhone 答案。

最终状态

你的环境已就绪。要逐步构建研讨会，如果需要应用演示请浏览 01-base-app，然后检出 checkpoint/02-tracing 以进行首次代码更改。

目标