上一部分反复在「考」一个东西——prompt。它是你和模型对话的「脚本」,是 LLM 应用里改动最频繁的部分:一个词的措辞、一句指令的增删,都可能让效果天差地别。这一课讲 Langfuse 怎么像 git 管代码一样管 prompt:不可变的版本、可移动的 label、每次改动的 commit message,外加让一个 prompt 引用另一个的依赖组合。 理解了这套「版本控制」模型,你就握住了「安全地改 prompt」的关键——能发布、能秒回滚、能精确复现任意历史版本,而这一切都不需要改一行应用代码。
production」「staging」这些 label,就像 git 的分支 / 标签——它们是可移动的指针,每个指向某一个版本。把 production 指向 v5,就等于「发布」了 v5;发现不对,把它指回 v4,就是「秒回滚」——而你的应用代码一个字都不用动,因为它只认「给我 production 那版」,不认具体版本号。
你甚至能让一个 prompt 引用另一个(依赖),就像代码里 import 一个公共模块——公共的开场白写一次,处处复用。
一个 prompt 由 (name, version) 唯一确定(@@unique([projectId, name, version]))。新建一版时,version = 上一版 + 1——版本号自增、内容一旦写下永不再改。而 labels 是一个字符串数组,关键规则是:同一个 label 在一个 name 下只能指向一个版本。所以当你给新版打上 production 标签,系统会自动把这个标签从旧版上摘掉——label 就这样「移动」到了新版。
latestPrompt.version + 1);label 唯一、可移动——给新版打 production 会从旧版自动摘除该标签(removeLabelsFromPreviousPromptVersions)。新建版本默认带 latest 标签。源码:createPrompt.ts:88-181、constants.ts:1-2(PRODUCTION_LABEL/LATEST_PROMPT_LABEL)。schema.prisma 的 Prompt:version/labels/commitMessage/createdBy;值为示例):每次保存生成一个不可变的新版本(@@unique([projectId,name,version])),最新在上。production、latest 不是版本号而是可移动的标签指针——发布=把 production 移到某版,回滚=移回去,应用代码只认标签。这张表正是上面「git 式模型」的真实数据形态。// 找到当前最新版,新版号 = 它 + 1(首版为 1)——版本号自增、内容不可变 const latestPrompt = await prisma.prompt.findFirst({ where: {…name}, orderBy: [{ version: "desc" }] }); version: latestPrompt?.version ? latestPrompt.version + 1 : 1, // 新建的 prompt 永远带上 'latest' 标签 const finalLabels = [...labels, LATEST_PROMPT_LABEL]; // "latest" // 关键:label 在一个 name 下唯一 —— 给新版打的 label,要从旧版上摘掉 await removeLabelsFromPreviousPromptVersions({ …, labelsToRemove: finalLabels }); // 于是 production 这个指针「移动」到了新版,旧版不再带它
| git 概念 | prompt 管理对应 | 说明 |
|---|---|---|
| commit | version | 不可变快照,编号自增,内容永不再改 |
| commit message | commitMessage | 每次改动的一句说明,留痕可追溯 |
| branch / tag | labels(production/latest…) | 可移动指针,每 name 下唯一,指向某版 |
| 仓库级标签 | tags | 跨所有版本一致(贴在 name 上,非某一版) |
| import 模块 | PromptDependency | 一个 prompt 引用另一个,组合复用 |
把这张对照表记在心里,prompt 管理就不再是新概念——它就是你已经熟悉的 git,只不过管的不是代码,而是「和模型对话的脚本」。
这套 git 式模型最大的实用价值,藏在应用怎么取 prompt里。生产代码不该写死「给我 v5」——而该写「给我 production 那版」。于是「用哪一版」这个决定,从代码部署里被剥离出来,变成一次移动 label 的运营动作。发布和回滚因此快到秒级,且不经过任何代码改动、CI、上线流程。
get("greeting", label="production"):应用永远只认 production 指针,谁指过去就用谁。换版本是运营在 UI 上移 label,应用无感。这是「配置与代码分离」的教科书。
get("greeting", version=5):精确锁定第 5 版,永不漂移。适合需要绝对可复现的场景(如一次正式实验、一篇论文的复现)。
PromptProtectedLabels 让你把 production 等关键 label 设为「受保护」——移动它需要更高权限,避免新人手滑把没测过的版本推上线。
label="production" 取,指针指向哪版由运营在 UI 决定。发布 = 移 label 到 v5;回滚 = 移回 v4——秒级、零代码、零部署。关键 label 可用 PromptProtectedLabels 加权限门槛。prompt 多了会有重复——同一段「你是一个友好的客服助手……」开场白,可能出现在十个 prompt 里。改一次得改十处,极易漏。PromptDependency 解决这个:一个 prompt(parent)可以引用另一个 prompt(child),引用时既能按版本钉死(childVersion),也能按 label 浮动(childLabel)。这就像代码里 import 一个公共模块——公共片段写一次,处处复用。
schema.prisma:864 的 PromptDependency 用 parentId + childName + childLabel(浮动)或 childVersion(钉死)描述引用。浮动让公共片段一改处处更新,钉定让父 prompt 不受子升级影响——和第一节的 label/version 取舍如出一辙。model PromptDependency { parentId String // 引用方(父 prompt) childName String // 被引用的 prompt 名 childLabel String? // 二选一:按 label 浮动(如 "production"),子升级父自动跟 childVersion Int? // 或:按 version 钉死(如 3),父永远用这版,不漂移 } // 创建时按 dep.type 决定钉哪种(createPrompt.ts) ...(dep.type === "version" ? { childVersion: dep.version } : { childLabel: dep.label })
把这套机制串起来,「安全地改 prompt」就成了一条清晰的流水线——这也正好衔接后两课的 Playground(第39课)与整个 Part 6 的实验:
改完保存即生成新 version(自增、带 commitMessage),旧版原封不动留存。
确认更好,把 production 指针移到新版——线上应用下一次取 prompt 即生效,零部署。
万一线上表现不对,把 production 移回旧版即可——旧版一直在,回滚不丢数据、不等发布。
production)来指代「当前现役」,而现役会变。两者结合,你既能大胆迭代(每改一版都安全留存),又能安心运营(用 label 平滑切换、随时回滚)。把不可变与可变这对矛盾,干净地分配到「版本」和「label」两个概念上——这是数据建模的优雅。version=5,那换 prompt 就得改代码、过 CI、重新部署——慢、重、还得工程师在场。而写 label="production",换版本就变成运营在 UI 上点一下移个指针:秒级生效、可回滚、非工程师也能做。这正是「配置与代码分离」的威力——把变化频繁的东西(prompt 内容)从变化缓慢的东西(应用代码)里剥离,各自用最适合的节奏演进。PromptProtectedLabels 再给关键 label 加一道权限门,让「秒级发布」既灵活又不失控。
(name, version) 唯一;版本号自增、内容不可变,附 commitMessage——每次改动都安全留存、可精确复现。production/latest 等 label 在一个 name 下唯一,指向某一版;给新版打 label 会自动从旧版摘除(removeLabelsFromPreviousPromptVersions)——移 label = 发布 / 回滚。get(label="production"),换版本只需运营移指针——秒级、零代码、零部署、可回滚;按 version 取则用于绝对复现。PromptProtectedLabels 给 production 等关键 label 加权限门槛,避免误把未测版本推上线。PromptDependency 让父 prompt 引用子 prompt,按 childLabel 浮动或 childVersion 钉死——公共片段写一次处处用,取舍逻辑和 label/version 一脉相承。The previous part kept "examining" one thing—the prompt. It's the "script" of your conversation with the model, the most frequently changed part of an LLM app: rewording one word, adding or removing one instruction, can swing the outcome wildly. This lesson is about how Langfuse manages prompts like git manages code: immutable versions, movable labels, a commit message per change, plus dependency composition that lets one prompt reference another. Grasp this "version control" model and you hold the key to "changing prompts safely"—you can release, roll back instantly, and reproduce any historical version exactly, all without touching a line of application code.
production" / "staging" are like git's branches / tags—they're movable pointers, each pointing to one version. Point production at v5 and you've "released" v5; if something's wrong, point it back at v4 for an "instant rollback"—and your application code doesn't change one character, because it asks for "the production one", not a specific version number.
You can even have one prompt reference another (a dependency), like import-ing a shared module in code—write the shared preamble once, reuse it everywhere.
A prompt is uniquely identified by (name, version) (@@unique([projectId, name, version])). On creating a version, version = previous + 1—the number auto-increments, and once written the content is never changed again. labels is a string array, with the key rule: a given label can point to only one version under a name. So when you tag a new version with production, the system automatically strips that label from the old version—the label thus "moves" to the new one.
latestPrompt.version + 1); a label is unique and movable—tagging a new version with production auto-strips it from the old one (removeLabelsFromPreviousPromptVersions). A new version always gets the latest label. Source: createPrompt.ts:88-181, constants.ts:1-2 (PRODUCTION_LABEL/LATEST_PROMPT_LABEL).Prompt model in schema.prisma: version/labels/commitMessage/createdBy; values illustrative): each save creates a new immutable version (@@unique([projectId,name,version])), newest on top. production and latest are not version numbers but movable label pointers — a release moves production onto a version, a rollback moves it back, and app code only knows the label. This table is the concrete data form of the git-style model above.// find the current latest version; new = it + 1 (first is 1)—number auto-increments, content immutable const latestPrompt = await prisma.prompt.findFirst({ where: {…name}, orderBy: [{ version: "desc" }] }); version: latestPrompt?.version ? latestPrompt.version + 1 : 1, // a newly created prompt always gets the 'latest' label const finalLabels = [...labels, LATEST_PROMPT_LABEL]; // "latest" // key: a label is unique per name — labels put on the new version must be stripped from old ones await removeLabelsFromPreviousPromptVersions({ …, labelsToRemove: finalLabels }); // so the production pointer "moves" to the new version; old versions no longer carry it
| git concept | prompt management counterpart | note |
|---|---|---|
| commit | version | immutable snapshot, auto-incrementing number, content never changed |
| commit message | commitMessage | a note per change, leaving a traceable trail |
| branch / tag | labels (production/latest…) | movable pointers, unique per name, pointing to a version |
| repo-level labels | tags | consistent across all versions (on the name, not a version) |
| import a module | PromptDependency | one prompt references another, composition reuse |
Keep this mapping in mind and prompt management is no longer a new concept—it's the git you already know, just managing not code but "the script of your conversation with the model".
This git-style model's biggest practical value hides in how the app fetches a prompt. Production code shouldn't hardcode "give me v5"—it should say "give me the production one". So the decision of "which version to use" is lifted out of code deployment into a label-moving operations action. Releases and rollbacks thus become second-scale, and bypass any code change, CI, or deploy flow.
get("greeting", label="production"): the app only ever knows the production pointer, using whatever it points to. Switching versions is operations moving a label in the UI, with the app oblivious. A textbook of "config-code separation".
get("greeting", version=5): locks exactly to version 5, never drifting. Suits absolute-reproducibility scenarios (a formal experiment, reproducing a paper).
PromptProtectedLabels lets you mark key labels like production as "protected"—moving it needs higher permission, preventing a newcomer from accidentally shipping an untested version.
label="production", with which version the pointer targets decided by operations in the UI. Release = move the label to v5; rollback = move it back to v4—second-scale, zero-code, zero-deploy. Key labels can be gated via PromptProtectedLabels.With many prompts comes duplication—the same "You are a friendly support assistant…" preamble might appear in ten prompts. Editing it once means editing ten places, easy to miss. PromptDependency solves this: a prompt (parent) can reference another prompt (child), either pinned by version (childVersion) or floating by label (childLabel). It's like import-ing a shared module in code—write the shared snippet once, reuse it everywhere.
schema.prisma:864's PromptDependency uses parentId + childName + childLabel (floating) or childVersion (pinned). Floating makes a shared snippet update everywhere on one edit; pinning shields a parent from a child upgrade—mirroring the first section's label/version trade-off.model PromptDependency { parentId String // the referrer (parent prompt) childName String // the referenced prompt's name childLabel String? // one of: float by label (e.g. "production"), parent follows child upgrades childVersion Int? // or: pin by version (e.g. 3), parent always uses this, no drift } // on create, dep.type decides which to pin (createPrompt.ts) ...(dep.type === "version" ? { childVersion: dep.version } : { childLabel: dep.label })
String this mechanism together and "changing a prompt safely" becomes a clear pipeline—dovetailing with the next lessons' Playground (L39) and all of Part 6's experiments:
Saving an edit creates a new version (auto-incrementing, with a commitMessage); the old version is preserved intact.
Confirmed better, move the production pointer to the new version—the production app's next prompt fetch picks it up, zero-deploy.
If production misbehaves, move production back to the old version—the old one is always there, rollback loses no data and waits for no release.
production) to denote "the current active one", and the active one changes. Together, you can both iterate boldly (every edit safely preserved) and operate calmly (switch smoothly via labels, roll back anytime). Cleanly assigning the immutable/mutable tension onto the two concepts "version" and "label" is the elegance of data modeling.version=5, switching prompts means changing code, passing CI, redeploying—slow, heavy, and needs an engineer present. With label="production", switching becomes operations clicking a pointer-move in the UI: second-scale, rollback-able, doable by non-engineers. This is the power of "config-code separation"—lifting the frequently-changing thing (prompt content) out of the slowly-changing thing (app code), each evolving at its own pace. PromptProtectedLabels then gates key labels, keeping "second-scale releases" flexible without losing control.
(name, version) unique; the version number auto-increments, content immutable, with a commitMessage—every edit safely preserved and exactly reproducible.production/latest labels are unique per name, pointing to one version; tagging a new version auto-strips the label from the old one (removeLabelsFromPreviousPromptVersions)—moving a label = release / rollback.get(label="production"), switching versions just needs operations moving a pointer—second-scale, zero-code, zero-deploy, rollback-able; fetch by version is for absolute reproducibility.PromptProtectedLabels gates key labels like production with permissions, preventing an untested version from being shipped by accident.PromptDependency lets a parent reference a child by childLabel (floating) or childVersion (pinned)—write a shared snippet once, reuse everywhere, with trade-off logic mirroring label/version.