您可以使用 LangSmith Python、TypeScript 和 Java SDK 以编程方式管理提示词。

安装包

在 Python 中，您可以直接使用 LangSmith SDK（*推荐，功能完整*），或者通过 LangChain 包使用（仅支持推送和拉取提示词）。

在 TypeScript 中，您必须使用 LangChain npm 包来拉取提示词（它也支持推送）。对于所有其他功能，请使用 LangSmith 包。

pip install -U langsmith # version >= 0.1.99

uv add langsmith  # version >= 0.1.99

yarn add langsmith langchain # langsmith version >= 0.1.99 and langchain version >= 0.2.14

implementation("com.langchain.smith:langsmith-java:0.1.0-beta.4")

配置环境变量

如果您已有 LANGSMITH_API_KEY 设置为 LangSmith 当前工作区的 API 密钥，则可以跳过此步骤。

否则，请通过导航到以下位置获取工作区的 API 密钥 Settings > API Keys > Create API Key 在 LangSmith 中。

设置您的环境变量。

推送提示词

要创建新提示词或更新现有提示词，您可以使用 push prompt method.

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)
# url is a link to the prompt in the UI
print(url)

from langchain_classic import hub as prompts
from langchain_core.prompts import ChatPromptTemplate

prompt = ChatPromptTemplate.from_template("tell me a joke about {topic}")
url = prompts.push("joke-generator", prompt)
# url is a link to the prompt in the UI
print(url)

const prompt = ChatPromptTemplate.fromTemplate("tell me a joke about {topic}");
const url = hub.push("joke-generator", {
  object: prompt,
});
// url is a link to the prompt in the UI
console.log(url);

您也可以将提示词作为提示词和模型的 RunnableSequence 来推送。这对于存储您想与此提示词一起使用的模型配置非常有用。提供商必须受 Playground 支持，请参阅 支持的模型提供商.

from langsmith import Client
from langchain_core.prompts import ChatPromptTemplate
from langchain_openai import ChatOpenAI

client = Client()
model = ChatOpenAI(model="gpt-5.4-mini")
prompt = ChatPromptTemplate.from_template("tell me a joke about {topic}")
chain = prompt | model
client.push_prompt("joke-generator-with-model", object=chain)

from langchain_classic import hub as prompts
from langchain_core.prompts import ChatPromptTemplate
from langchain_openai import ChatOpenAI

model = ChatOpenAI(model="gpt-5.4-mini")
prompt = ChatPromptTemplate.from_template("tell me a joke about {topic}")
chain = prompt | model
url = prompts.push("joke-generator-with-model", chain)
# url is a link to the prompt in the UI
print(url)

const model = new ChatOpenAI({ model: "gpt-5.4-mini" });
const prompt = ChatPromptTemplate.fromTemplate("tell me a joke about {topic}");
const chain = prompt.pipe(model);
await hub.push("joke-generator-with-model", {
  object: chain,
});

推送一个 StructuredPrompt

A StructuredPrompt 将提示模板与输出模式结合，确保模型以预定义的结构返回数据。使用 StructuredPrompt.from_messages_and_schema (Python) 或 StructuredPrompt.fromMessagesAndSchema (TypeScript) 创建一个，然后像推送其他提示一样将其推送到 hub。

不指定模型

当您想要独立于任何模型配置存储模板和模式时，单独推送结构化提示。

from langsmith import Client
from langchain_core.prompts.structured import StructuredPrompt
from pydantic import BaseModel, Field

class ResponseSchema(BaseModel):
    positive_sentiment: bool = Field(description="Was the user sentiment positive?")

prompt = StructuredPrompt.from_messages_and_schema(
    [
        ("system", "Evaluate the sentiment of the following conversation."),
        ("human", "{conversation}"),
    ],
    schema=ResponseSchema.model_json_schema(),
)

client = Client()
url = client.push_prompt("sentiment-evaluator", object=prompt)
print(url)

const schema = {
  title: "ResponseSchema",
  type: "object",
  properties: {
    positive_sentiment: {
      type: "boolean",
      description: "Was the user sentiment positive?",
    },
  },
  required: ["positive_sentiment"],
};

const prompt = StructuredPrompt.fromMessagesAndSchema(
  [
    ["system", "Evaluate the sentiment of the following conversation."],
    ["human", "{conversation}"],
  ],
  schema
);

const url = await hub.push("sentiment-evaluator", prompt);
console.log(url);

使用模型

将结构化提示作为 RunnableSequence 与模型一起推送，以在 hub 中存储完整的管道，包括模型配置。

