AI Agent从无到有34: 用 LangSmith Hub 实现团队级提示词管理

纲要

• LangSmith 平台核心能力
  • 可观测性（Observability）：实时监控 LLM 应用性能与异常
  • 评估（Evaluation）：提供数据集与测试工具，量化模型效果
  • 提示工程（Prompt Engineering）：通过 Hub 管理提示词版本、共享与协作
• 传统提示词管理的痛点
• Hub 工作流：创建、推送、拉取、迭代
• 关键组件：langsmith SDK、hub.pull、Client.push_prompt、Client.pull_prompt
• 代码演示：完整可运行的 Python 脚本（需配置 API Key）

引言

在团队开发 AI Agent 或 LLM 应用时，提示词（Prompt）往往分散在各个开发者的代码、配置文件甚至聊天记录中。版本混乱、难以复用、缺乏审计，这些问题随着项目规模的扩大而日益严重。

LangChain 生态中的 LangSmith Hub 正是为解决这一痛点而设计。它提供了一个类似 GitHub 的提示词托管平台，支持版本化、分享、评审和远程加载，让提示词真正成为可管理的资产。

LangSmith Hub 快速上手

中心化提示词管理的必要性

假设一个三人团队共同维护一个客服机器人，每个人的本地都有一份 system_prompt.txt。当需要调整话术时，必须手动同步文件，极易出现覆盖和冲突。使用 Hub 后，所有提示词都存储于云端，团队成员只需通过一个简单的标识符即可拉取最新版本，同时保留历史版本，随时可回滚。

三大核心操作：拉取、推送、迭代

LangSmith Hub 的基本使用流程如下：

下面通过代码逐步实现这个流程。

前置准备

1. 注册 LangSmith 账号，在 Settings > API Keys 页面创建 API Key。
2. 安装必要的 Python 包（推荐使用 langsmith SDK，langchainhub 包已废弃）：

pip install -U langsmith langchain-core langchain-openai

3. 设置环境变量：

export LANGSMITH_API_KEY="你的API密钥"
export OPENAI_API_KEY="你的OpenAI密钥"  # 如果使用 OpenAI 模型

拉取公共提示词

Hub 上有很多社区分享的优质提示词，例如一个将自然语言转 SQL 的模板。可以通过 hub.pull 加载到本地使用。注意，拉取公共提示词时需要指定作者的 handle。

from langchain import hub

# 从 Hub 拉取公共提示词
prompt = hub.pull("langchain-ai/text-to-sql")
print("模板结构：")
print(prompt)
print()

# 格式化提示词
formatted = prompt.format(question="查询所有年龄大于30的用户")
print("格式化后的提示词：")
print(formatted)

创建并推送自有提示词

使用 langsmith 客户端将本地创建好的 ChatPromptTemplate 推送到 Hub，方便团队共享。根据官方文档，push_prompt 方法使用 object 参数传递提示词对象。

import os
from langsmith import Client
from langchain_core.prompts import ChatPromptTemplate

# 初始化客户端（自动读取环境变量 LANGSMITH_API_KEY）
client = Client()

# 创建一个提示词模板
my_prompt = ChatPromptTemplate.from_messages([
    ("system", "你是一个友好的客服助手，用中文回答。"),
    ("human", "{question}")
])

# 推送到 Hub，指定一个唯一名称
try:
    url = client.push_prompt(
        "my-customer-service-prompt",   # 提示词名称，建议加上命名空间，如 "my-org/my-prompt"
        object=my_prompt                # 注意：使用 object 参数传递提示词
    )
    print(f"提示词已上传，Hub 地址：{url}")
except Exception as e:
    print(f"上传失败: {e}")
    print("请确认已设置 LANGSMITH_API_KEY 且名称未被占用。")

团队协作：拉取并使用提示词

其他团队成员配置好 API Key 后，只需执行一行代码即可获取最新提示词，并接入模型调用。

from langsmith import Client
from langchain_openai import ChatOpenAI

client = Client()

# 拉取指定版本的提示词（不指定版本则拉取最新）
prompt = client.pull_prompt("my-customer-service-prompt")
print("拉取到的提示词：")
print(prompt)
print()

# 连接模型（以 OpenAI 为例）
model = ChatOpenAI(model="gpt-3.5-turbo", temperature=0)
chain = prompt | model

# 调用
response = chain.invoke({"question": "我的订单什么时候发货？"})
print("模型回答：")
print(response.content)

提示词迭代与版本管理

当需要修改提示词时，开发者可以更新本地模板后再次推送，系统会自动生成新版本，每个版本都有一个唯一的 commit hash。在生产环境中，建议通过 commit hash 固定版本，而非默认拉取 latest。

# 创建一个改进版提示词
improved_prompt = ChatPromptTemplate.from_messages([
    ("system", "你是一个风趣幽默的客服助手，回答尽量简短。"),
    ("human", "{question}")
])

# 推送时增加标签（commit_tags），便于标记版本
client.push_prompt(
    "my-customer-service-prompt",
    object=improved_prompt,
    commit_tags=["v2", "humorous"]      # 使用 commit_tags 参数标记版本
)

# 拉取指定版本（通过 commit hash 或标签）
# 注意：实际使用时应替换为真实的 commit hash
prompt_v1 = client.pull_prompt("my-customer-service-prompt:abc123")
prompt_v2 = client.pull_prompt("my-customer-service-prompt:def456")
print("v1 版本的系统提示词：", prompt_v1.messages[0].content)
print("v2 版本的系统提示词：", prompt_v2.messages[0].content)

在 Hub 网页界面中，可以直观地对比不同版本的差异，查看提交历史，甚至在线测试提示词效果。

