00 Penyiapan

Miliki aplikasi workshop berjalan secara lokal dengan kredensial OpenAI dan Langfuse. Dari sini Anda dapat mengintip 01-base-app, kemudian mulai membangun di 02-tracing.

Materi workshop dikelola di repositori publik langfuse/langfuse-workshop. Gunakan repositori untuk aplikasi yang dapat dijalankan, cabang checkpoint, dan setup lokal.

Lihat file Markdown ini

Tujuan

Miliki aplikasi workshop berjalan secara lokal dengan kredensial OpenAI dan Langfuse di tempat. Dari sini Anda dapat mengintip 01-base-app, kemudian mulai membangun di 02-tracing.

Prasyarat

Node.js ^20.19.0 || >=22.12.0 — periksa dengan node -v dan tingkatkan sebelum menginstal jika Anda di bawahnya (nvm install 22, atau yang setara untuk asdf, fnm, atau volta).

Versi yang lebih lama gagal dengan cara yang mudah disalahpahami. Biner khusus platform Vite adalah dependensi opsional, jadi npm melompatinya tanpa melaporkan kesalahan: npm install terlihat seperti berhasil, dan masalahnya hanya muncul kemudian ketika npm run dev tidak dapat memulai Vite. Jika Anda meningkatkan Node setelah menginstal, jalankan kembali npm ci agar biner yang dilompati diambil.

Titik awal

Klon repositori workshop, masukkan, kemudian periksa checkpoint setup untuk bab ini:

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

Checkpoint ini sengaja berisi aplikasi dasar yang tidak terlacak sama seperti checkpoint/01-base-app. Gunakan untuk mengonfirmasi bahwa kunci API, dependensi, dan port lokal Anda berfungsi sebelum beralih ke bab pembuatan. Kunci Langfuse dikonfigurasi sekarang, tetapi jejak dimulai hanya setelah Anda menambahkan instrumentasi di 02-tracing.

Langkah 1 — Dapatkan kunci API

OpenAI — platform.openai.com → API Keys → buat satu. Salin nilai sk-....
Langfuse — daftar di langfuse.com di wilayah EU, buat proyek, dan salin kunci publik + rahasia dari Settings → API Keys.

Langkah 2 — Pasang keterampilan Langfuse dan CLI

Modul nanti mendorong Langfuse melalui agen pengodean, yang membutuhkan keterampilan langfuse dan CLI Langfuse.

Tempel ini ke agen pengodean Anda untuk memasang keduanya:

"Silakan pasang keterampilan langfuse dari https://github.com/langfuse/skills/tree/main/skills/langfuse, dan pasang CLI Langfuse dengan npm install -g langfuse-cli."

Lebih suka memasangnya sendiri:

# Langfuse CLI
npm install -g langfuse-cli

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

Langkah 3 — Konfigurasi `.env`

cp .env.example .env

Isi:

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

Biarkan sisa default seperti adanya.

Aplikasi workshop selalu memuat file .env repositori ini untuk server dan skrip pembantu. Jika Anda memiliki nilai LANGFUSE_*, OPENAI_*, atau DATASET_NAME yang diekspor dalam shell Anda dari proyek lain, nilai tersebut tidak akan menimpa file ini. Untuk mengubah konfigurasi workshop, edit .env.

Simpan nilai ini dalam .env lokal Anda saja. Jangan tempel kunci API nyata ke dalam catatan workshop bersama, transkrip, tangkapan layar, atau pesan chat.

Langkah 4 — Pasang dan jalankan

npm install
npm run dev

Buka http://127.0.0.1:3333.

Jika Anda ingin memverifikasi server secara terpisah, periksa http://127.0.0.1:8787/api/health atau http://127.0.0.1:8787/api/support-context. Selama npm run dev, 127.0.0.1:8787/ bukanlah URL aplikasi utama.

Jika tidak ada yang dimuat di 127.0.0.1:3333, gulir output npm run dev kembali ke baris [dev:client]. concurrently membuat server API tetap berjalan bahkan ketika Vite macet, jadi terminal masih terlihat hidup — dan membuka 127.0.0.1:8787/ dalam status itu menjawab dengan ENOENT ... dist/index.html, yang hanya berarti build produksi tidak ada dan tidak mengatakan apa pun tentang kegagalan sebenarnya. Kecelakaan Cannot find native binding dalam baris [dev:client] itu adalah versi Node; lihat Prasyarat.

Langkah 5 — Konfirmasi apa yang Anda lihat

Anda harus melihat chat Agen Dukungan IT Dad:

maskot Specs di bagian atas
salam dari Specs
chip saran di bawah salam
panel iPhone di sebelah kanan ("Dad" + detail iPhone 15)

Bagaimana Specs menangani tiket — satu agen, dua alat, satu model, setiap lompatan adalah pengamatan dalam jejak.

Cara memverifikasi Anda selesai

npm run dev berjalan dan mendengarkan di http://127.0.0.1:3333 (klien) dan http://127.0.0.1:8787 (server API).
http://127.0.0.1:8787/api/health atau http://127.0.0.1:8787/api/support-context mengembalikan respons nyata.
Browser menampilkan salam Specs, bukan kesalahan.
Mengirim salah satu chip saran mengembalikan jawaban iPhone nyata dari model.

Status akhir

Lingkungan Anda siap. Untuk membangun workshop langkah demi langkah, intip 01-base-app jika Anda menginginkan tur aplikasi, kemudian periksa checkpoint/02-tracing untuk perubahan kode pertama.