拒绝复制粘贴！LangSmith SDK 实战：如何实现 Prompt 的版本化管理与迭代

摘要： 在大模型应用开发中，Prompt（提示词）往往决定了应用的成败。然而，许多开发者仍习惯于将 Prompt 硬编码在代码中，导致团队协作困难、版本回溯无门。LangHub 作为 LangSmith 生态系统的一部分，提供了强大的 Prompt 管理能力。本文将介绍如何利用 LangSmith 的 Python SDK，实现 Prompt 的云端托管、拉取测试以及版本迭代，助你构建专业级的 LLM 应用开发流程。

1. 前言：为什么要托管 Prompt？

在没有专用工具的情况下，修改 Prompt 的流程通常是：改代码 -> 提交 -> 发布 -> 观察效果。这种模式存在几个明显缺陷：

• 耦合度高：业务逻辑与 Prompt 文本混在一起。
• 无法 A/B 测试：很难快速对比不同版本 Prompt 的效果。
• 协作割裂：非技术人员（如产品经理）难以直接参与 Prompt 优化。
  LangSmith 的 Prompt 管理功能通过 SDK 将 Prompt 变成了可管理的“代码依赖”，我们可以像管理 API 配置一样管理 Prompt。

2. 环境准备

确保已安装必要的 Python 库：

pip install langsmith langchain-openai openai

设置环境变量（以连接 LangSmith）：

import os
os.environ["LANGCHAIN_API_KEY"] = "lsv2_sk_..." # 你的 LangSmith API Key
os.environ["LANGCHAIN_TRACING_V2"] = "true"

3. 第一步：创建并上传 Prompt

首先，我们需要定义一个 Prompt 模板，并将其推送到 LangSmith 服务器。这相当于在你的云端工作区创建了一个“Prompt 资源”。

我们使用 ChatPromptTemplate 来构建结构化的对话模板，并使用 client.push_prompt 进行上传。

from langsmith import Client
from langchain_core.prompts import ChatPromptTemplate

# 初始化客户端
client = Client()

# 定义 Prompt 模板
# 包含一个 System 角色设定和一个 User 输入变量
prompt = ChatPromptTemplate([
    ("system", "You are a helpful chatbot."),
    ("user", "{question}"),
])

# 将 Prompt 推送到 LangSmith
# "my-prompt" 是这个 Prompt 的唯一标识符
client.push_prompt("my-prompt", object=prompt)

print("Prompt 上传成功！")

此时，登录 LangSmith 的 Web 界面，你会发现名为 my-prompt 的提示词已经出现在你的 Prompts 列表中。

4. 第二步：拉取并测试 Prompt

Prompt 上传后，我们可以在任何应用代码中通过名称拉取它，并在本地或生产环境中进行测试。这种方式实现了“代码与 Prompt 解耦”。

4.1 拉取 Prompt

使用 client.pull_prompt 方法获取云端模板。默认情况下，它会拉取最新的提交版本。

from langsmith import Client
from openai import OpenAI
from langchain_core.messages import convert_to_openai_messages

client = Client()
oai_client = OpenAI()

# 从 LangSmith 拉取 Prompt
# 也可以指定版本号，例如: "my-prompt:abc123hash"
prompt = client.pull_prompt("my-prompt")

4.2 格式化与调用

拉取下来的对象是一个标准的 LangChain ChatPromptTemplate。我们可以像使用本地对象一样，使用 .invoke() 方法填充变量，然后利用 convert_to_openai_messages 将其转换为 OpenAI API 兼容的格式进行测试。

# 1. 填充变量
# 这里我们传入具体的用户问题
formatted_prompt = prompt.invoke({"question": "What is the color of the sky?"})

# 2. 转换消息格式
# LangChain 的消息格式需要转换为 OpenAI 原生格式
openai_messages = convert_to_openai_messages(formatted_prompt.messages)

# 3. 调用模型进行测试
response = oai_client.chat.completions.create(
    model="gpt-4o",
    messages=openai_messages,
)

print(f"模型回答: {response.choices[0].message.content}")

5. 第三步：迭代与版本管理

真实的开发场景中，Prompt 总是不断优化的。比如，我们现在要求机器人用西班牙语回答，而不是英语。我们不需要动应用层的业务代码，只需更新云端 Prompt。

5.1 更新 Prompt

我们创建一个新的 Prompt 对象，并推送到同一个名称 my-prompt 下。LangSmith 会自动将其识别为一个新的 Commit。

from langsmith import Client
from langchain_core.prompts import ChatPromptTemplate

client = Client()

# 定义改进后的 Prompt
# 修改 System 消息，增加语言限制
new_prompt = ChatPromptTemplate([
    ("system", "You are a helpful chatbot. Respond in Spanish."),
    ("user", "{question}"),
])

# 推送更新，确保名称一致
# 使用 tags 标记这次更新，方便后续查找
client.push_prompt("my-prompt", object=new_prompt, tags=["Spanish", "v2"])

print("Prompt 迭代版本已上传！")

5.2 团队协作与 UI 优化

• 版本对比：在 LangSmith 的 Web 界面中，你可以清晰地看到 my-prompt 的历史提交记录（Commit History），对比每个版本的具体差异。
• Prompt Canvas：对于不想写代码的团队成员，可以使用 LangSmith 提供的 Prompt Canvas（提示词画布） 工具，在可视化界面中直接编辑、调试并保存 Prompt，这完全等价于使用 SDK 进行 push 操作。

6. 总结

通过 LangSmith SDK，我们实现了一套标准的 Prompt 管理闭环：

• 定义：使用 ChatPromptTemplate 结构化定义 Prompt。
• 托管：通过 push_prompt 将其托管到云端，实现集中管理。
• 集成：应用代码通过 pull_prompt 动态获取，无需重新部署即可切换 Prompt 版本。
• 迭代：通过 Tags 和 Commit 历史记录，支持高效的 A/B 测试和团队协作。
  这种“Prompt 即代码”的实践，是构建企业级 LLM 应用不可或缺的一环。快去试试把你的硬编码 Prompt 搬运到 LangSmith 上吧！

参考资源：
LangSmith 官方文档: https://docs.smith.langchain.com/
OpenAI Prompt Engineering Guide
希望这篇文章能帮助你更好地管理你的 Prompt 工程！🚀