langfuse-prompt-migration

Langfuse 提示词迁移

将硬编码提示词迁移到 Langfuse，以便进行版本控制、A/B 测试和无需部署的迭代。

先决条件

开始前验证凭据：

echo $LANGFUSE_PUBLIC_KEY   # pk-...
echo $LANGFUSE_SECRET_KEY   # sk-...
echo $LANGFUSE_HOST         # https://cloud.langfuse.com or self-hosted

如果尚未设置，请让用户先配置。

迁移流程

1. Scan codebase for prompts
2. Analyze templating compatibility
3. Propose structure (names, subprompts, variables)
4. User approves
5. Create prompts in Langfuse
6. Refactor code to use get_prompt()
7. Link prompts to traces (if tracing enabled)
8. Verify application works

步骤 1：查找提示词

搜索以下模式：

框架	查找内容
OpenAI	messages=[{"role": "system", "content": "..."}]
Anthropic	system="..."
LangChain	ChatPromptTemplate、SystemMessage
Vercel AI	system: "..."、prompt: "..."
原始代码	LLM 调用附近的多行字符串

步骤 2：检查模板兼容性

重要： Langfuse 仅支持简单的 {{variable}} 替换。不支持条件语句、循环或过滤器。

模板功能	Langfuse 原生支持	操作
{{variable}}	✅	直接迁移
{var} / ${var}	⚠️	转换为 {{var}}
{% if %} / {% for %}	❌	将逻辑移至代码中
{{ var | filter }}	❌	在代码中应用过滤器

决策树

Contains {% if %}, {% for %}, or filters?
├─ No → Direct migration
└─ Yes → Choose:
    ├─ Option A (RECOMMENDED): Move logic to code, pass pre-computed values
    └─ Option B: Store raw template, compile client-side with Jinja2
        └─ ⚠️ Loses: Playground preview, UI experiments

简化复杂模板

条件语句 → 在代码中预先计算：

# Instead of {% if user.is_premium %}...{% endif %} in prompt
# Use {{tier_message}} and compute value in code before compile()

循环 → 在代码中预先格式化：

# Instead of {% for tool in tools %}...{% endfor %} in prompt
# Use {{tools_list}} and format the list in code before compile()

有关外部模板的详情，请访问：https://langfuse.com/faq/all/using-external-templating-libraries

步骤 3：提出结构方案

命名约定

规则	示例	不佳示例
使用小写字母，以连字符分隔	chat-assistant	ChatAssistant_v2
按功能命名	document-summarizer	prompt1
相关项使用层级命名	support/triage	supportTriage
子提示词使用 _ 前缀	_base-personality	shared-personality

识别子提示词

在以下情况下提取子提示词：

• 相同文本出现在 2 个或更多提示词中
• 表示独立组件（个性、安全规则、格式）
• 需要一起修改

提取变量

设为变量	保留为硬编码
特定用户内容（{{user_name}}）	输出格式说明
动态内容（{{context}}）	安全防护规则
每次请求的内容（{{query}}）	角色/个性
特定环境的内容（{{company_name}}）	静态示例

步骤 4：向用户展示计划

格式：

Found N prompts across M files:

src/chat.py:
  - System prompt (47 lines) → 'chat-assistant'

src/support/triage.py:
  - Triage prompt (34 lines) → 'support/triage'
    ⚠️ Contains {% if %} - will simplify

Subprompts to extract:
  - '_base-personality' - used by: chat-assistant, support/triage

Variables to add:
  - {{user_name}} - hardcoded in 2 prompts

Proceed?

步骤 5：在 Langfuse 中创建提示词

使用 langfuse.create_prompt()，参数如下：

• name：选择的名称
• prompt：模板文本（或 chat 类型的消息数组）
• type："text" 或 "chat"
• labels：["production"]（这些提示词已在线使用）
• config：可选的模型设置

标签策略：

• production → 所有已迁移的提示词
• staging → 之后添加，用于测试
• latest → 由 Langfuse 自动应用

完整 API 文档：https://langfuse.com/docs/prompts/get-started

步骤 6：重构代码

将硬编码提示词替换为：

prompt = langfuse.get_prompt("name", label="production")
messages = prompt.compile(var1=value1, var2=value2)

要点：

• 始终使用 label="production"（而非 latest），确保稳定性
• 调用 .compile() 替换变量
• 对于 chat 提示词，结果是可直接用于 API 的消息数组

SDK 示例（Python/JS/TS）：请访问 https://langfuse.com/docs/prompts/get-started

步骤 7：将提示词关联到跟踪记录

如果代码库使用 Langfuse 跟踪，请关联提示词，以便查看每个响应使用的版本。

检测现有跟踪

查找：

• @observe() 装饰器
• langfuse.trace() 调用
• from langfuse.openai import openai（已插桩的客户端）

关联方式

设置	关联方式
@observe() 装饰器	langfuse_context.update_current_observation(prompt=prompt)
手动跟踪	trace.generation(prompt=prompt, ...)
OpenAI 集成	openai.chat.completions.create(..., langfuse_prompt=prompt)

在 UI 中验证

1. 前往 Traces → 选择一条跟踪记录
2. 点击 Generation
3. 检查 Prompt 字段是否显示名称和版本

跟踪详情：https://langfuse.com/docs/prompts/get-started#link-with-langfuse-tracing

步骤 8：验证迁移

检查清单

• 所有提示词都使用 production 标签创建
• 代码使用 label="production" 获取提示词
• 变量编译无错误
• 子提示词解析正确
• 应用行为未改变
• 生成记录在 UI 中显示关联的提示词（如果启用了追踪）

常见问题

问题	解决方案
PromptNotFoundError	检查名称拼写
变量未替换	使用 {{var}} 而非 {var}，并调用 .compile()
子提示词未解析	必须存在具有相同标签的子提示词
缓存了旧提示词	重启应用

不在范围内

• 提示词工程（编写更好的提示词）
• 评估设置
• A/B 测试工作流
• 非 LLM 字符串模板