from langsmith import Client
from langchain_core.prompts.structured import StructuredPrompt
from langchain_openai import ChatOpenAI
from pydantic import BaseModel, Field

class ResponseSchema(BaseModel):
    positive_sentiment: bool = Field(description="Was the user sentiment positive?")

prompt = StructuredPrompt.from_messages_and_schema(
    [
        ("system", "Evaluate the sentiment of the following conversation."),
        ("human", "{conversation}"),
    ],
    schema=ResponseSchema.model_json_schema(),
)

model = ChatOpenAI(model="gpt-4o-mini")
chain = prompt | model

client = Client()
url = client.push_prompt("sentiment-evaluator-with-model", object=chain)
print(url)

拉取提示

要拉取提示，您可以使用 pull prompt 方法，该方法将提示作为 langchain PromptTemplate.

要拉取 **私有提示** 您无需指定所有者句柄（不过，如果您已设置，可以指定）。

要拉取 **公共提示** 从 LangChain Hub 拉取，您需要指定提示作者的句柄。

from langsmith import Client
from langchain_openai import ChatOpenAI

client = Client()
prompt = client.pull_prompt("joke-generator")
model = ChatOpenAI(model="gpt-5.4-mini")
chain = prompt | model
chain.invoke({"topic": "cats"})

from langchain_classic import hub as prompts
from langchain_openai import ChatOpenAI

prompt = prompts.pull("joke-generator")
model = ChatOpenAI(model="gpt-5.4-mini")
chain = prompt | model
chain.invoke({"topic": "cats"})

const prompt = await hub.pull("joke-generator");
const model = new ChatOpenAI({ model: "gpt-5.4-mini" });
const chain = prompt.pipe(model);
await chain.invoke({"topic": "cats"});

Similar to pushing a prompt, you can also pull a prompt as a RunnableSequence of a prompt and a model. Just specify include\_在拉取提示时指定模型。如果存储的提示包含模型，它将作为 RunnableSequence 返回。请确保为您使用的模型设置了正确的环境变量。

from langsmith import Client

client = Client()
chain = client.pull_prompt("joke-generator-with-model", include_model=True)
chain.invoke({"topic": "cats"})

from langchain_classic import hub as prompts

chain = prompts.pull("joke-generator-with-model", include_model=True)
chain.invoke({"topic": "cats"})

const chain = await hub.pull("joke-generator-with-model", { includeModel: true });
await chain.invoke({"topic": "cats"});

在拉取提示时，您还可以指定特定的提交哈希或 提交标签 来拉取提示的特定版本。

prompt = client.pull_prompt("joke-generator:12344e88")

prompt = prompts.pull("joke-generator:12344e88")

const prompt = await hub.pull("joke-generator:12344e88")

从 LangChain Hub 拉取公共提示时，您需要指定提示作者的句柄。

prompt = client.pull_prompt("efriis/my-first-prompt")

prompt = prompts.pull("efriis/my-first-prompt")

const prompt = await hub.pull("efriis/my-first-prompt")

提示词缓存

LangSmith SDK 包含内置的内存提示词缓存。启用后，LangSmith 会在内存中缓存拉取的提示词，减少频繁使用提示词的延迟和 API 调用。该缓存使用一个全局单例实例，在所有客户端之间共享，并在进程生命周期内持续存在。它实现了 stale-while-revalidate 模式，确保您的应用程序始终获得快速响应，同时在后台保持提示词更新。

Requirements: - Python SDK： langsmith >= 0.7.0 - TypeScript SDK： langsmith >= 0.5.0

默认行为

缓存默认 **启用**。启用后，默认设置为：

刷新时，全局缓存将使用最后请求给定提示词的客户端来获取新数据。

使用缓存

默认情况下，所有客户端都使用全局提示词缓存。无需配置：

from langsmith import Client
# Obtain a reference to the global cache just for logging metrics
from langsmith.prompt_cache import prompt_cache_singleton

# Caching is enabled by default using the global singleton
client = Client()

# First pull - fetches from API and caches
prompt = client.pull_prompt("joke-generator")

# Subsequent pulls - returns cached version instantly
prompt = client.pull_prompt("joke-generator")

# Check cache metrics
print(f"Cache hits: {prompt_cache_singleton.metrics.hits}")
print(f"Cache misses: {prompt_cache_singleton.metrics.misses}")
print(f"Hit rate: {prompt_cache_singleton.metrics.hit_rate:.1%}")

// Obtain a reference to the global cache just for logging metrics


// Caching is enabled by default
// First pull - fetches from API and caches
const prompt = await hub.pull("joke-generator");

// Subsequent pulls - returns cached version instantly
const prompt2 = await hub.pull("joke-generator");

