纲要

• LangSmith 平台核心能力
  • 可观测性：实时监控 LLM 应用性能与异常
  • 评估：提供数据集与测试工具，量化模型效果
  • 提示工程：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 快速上手

为什么需要中心化的提示词管理？

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

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

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

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

前置准备

1. 注册 LangSmith 账号，在 Settings 页面创建 API Key。
2. 安装必要的 Python 包：

pip install langchain langchain-core langsmith langchain-openai

3. 设置环境变量：

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

拉取公共提示词

Hub 上有很多社区分享的优质提示词，例如一个将自然语言转 SQL 的模板 langchain-ai/text-to-sql。可以直接用 hub.pull 加载到本地使用。

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，方便团队共享。

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

# 初始化客户端（自动读取环境变量 LANGCHAIN_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"
        prompt=my_prompt
    )
    print(f"提示词已上传，Hub 地址：{url}")
except Exception as e:
    print(f"上传失败: {e}")
    print("请确认已设置 LANGCHAIN_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)

提示词迭代与版本管理

当需要修改提示词时，开发者可以更新本地模板后再次推送，系统会自动生成新版本。也可以手动标记版本号（如 :v2），便于引用历史版本。

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

# 推送时增加标签，表示新版本
client.push_prompt(
    "my-customer-service-prompt",
    prompt=improved_prompt,
    tags=["v2", "humorous"]
)

# 拉取指定版本
prompt_v1 = client.pull_prompt("my-customer-service-prompt:v1")
prompt_v2 = client.pull_prompt("my-customer-service-prompt:v2")
print("v1 版本的系统提示词：", prompt_v1.messages[0].content)
print("v2 版本的系统提示词：", prompt_v2.messages[0].content)

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

本地管理 vs Hub 管理

特性	本地文件/代码内嵌	LangSmith Hub
版本控制	依赖 Git（需手动提交）	自动版本化，内置对比
团队共享	手动复制、同步	一行命令拉取
在线测试	无	提供 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("LANGCHAIN_API_KEY"):
    sys.exit("请设置环境变量 LANGCHAIN_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, prompt=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()

总结

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

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