00 Thiết lập

Tài liệu workshop được duy trì trong repository công khai langfuse/langfuse-workshop. Sử dụng repository cho ứng dụng có thể chạy được, các nhánh checkpoint, và cài đặt cục bộ.

Xem file Markdown này

Mục tiêu

Có ứng dụng workshop chạy cục bộ với cả hai thông tin xác thực OpenAI và Langfuse. Từ đây bạn có thể lướt qua 01-base-app, sau đó bắt đầu xây dựng trong 02-tracing.

Điều kiện tiên quyết

Node.js ^20.19.0 || >=22.12.0 — kiểm tra bằng node -v và nâng cấp trước khi cài đặt nếu bạn dưới nó (nvm install 22, hoặc tương đương cho asdf, fnm, hoặc volta).

Phiên bản cũ hơn thất bại theo cách dễ đọc sai. Tệp nhị phân dành riêng cho nền tảng của Vite là một phụ thuộc tùy chọn, vì vậy npm bỏ qua nó mà không báo cáo lỗi: npm install trông giống như nó thành công, và vấn đề chỉ xuất hiện sau khi npm run dev không thể khởi động Vite. Nếu bạn nâng cấp Node sau khi cài đặt, hãy chạy lại npm ci để lấy tệp nhị phân bị bỏ qua.

Điểm bắt đầu

Clone repository workshop, nhập vào nó, sau đó checkout checkpoint setup cho chương này:

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

Checkpoint này cố ý chứa cùng một ứng dụng cơ sở không được trace như checkpoint/01-base-app. Sử dụng nó để xác nhận rằng các khóa API, phụ thuộc và cổng cục bộ của bạn hoạt động trước khi chuyển sang các chương xây dựng. Các khóa Langfuse được cấu hình ngay bây giờ, nhưng các trace chỉ bắt đầu sau khi bạn thêm instrumentation trong 02-tracing.

Bước 1 — Lấy các khóa API

1. OpenAI — platform.openai.com → API Keys → tạo một cái. Sao chép giá trị sk-....
2. Langfuse — đăng ký tại langfuse.com trên khu vực EU, tạo một dự án, và sao chép các khóa công khai + bí mật từ Settings → API Keys.

Bước 2 — Cài đặt Langfuse skill và CLI

Các module sau sẽ điều khiển Langfuse thông qua một agent mã hóa, cần langfuse skill và Langfuse CLI.

Dán điều này vào agent mã hóa của bạn để cài đặt cả hai:

"Vui lòng cài đặt langfuse skill từ https://github.com/langfuse/skills/tree/main/skills/langfuse, và cài đặt Langfuse CLI bằng npm install -g langfuse-cli."

Thích cài đặt chúng yourself:

# Langfuse CLI
npm install -g langfuse-cli

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

Bước 3 — Cấu hình .env

cp .env.example .env

Fill in:

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

Giữ lại các mặc định còn lại như cũ.

Ứng dụng workshop luôn tải tệp .env của repository này cho máy chủ và các script helper. Nếu bạn có các giá trị LANGFUSE_*, OPENAI_*, hoặc DATASET_NAME được export trong shell của bạn từ một dự án khác, chúng sẽ không ghi đè tệp này. Để thay đổi cấu hình workshop, hãy chỉnh sửa .env.

Giữ các giá trị này trong .env cục bộ của bạn thôi. Không dán các khóa API thực vào ghi chú workshop được chia sẻ, bản ghi, ảnh chụp màn hình, hoặc tin nhắn chat.

Bước 4 — Cài đặt và chạy

npm install
npm run dev

Mở http://127.0.0.1:3333.

Nếu bạn muốn xác minh máy chủ riêng biệt, hãy kiểm tra http://127.0.0.1:8787/api/health hoặc http://127.0.0.1:8787/api/support-context.. Trong npm run dev, 127.0.0.1:8787/ không phải là URL ứng dụng chính.

Nếu không có gì tải được trên 127.0.0.1:3333, hãy cuộn lên output npm run dev để xem các dòng [dev:client]. concurrently giữ cho máy chủ API chạy ngay cả khi Vite đã bị crash, vì vậy terminal vẫn trông còn sống - và mở 127.0.0.1:8787/ ở trạng thái đó trả lời bằng ENOENT ... dist/index.html, chỉ có nghĩa là bản dựng production bị thiếu và không nói gì về lỗi thực tế. Một lỗi Cannot find native binding trong các dòng [dev:client] đó là phiên bản Node; xem Điều kiện tiên quyết.

Bước 5 — Xác nhận những gì bạn thấy

Bạn sẽ thấy Dad IT Support Agent chat:

• mascot Specs ở trên
• một lời chào từ Specs
• các suggestion chips bên dưới lời chào
• bảng điều khiển iPhone bên phải ("Dad" + chi tiết iPhone 15)

Cách xác minh bạn đã hoàn thành

• npm run dev đang chạy và lắng nghe trên http://127.0.0.1:3333 (client) và http://127.0.0.1:8787 (máy chủ API).
• http://127.0.0.1:8787/api/health hoặc http://127.0.0.1:8787/api/support-context trả về một phản hồi thực tế.
• Trình duyệt hiển thị lời chào từ Specs, không phải lỗi.
• Gửi một trong các suggestion chips trả về một câu trả lời iPhone thực tế từ model.

Trạng thái cuối cùng

Môi trường của bạn đã sẵn sàng. Để xây dựng workshop từng bước, hãy lướt 01-base-app nếu bạn muốn tour ứng dụng, sau đó checkout checkpoint/02-tracing cho các thay đổi code đầu tiên.