// Check cache metrics
console.log(`Cache hits: ${promptCacheSingleton.metrics.hits}`);
console.log(`Cache misses: ${promptCacheSingleton.metrics.misses}`);
console.log(`Hit rate: ${(promptCacheSingleton.hitRate * 100).toFixed(1)}%`);

配置全局缓存

您可以配置所有客户端默认使用的全局提示词缓存。当您想要自定义整个应用程序的缓存行为时，这非常有用：

from langsmith import Client
from langsmith.prompt_cache import (
    configure_global_prompt_cache,
    prompt_cache_singleton,
)

# Configure global cache before creating any clients
configure_global_prompt_cache(
    max_size=200,  # Cache up to 200 prompts
    ttl_seconds=7200,  # Consider prompts stale after 2 hours
    refresh_interval_seconds=600,  # Check for stale prompts every 10 minutes
)

# All clients will use these settings
client1 = Client()
client2 = Client()

# Both clients share the same global cache with your custom settings
prompt1 = client1.pull_prompt("prompt-1")
prompt2 = client2.pull_prompt("prompt-2")

# Check global cache metrics
print(f"Global cache hits: {prompt_cache_singleton.metrics.hits}")
print(f"Global cache misses: {prompt_cache_singleton.metrics.misses}")

  configureGlobalPromptCache,
  promptCacheSingleton,
} from "langsmith";

// Configure global cache before pulling prompts
configureGlobalPromptCache({
  maxSize: 200,  // Cache up to 200 prompts
  ttlSeconds: 7200,  // Consider prompts stale after 2 hours
  refreshIntervalSeconds: 600,  // Check for stale prompts every 10 minutes
});

// All hub.pull calls will use these settings
const prompt1 = await hub.pull("prompt-1");
const prompt2 = await hub.pull("prompt-2");

// Check global cache metrics
console.log(`Global cache hits: ${promptCacheSingleton.metrics.hits}`);
console.log(`Global cache misses: ${promptCacheSingleton.metrics.misses}`);

禁用缓存

要为特定客户端禁用缓存，请传递 disable_prompt_cache=True。您也可以在全球范围内配置最大大小为零：

from langsmith import Client

# Disable caching for this client
client = Client(disable_prompt_cache=True)

# Every pull will fetch from the API
prompt = client.pull_prompt("joke-generator")

// Disable caching globally
configureGlobalPromptCache({ maxSize: 0 });

// Every pull will fetch from the API
const prompt = await hub.pull("joke-generator");

跳过缓存

要绕过缓存并为单个请求从 API 获取新的提示词，请使用 skip_cache parameter:

# Force a fresh fetch, ignoring any cached version
prompt = client.pull_prompt("joke-generator", skip_cache=True)

// Force a fresh fetch, ignoring any cached version
const prompt = await hub.pull("joke-generator", { skipCache: true });

当您需要确保拥有最新版本的提示词时，这很有用，例如在 LangSmith UI 中进行更改后。

离线模式

对于网络连接有限或无网络连接的环境，您可以预填充缓存并离线使用。设置 ttl_seconds to None （Python）或 null （TypeScript）以防止缓存条目过期并禁用后台刷新。

步骤 1：将提示词导出到缓存文件（在线时）

from langsmith import Client
from langsmith.prompt_cache import prompt_cache_singleton

# Create client (caching is enabled by default)
client = Client()

# Pull the prompts you need
client.pull_prompt("prompt-1")
client.pull_prompt("prompt-2")
client.pull_prompt("prompt-3")

# Export cache to a file
prompt_cache_singleton.dump("prompts_cache.json")

// Caching is enabled by default

// Pull the prompts you need
await hub.pull("prompt-1");
await hub.pull("prompt-2");
await hub.pull("prompt-3");

// Export cache to a file
promptCacheSingleton.dump("prompts_cache.json");

步骤 2：在离线环境中加载缓存文件

from langsmith import Client
from langsmith.prompt_cache import (
    configure_global_prompt_cache,
    prompt_cache_singleton,
)

# Configure cache with infinite TTL (never expire, no background refresh)
configure_global_prompt_cache(ttl_seconds=None)

# Load the cache file
prompt_cache_singleton.load("prompts_cache.json")

# Create client (uses the loaded cache)
client = Client()

# Uses cached version without any API calls
prompt = client.pull_prompt("prompt-1")

  configureGlobalPromptCache,
  promptCacheSingleton,
} from "langsmith";

// Configure cache with infinite TTL (never expire, no background refresh)
configureGlobalPromptCache({ ttlSeconds: null });

// Load the cache file
promptCacheSingleton.load("prompts_cache.json");

