03 Quản lý prompt

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

Xem tệp Markdown này

Điểm bắt đầu

git checkout checkpoint/03-prompt-management

Bạn có một ứng dụng được theo dõi. System prompt tồn tại như một hằng số được gọi là SYSTEM_PROMPT trong src/server/support-agent.ts và được sử dụng trực tiếp làm system message.

Trong chương này, chúng ta chuyển prompt đó vào Langfuse để nó được quản lý phiên bản và có thể chỉnh sửa trong giao diện người dùng, và chúng ta lấy nó lại vào thời gian yêu cầu. Hằng số cục bộ vẫn giữ trong tệp làm dự phòng khi không thể tiếp cận Langfuse.

Đảm bảo .env có:

LANGFUSE_PROMPT_NAME=dad-it-support-agent
LANGFUSE_PROMPT_LABEL=production

Tại sao quản lý prompt

Giữ system prompt trong mã có nghĩa là mọi thay đổi prompt là một thay đổi mã: pull request, review, build, deploy. Với quản lý prompt Langfuse, prompt tồn tại trong Langfuse — được quản lý phiên bản, được dán nhãn, và có thể chỉnh sửa trong giao diện người dùng — và ứng dụng lấy nó vào thời gian yêu cầu. Điều đó có nghĩa là những người không phải kỹ sư có thể lặp lại prompts, các thay đổi được phát hành độc lập với các chu kỳ phát hành, và mọi phiên bản được bảo tồn và liên kết với các traces nó tạo ra.

Tìm hiểu thêm trong tài liệu Langfuse prompts.

Mục tiêu

Hai bước:

1. Công bố system prompt cho Langfuse để một bản sao được quản lý phiên bản tồn tại ở đó.
2. Lấy nó lại vào thời gian yêu cầu, và liên kết từng thế hệ OpenAI với phiên bản tạo ra nó.

Bước 1 — Công bố prompt (Giao diện Langfuse)

Cách trực tiếp nhất để tạo prompt là thêm nó theo cách thủ công trong giao diện — nó là quy trình làm việc giống nhau mà nhóm của bạn sẽ sử dụng cho mọi lần lặp lại trong tương lai.

1. Trong Langfuse, mở Prompts → New prompt.
2. Đặt tên là dad-it-support-agent (phù hợp với LANGFUSE_PROMPT_NAME trong .env của bạn).
3. Type là text.
4. Dán nội dung của SYSTEM_PROMPT từ src/server/support-agent.ts.
5. Gắn nhãn phiên bản production (phù hợp với LANGFUSE_PROMPT_LABEL trong .env của bạn).
6. Save.

💡 Lựa chọn thay thế — công bố qua script. scripts/publish-prompt.ts đẩy hằng số SYSTEM_PROMPT lên Langfuse (npm run prompt:publish). Kết quả tương tự.

Bước 2 — Lấy prompt từ Langfuse

Thêm import trong src/server/support-agent.ts:

import { LangfuseClient } from "@langfuse/client";

Xây dựng client ở phạm vi module:

const langfuse = new LangfuseClient();

Thêm trợ giúp getPrompt lấy từ Langfuse, trả về null khi có bất kỳ lỗi nào để chat có thể quay lại SYSTEM_PROMPT cục bộ:

async function getPrompt() {
  try { return await langfuse.prompt.get(env.langfusePromptName); }
  catch { return null; }
}

Sử dụng nó trong runSupportConversation — lấy, sau đó quay lại hằng số cục bộ nếu lần lấy trả về null:

const langfusePrompt = await getPrompt();
const systemPrompt = langfusePrompt?.prompt ?? SYSTEM_PROMPT;

Gửi systemPrompt làm system message. Tìm dòng này trong transcript vài dòng dưới:

{ role: "system", content: SYSTEM_PROMPT },

và thay đổi nó thành:

{ role: "system", content: systemPrompt },

Nếu không có thay đổi này, mô hình tiếp tục nhận hằng số cục bộ — huy hiệu Prompt ở bước tiếp theo vẫn sẽ xuất hiện, nhưng chỉnh sửa prompt trong Langfuse sẽ không có tác dụng đến các câu trả lời.

Chuyển langfusePrompt đến lệnh gọi observeOpenAI hiện có để thế hệ được liên kết với phiên bản prompt đã công bố — chỉ khi chúng ta thực sự có:

const openai = observeOpenAI(
  new OpenAI({ apiKey: env.openaiApiKey }),
  langfusePrompt ? { langfusePrompt } : undefined
);

Ba điều cần chú ý:

• Lệnh gọi observeOpenAI(new OpenAI(...)) chính nó không thay đổi — cùng một bọc nội tuyến từ bước 02. Chúng ta chỉ thêm một đối số thứ hai có điều kiện mang langfusePrompt.
• Hằng số cục bộ SYSTEM_PROMPT vẫn giữ trong tệp làm dự phòng. Nếu Langfuse bị cấu hình sai hoặc prompt chưa được công bố, chat vẫn hoạt động — nó chỉ không mang huy hiệu Prompt trên lần quay đó.
• Truyền langfusePrompt vào observeOpenAI là những gì làm cho mọi thế hệ dưới client đó mang huy hiệu Prompt liên kết lại với phiên bản đã công bố chính xác.

Xác minh

npm run dev

Hỏi một câu hỏi, sau đó trong Langfuse:

• Mở trace, nhấp vào thế hệ OpenAI. Nó sẽ hiển thị huy hiệu Prompt liên kết đến dad-it-support-agent ở phiên bản bạn đã công bố.
• Trong chế độ xem Prompts cho dad-it-support-agent, cuộn đến "Used in" và trace của bạn xuất hiện.

Kết thúc

Quản lý prompt là những gì đóng vòng trace ↔ prompt. Mọi phiên bản prompt được bảo tồn, mọi thế hệ biết phiên bản nào tạo ra nó, và bạn có thể lặp lại prompts độc lập với các lần triển khai mã.

Một cách thanh lịch hơn để kết nối quản lý prompt phù hợp với các thực tiễn tốt nhất của Langfuse là Langfuse skill (/langfuse). Skill áp dụng các mẫu được khuyến nghị cho codebase của bạn mà không cần bạn tự xây dựng từng phần. Hướng dẫn này tồn tại để bạn có thể thấy skill đang làm gì dưới lớp vỏ.

Trạng thái cuối

Đây là điểm bắt đầu cho 04-monitoring.