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과 같은 추적되지 않은 기본 앱을 포함합니다. 02-tracing에서 계측을 추가한 후에만 트레이스가 시작되기 전에 API 키, 종속성 및 로컬 포트가 작동하는지 확인하는 데 사용하세요. Langfuse 키는 지금 구성되지만 추적은 시작되지 않습니다.

1단계 — API 키 가져오기

OpenAI — platform.openai.com → API Keys → 새로 만들기. sk-... 값을 복사합니다.
Langfuse — langfuse.com에서 EU 지역에 가입하고, 프로젝트를 만들고, Settings → API Keys에서 공개 + 비공개 키를 복사합니다.

2단계 — Langfuse 스킬 및 CLI 설치

이후 모듈은 langfuse 스킬과 Langfuse CLI가 필요한 코딩 에이전트를 통해 Langfuse를 구동합니다.

이것을 코딩 에이전트에 붙여넣으세요:

"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 파일을 서버 및 도우미 스크립트에 로드합니다. 다른 프로젝트에서 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은 Vite가 충돌했을 때도 API 서버를 계속 실행하므로 터미널은 여전히 살아있는 것 같습니다 — 그리고 그 상태에서 127.0.0.1:8787/을 열면 ENOENT ... dist/index.html로 응답하며, 이는 프로덕션 빌드가 없다는 뜻일 뿐이며 실제 실패에 대해서는 아무것도 말하지 않습니다. 그 Cannot find native binding 줄의 [dev:client] 충돌은 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을 확인하세요.

목표