// Uses cached version without any API calls
const prompt = await hub.pull("prompt-1");

缓存操作

缓存支持多种用于管理缓存提示词的操作：

from langsmith import Client
from langsmith.prompt_cache import prompt_cache_singleton

client = Client()

# Invalidate a specific prompt from cache
prompt_cache_singleton.invalidate("joke-generator:latest")

# Clear all cached prompts
prompt_cache_singleton.clear()

# Reset metrics
prompt_cache_singleton.reset_metrics()

# Check if cache is running background refresh
# (only runs if ttl_seconds is not None)
if prompt_cache_singleton._refresh_thread is not None:
    print("Background refresh is active")

// Invalidate a specific prompt from cache
promptCacheSingleton.invalidate("joke-generator:latest");

// Clear all cached prompts
promptCacheSingleton.clear();

// Reset metrics
promptCacheSingleton.resetMetrics();

清理

您可以手动调用 stop() 来停止后台刷新任务：

prompt_cache_singleton.stop()

promptCacheSingleton.stop();

不使用 LangChain 使用提示词

如果您想在 LangSmith 中存储提示词，但直接通过模型提供商的 API 使用它们，您可以使用我们的转换方法。这些方法会将您的提示词转换为 OpenAI 或 Anthropic API 所需的负载。

这些转换方法依赖于 LangChain 集成包中的逻辑，您还需要安装相应的包作为依赖项，以及您选择的官方 SDK。以下是一些示例：

OpenAI

pip install -U langchain_openai

yarn add @langchain/openai @langchain/core # @langchain/openai version >= 0.3.2

from openai import OpenAI
from langsmith.client import Client, convert_prompt_to_openai_format

# langsmith client
client = Client()
# openai client
oai_client = OpenAI()

# pull prompt and invoke to populate the variables
prompt = client.pull_prompt("joke-generator")
prompt_value = prompt.invoke({"topic": "cats"})
openai_payload = convert_prompt_to_openai_format(prompt_value)
openai_response = oai_client.chat.completions.create(**openai_payload)

const prompt = await hub.pull("jacob/joke-generator");
const formattedPrompt = await prompt.invoke({
  topic: "cats",
});
const { messages } = convertPromptToOpenAI(formattedPrompt);

const openAIClient = new OpenAI();
const openAIResponse = await openAIClient.chat.completions.create({
  model: "gpt-5.4-mini",
  messages,
});

Anthropic

pip install -U langchain_anthropic

yarn add @langchain/anthropic @langchain/core # @langchain/anthropic version >= 0.3.3

from anthropic import Anthropic
from langsmith.client import Client, convert_prompt_to_anthropic_format

# langsmith client
client = Client()
# anthropic client
anthropic_client = Anthropic()

# pull prompt and invoke to populate the variables
prompt = client.pull_prompt("joke-generator")
prompt_value = prompt.invoke({"topic": "cats"})
anthropic_payload = convert_prompt_to_anthropic_format(prompt_value)
anthropic_response = anthropic_client.messages.create(**anthropic_payload)

const prompt = await hub.pull("jacob/joke-generator");
const formattedPrompt = await prompt.invoke({
  topic: "cats",
});
const { messages, system } = convertPromptToAnthropic(formattedPrompt);

const anthropicClient = new Anthropic();
const anthropicResponse = await anthropicClient.messages.create({
  model: "claude-haiku-4-5-20251001",
  system,
  messages,
  max_tokens: 1024,
  stream: false,
});

列出、删除和收藏提示词

You can also list, delete, and like/unlike prompts using the list prompts, delete prompt, like prompt 和 unlike prompt 方法。请参阅 LangSmith SDK 客户端 以获取这些方法的详细文档。

# List all prompts in my workspace
prompts = client.list_prompts()

# List my private prompts that include "joke"
prompts = client.list_prompts(query="joke", is_public=False)

# Delete a prompt
client.delete_prompt("joke-generator")

# Like a prompt
client.like_prompt("efriis/my-first-prompt")

# Unlike a prompt
client.unlike_prompt("efriis/my-first-prompt")

// List all prompts in my workspace


const client = new Client({ apiKey: "lsv2_..." });
const prompts = client.listPrompts();

for await (const prompt of prompts) {
  console.log(prompt);
}

// List my private prompts that include "joke"
const private_joke_prompts = client.listPrompts({ query: "joke", isPublic: false});

// Delete a prompt
client.deletePrompt("joke-generator");

// Like a prompt
client.likePrompt("efriis/my-first-prompt");

// Unlike a prompt
client.unlikePrompt("efriis/my-first-prompt");