核心概念

本页讨论提示词管理的概念与最佳实践。如果你还没有看过,请先查看概览页,了解它为什么对应用的可观测性有价值。

准备开始?查看入门指南来创建你的第一个提示词。

Prompt 对象

Langfuse 认为一个 prompt 是两部分的组合:给 LLM 的指令(可以是单个字符串,也可以是消息数组),以及可选的、影响行为的额外配置。

prompt 对象还有若干属性,用于管理不同的版本、变体和部署。本页将带你了解如何高效使用提示词的最重要原则。

关于 prompt 对象所有字段和方法的详细信息,请参阅 SDK 参考文档。

Chat 提示词 vs Text 提示词

Langfuse 支持两种提示词类型。type 字段决定格式,且创建后不可更改。

Text 提示词是单个字符串,适合简单场景,或只需要一个系统消息的情况。

Chat 提示词是带有特定角色(system、user、assistant)的消息数组,适合你想管理完整对话结构、包含示例对话,或处理聊天历史的情况。

{
  "name": "movie-critic",
  "type": "text",
  "prompt": "As a movie critic, do you like Dune 2?",
  "version": 1
}

{
  "name": "movie-critic-chat",
  "type": "chat",
  "prompt": [
    {
      "role": "system",
      "content": "You are a movie critic."
    },
    {
      "role": "user",
      "content": "Do you like Dune 2?"
    }
  ],
  "version": 1
}

何时使用 chat 提示词: 大多数应用从 text 提示词开始。当你构建更复杂的逻辑,需要管理多条消息、基于角色的结构或聊天历史时,切换到 chat 提示词就很合理。这让你能在提示词管理系统中管理完整的对话结构。

提示词的动态渲染

你可以为提示词添加变量,在运行时动态填充。下面讲解你可以使用的不同类型的变量。

提示词支持三种在运行时插入动态内容的方式:

提示词缓存

Langfuse 提示词管理使用缓存的提示词,主要有两个原因:

1. 不会给你的应用增加延迟。
2. 消除可用性风险。

这意味着更新提示词后的前几个 traces 可能仍在使用旧版本。如果你的用例对即时更新有要求,你可以禁用缓存,或配置更短的 TTL(存活时间)。

关于缓存的工作原理和配置方法,请参阅缓存文档。

版本与标签

理解版本和标签如何协同工作,对于在生产环境中管理提示词至关重要。它们有着不同但互补的用途。

**版本(Versions)**提供每次提示词变更的不可变历史。每次更新都会创建一个新版本(1, 2, 3...)。

**标签(Labels)**是指向特定版本的指针。你的代码通常指向标签。常见的标签包括:

• production - 默认标签,供生产应用使用
• latest - 始终指向最新版本
• 自定义标签 - 为预发、测试、租户或 A/B 测试创建标签

了解更多关于版本与标签的内容。

graph LR
    subgraph "Prompt Management"
      subgraph "Prompt Version History"
          V1["Version 1"]
          V2["Version 2"]
          V3["Version 3"]
          V4["Version 4"]
          V1 -.-> V2
          V2 -.-> V3
          V3 -.-> V4
      end

      subgraph "Prompt Labels"
        PROD["🏷️ production<br/>(default)"]
        LATEST["🏷️ latest<br/>(auto-updated)"]
        TENANT["🏷️ tenant-b<br/>(custom)"]
      end
    end

    PROD -->|targets| V2
    LATEST -->|targets| V4
    TENANT -->|targets| V4

    SDK["SDK Request<br/>get_prompt('movie-critic')"] -->|resolves via| PROD

    SDK2["SDK Request<br/>get_prompt('movie-critic', label='latest')"] -->|resolves via| LATEST

    class V1,V2,V3,V4 version
    class PROD,LATEST,TENANT label
    class SDK sdk,sdk2

部署工作流

下面是部署提示词变更的典型工作流:

1. 创建并测试: 创建新的提示词版本(自动获得 latest 标签)
2. 验证: 在开发环境中或使用 playground 测试新版本
3. 部署: 更新 production 标签,使其指向新版本
4. 监控: 生产应用会在下次获取时自动采用新版本
5. 必要时回滚: 只需把 production 标签重新指回之前的版本

由于你的代码引用的是标签,所有这些操作都无需修改代码。