03 提示词管理

您有一个可工作的已追踪应用程序。系统提示词存在于 src/server/support-agent.ts 中的常量 SYSTEMPROMPT 中，并直接用作系统消息。

工作坊材料在公共 langfuse/langfuse-workshop 仓库中维护。使用该仓库获取可运行的应用程序、检查点分支和本地设置。

起始点

git checkout checkpoint/03-prompt-management

您有一个可工作的已追踪应用程序。系统提示词存在于 src/server/support-agent.ts 中的常量 SYSTEM_PROMPT 中，并直接用作系统消息。

在本章中，我们将该提示词移至 Langfuse，以便其被版本化并在 UI 中可编辑，并在请求时获取它。本地常量保留在文件中作为 Langfuse 无法访问时的备用方案。

确保 .env 具有：

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

为什么要管理提示词

将系统提示词保存在代码中意味着每个提示词更改都是代码更改：拉取请求、审查、构建、部署。使用 Langfuse 提示词管理，提示词存在于 Langfuse 中——已版本化、已标记并在 UI 中可编辑——应用程序在请求时获取它。这意味着非工程师可以迭代提示词，更改独立于发布周期，每个版本都被保留并链接到它产生的踪迹。

在 Langfuse 提示词文档中了解更多。

目标

两个步骤：

将系统提示词发布到 Langfuse，以便一个版本化副本存在于那里。
在请求时获取它，并将每个 OpenAI 生成链接到产生它的版本。

第 1 步 — 发布提示词（Langfuse UI）

创建提示词的最直接方式是在 UI 中手动添加它——这是您的团队将用于每次后续迭代的相同工作流。

在 Langfuse 中，打开提示词 → 新建提示词。
命名为 dad-it-support-agent（与您 .env 中的 LANGFUSE_PROMPT_NAME 匹配）。
类型是 text。
粘贴 src/server/support-agent.ts 中的 SYSTEM_PROMPT 的正文。
标记版本为 production（与您 .env 中的 LANGFUSE_PROMPT_LABEL 匹配）。
保存。

在 Langfuse 中创建 dad-it-support-agent 提示词。

💡 替代方式 — 通过脚本发布。 scripts/publish-prompt.ts 将 SYSTEM_PROMPT 常量推送到 Langfuse（npm run prompt:publish）。结果相同。

第 2 步 — 从 Langfuse 获取提示词

在 src/server/support-agent.ts 中添加导入：

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

在模块范围构造客户端：

const langfuse = new LangfuseClient();

添加一个 getPrompt 辅助程序，从 Langfuse 获取，在任何失败时返回 null，以便聊天可以回退到本地 SYSTEM_PROMPT：

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

在 runSupportConversation 中使用它 — 获取，然后如果获取返回 null 则回退到本地常量：

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

将 systemPrompt 作为系统消息发送。 在抄本中找到这一行，位于几行下方：

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

并将其更改为：

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

没有此更改，模型将继续接收本地常量——下一步中的提示词徽章仍然会出现，但在 Langfuse 中编辑提示词不会对答案产生影响。

将 langfusePrompt 传递到现有的 observeOpenAI 调用，以便生成被链接到已发布的提示词版本——仅当我们实际拥有一个时：

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

需要注意三件事：

observeOpenAI(new OpenAI(...)) 调用本身没有改变——来自第 02 步的相同内联包装。我们只是添加了一个条件第二个参数，携带 langfusePrompt。
本地 SYSTEM_PROMPT 常量保留在文件中作为备用。如果 Langfuse 配置错误或提示词尚未发布，聊天将继续工作——它只是不会在该轮次上携带提示词徽章。
将 langfusePrompt 传递到 observeOpenAI 是使该客户端下的每个生成都携带提示词徽章的原因，链接回到确切的已发布版本。