本地管理 vs Hub 管理

特性	本地文件/代码内嵌	LangSmith Hub
版本控制	依赖 Git（需手动提交）	自动版本化，内置 Diff 对比
团队共享	手动复制、同步	一行命令拉取
在线测试	无	提供 Playground，可实时调试
复用性	低，易重复造轮子	高，社区模板可复用
权限与审计	无	支持 API Key 权限，可查看下载次数

完整可运行示例代码

以下代码将上述所有步骤整合为一个脚本，只需配置好 API Key 即可运行。未配置时会给出友好提示。

import os
import sys
from langchain import hub
from langsmith import Client
from langchain_core.prompts import ChatPromptTemplate
from langchain_openai import ChatOpenAI

# 检查必要的环境变量
if not os.getenv("LANGSMITH_API_KEY"):
    sys.exit("请设置环境变量 LANGSMITH_API_KEY")
if not os.getenv("OPENAI_API_KEY"):
    print("警告：未设置 OPENAI_API_KEY，仅测试提示词管理，不进行模型调用。")

def main():
    client = Client()
    
    # 1. 拉取公共模板
    print("=== 1. 从 Hub 拉取公共模板 ===")
    public_prompt = hub.pull("langchain-ai/text-to-sql")
    print("拉取成功，模板变量：", public_prompt.input_variables)
    
    # 2. 创建并推送自有模板
    print("\n=== 2. 推送自定义提示词 ===")
    my_template = ChatPromptTemplate.from_messages([
        ("system", "你是一个友好的客服助手，用中文回答。"),
        ("human", "{question}")
    ])
    prompt_name = "my-test-prompt-001"  # 请替换为你的命名空间/名称
    try:
        url = client.push_prompt(prompt_name, object=my_template)
        print(f"推送成功，Hub 地址：{url}")
    except Exception as e:
        print(f"推送失败（可能名称已存在）: {e}")
        # 若已存在，直接拉取
        print("尝试拉取已有版本...")
    
    # 3. 拉取刚推送的模板（或已有版本）
    print("\n=== 3. 拉取提示词并调用模型 ===")
    pulled_prompt = client.pull_prompt(prompt_name)
    print("拉取成功，消息结构：")
    for msg in pulled_prompt.messages:
        print(f"  [{msg.type}]: {msg.content}")
    
    # 4. 如果有模型，运行一条测试
    if os.getenv("OPENAI_API_KEY"):
        model = ChatOpenAI(model="gpt-3.5-turbo", temperature=0)
        chain = pulled_prompt | model
        response = chain.invoke({"question": "我的订单什么时候发货？"})
        print("\n模型回答：")
        print(response.content)
    else:
        print("\n跳过模型调用（未配置 OPENAI_API_KEY）。")

if __name__ == "__main__":
    main()

API 速览

以下梳理本文涉及的核心 API：

langchain.hub.pull

• 所属库：langchain
• 方法签名：pull(owner_repo_commit: str) -> Runnable
• 参数：
  • owner_repo_commit：提示词标识符，格式为 owner/repo 或 owner/repo/commit_hash
• 返回值：Runnable 对象，可直接用于链式调用
• 示例：

from langchain import hub
prompt = hub.pull("langchain-ai/text-to-sql")

langsmith.Client.push_prompt

• 所属库：langsmith
• 方法签名：push_prompt(name: str, object: Any, commit_tags: Optional[Sequence[str]] = None, description: Optional[str] = None) -> str
• 参数：
  • name：提示词名称，建议使用 org/name 格式
  • object：要推送的 LangChain 对象（如 ChatPromptTemplate）
  • commit_tags：可选，为此次提交添加标签
  • description：可选，提示词描述
• 返回值：提示词在 UI 中的 URL
• 示例：

from langsmith import Client
from langchain_core.prompts import ChatPromptTemplate
client = Client()
prompt = ChatPromptTemplate.from_template("tell me a joke about {topic}")
url = client.push_prompt("joke-generator", object=prompt)

langsmith.Client.pull_prompt

• 所属库：langsmith
• 方法签名：pull_prompt(prompt_identifier: str, include_model: bool = False) -> Runnable
• 参数：
  • prompt_identifier：提示词标识符，格式为 owner/repo 或 owner/repo:commit_hash
  • include_model：是否同时加载关联的模型配置
• 返回值：Runnable 对象
• 示例：

from langsmith import Client
client = Client()
prompt = client.pull_prompt("my-org/my-prompt")

参考文档

官方文档

• Manage prompts programmatically - LangSmith Docs
• Manage prompts - LangSmith Docs
• Prompt & Context Hub - LangSmith Docs
• LangSmith SDK GitHub Repository

参考链接

• LangChain Hub API Reference (JavaScript)
• Prompt Versioning - LangSmith Cookbook

总结

LangSmith Hub 为提示词赋予了代码般的版本管理与协作能力，将“一次编写、到处复制”的原始模式升级为“集中托管、按需拉取、持续迭代”的工程化模式。关键技术栈要点包括：

• langsmith SDK：官方推荐的提示词管理工具，langchainhub 包已废弃
• push_prompt：使用 object 参数传递提示词对象，支持 commit_tags 标记版本
• pull_prompt：支持通过 commit_hash 固定版本，生产环境应避免默认拉取 latest
• 版本管理：每次推送自动生成 commit hash，支持 Diff 对比和标签管理
• 环境管理：支持 Staging 和 Production 环境隔离，可通过 UI 完成版本晋升

无论是个人开发者复用社区模板，还是团队多人协作维护复杂应用，LangSmith Hub 都能显著提升提示词管理的效率和可靠性。