主题
追踪快速入门
在几分钟内为 LLM 应用添加 LangSmith 追踪。
LangSmith 通过捕获追踪，为你提供 LLM 应用的端到端可见性；追踪是请求期间运行的每个步骤的完整记录，从传入的输入到返回的最终输出。
在本快速入门中，你将为一个 AI 助手添加追踪，并在 LangSmith 中查看结果。
TIP
如果你使用 LangChain 或 LangGraph 构建，只需一个环境变量即可启用 LangSmith 追踪。请参阅使用 LangChain 追踪或使用 LangGraph 追踪。
前置条件
开始之前，请确保你拥有：
- LangSmith 账户：在 smith.langchain.com 注册或登录。
- LangSmith API 密钥：遵循创建 API 密钥指南。
- OpenAI API 密钥：从 OpenAI 仪表板生成。
此示例使用 OpenAI 作为 LLM 提供程序。你可以将其调整为适用于你自己的提供程序。
1. 设置环境
- 创建项目目录、安装依赖并配置所需的环境变量：
bash
mkdir ls-quickstart && cd ls-quickstart
python -m venv .venv && source .venv/bin/activate
pip install -U langsmith openaibash
mkdir ls-quickstart-ts && cd ls-quickstart-ts
npm init -y
npm install langsmith openai
npm install -D typescript tsxkotlin
implementation("com.langchain.smith:langsmith-java:0.1.0-alpha.28")在 shell 中导出环境变量：
bashexport LANGSMITH_TRACING=true export LANGSMITH_API_KEY="<your-langsmith-api-key>" export OPENAI_API_KEY="<your-openai-api-key>"要将追踪发送到特定项目，请使用
LANGSMITH_PROJECT环境变量。如果未设置，LangSmith 会在摄取追踪时自动创建一个默认追踪项目。
NOTE
如果你的账户位于美国（默认）以外的区域，还要将 LANGSMITH_ENDPOINT 设置为你的区域对应的 API URL。否则，你的 API 密钥将无法被识别，请求将无法通过身份验证。
| 区域 | 主机 / URL |
|---|---|
| GCP US | {`$ / https://${prefix_0 || "api.smith"}.langchain.com${suffix_0 || ""}`} |
| GCP EU | {`$ / https://eu.${prefix_0 || "api.smith"}.langchain.com${suffix_0 || ""}`} |
| GCP APAC | {`$ / https://apac.${prefix_0 || "api.smith"}.langchain.com${suffix_0 || ""}`} |
| AWS US | {`$ / https://aws.${prefix_0 || "api.smith"}.langchain.com${suffix_0 || ""}`} |
例如，EU 账户：export LANGSMITH_ENDPOINT="https://eu.api.smith.langchain.com"。不要在 URL 末尾添加斜杠，因为这可能导致身份验证错误。
如果你使用 Anthropic，请使用 Anthropic 包装器。如果你使用 Google Gemini，请使用 Gemini 包装器。对于其他提供程序，请使用 @traceable 装饰器手动追踪调用。
2. 构建应用
以下应用使用两个 LangSmith 工具来添加追踪：
- OpenAI 包装器：包装 OpenAI 客户端，使每次 LLM 调用都自动记录为嵌套 span。
- Traceable 包装器：包装函数，使其输入、输出和任何嵌套 span 在 LangSmith 中显示为单条追踪。在 Python 中使用
@traceable，在 TypeScript 和 Kotlin 中使用traceable，在 Java 中使用Tracing.traceFunction。
assistant 函数调用工具（get_context）以检索相关上下文，然后将该上下文传递给模型。对两个函数使用 traceable 包装器可将整个流水线捕获到一条追踪中，工具调用和 LLM 调用作为嵌套 span。
创建一个名为 app.py、index.ts、App.java 或 App.kt 的文件，内容如下：
python
from openai import OpenAI
from langsmith.wrappers import wrap_openai
from langsmith import traceable
client = wrap_openai(OpenAI()) # log every OpenAI call automatically
@traceable(run_type="tool") # trace this as a tool span
def get_context(question: str) -> str:
# In a real app, this would query a knowledge base or vector store
return "LangSmith traces are stored for 14 days on the Developer plan."
@traceable # capture the full pipeline as a single trace
def assistant(question: str) -> str:
context = get_context(question)
response = client.chat.completions.create(
model="gpt-5.4-mini",
messages=[
{
"role": "system",
"content": f"Answer using the context below.\n\nContext: {context}",
},
{"role": "user", "content": question},
],
)
return response.choices[0].message.content
if __name__ == "__main__":
print(assistant("How long are LangSmith traces stored?"))typescript
import OpenAI from "openai";
import { wrapOpenAI } from "langsmith/wrappers";
import { traceable } from "langsmith/traceable";
const client = wrapOpenAI(new OpenAI()); // log every OpenAI call automatically
const getContext = traceable(
async function getContext(question: string): Promise<string> { // trace this as a tool span
// In a real app, this would query a knowledge base or vector store
return "LangSmith traces are stored for 14 days on the Developer plan.";
},
{ run_type: "tool" }
);
const assistant = traceable(async function assistant(question: string) { // capture the full pipeline as a single trace
const context = await getContext(question);
const response = await client.chat.completions.create({
model: "gpt-5.4-mini",
messages: [
{
role: "system",
content: `Answer using the context below.\n\nContext: ${context}`,
},
{ role: "user", content: question },
],
});
return response.choices[0]?.message?.content ?? null;
});
(async () => {
console.log(await assistant("How long are LangSmith traces stored?"));
})();java
import com.langchain.smith.tracing.RunType;
import com.langchain.smith.tracing.TraceConfig;
import com.langchain.smith.tracing.Tracing;
import com.langchain.smith.wrappers.openai.OpenAITracing;
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.ChatModel;
import com.openai.models.chat.completions.ChatCompletion;
import com.openai.models.chat.completions.ChatCompletionCreateParams;
import com.openai.models.chat.completions.ChatCompletionMessageParam;
import com.openai.models.chat.completions.ChatCompletionSystemMessageParam;
import com.openai.models.chat.completions.ChatCompletionUserMessageParam;
import java.util.function.Function;
class ObservabilityQuickstartApp {
public static void main(String[] args) {
new ObservabilityQuickstartRunner().run();
}
private static final class ObservabilityQuickstartRunner {
private final OpenAIClient client =
OpenAITracing.wrapOpenAI(OpenAIOkHttpClient.fromEnv());
private final Function<String, String> getContext =
Tracing.traceFunction(
question -> "LangSmith traces are stored for 14 days on the Developer plan.",
TraceConfig.builder().name("get_context").runType(RunType.TOOL).build());
private final Function<String, String> assistant =
Tracing.traceFunction(
question -> {
String context = getContext.apply(question);
ChatCompletion response =
client.chat()
.completions()
.create(
ChatCompletionCreateParams.builder()
.model(ChatModel.GPT_5_5)
.addMessage(
ChatCompletionMessageParam.ofSystem(
ChatCompletionSystemMessageParam.builder()
.content(
"Answer using the context below.\n\nContext: " + context)
.build()))
.addMessage(
ChatCompletionMessageParam.ofUser(
ChatCompletionUserMessageParam.builder()
.content(question)
.build()))
.build());
return response.choices().get(0).message().content().orElse("");
},
TraceConfig.builder().name("assistant").build());
void run() {
System.out.println(assistant.apply("How long are LangSmith traces stored?"));
}
}
}View example trace
打开本示例的一个公开 LangSmith 运行记录。
kotlin
import com.langchain.smith.tracing.RunType
import com.langchain.smith.tracing.TraceConfig
import com.langchain.smith.tracing.traceable
import com.langchain.smith.wrappers.openai.wrapOpenAI
import com.openai.client.okhttp.OpenAIOkHttpClient
import com.openai.models.ChatModel
import com.openai.models.chat.completions.ChatCompletionCreateParams
import com.openai.models.chat.completions.ChatCompletionMessageParam
import com.openai.models.chat.completions.ChatCompletionSystemMessageParam
import com.openai.models.chat.completions.ChatCompletionUserMessageParam
import kotlin.jvm.optionals.getOrNull
val client = wrapOpenAI(OpenAIOkHttpClient.fromEnv())
val getContext =
traceable(
{ _: String -> "LangSmith traces are stored for 14 days on the Developer plan." },
TraceConfig.builder().name("get_context").runType(RunType.TOOL).build(),
)
val assistant =
traceable(
{ question: String ->
val context = getContext(question)
val response =
client.chat().completions().create(
ChatCompletionCreateParams.builder()
.model(ChatModel.GPT_5_5)
.addMessage(
ChatCompletionMessageParam.ofSystem(
ChatCompletionSystemMessageParam.builder()
.content("Answer using the context below.\n\nContext: $context")
.build(),
),
)
.addMessage(
ChatCompletionMessageParam.ofUser(
ChatCompletionUserMessageParam.builder()
.content(question)
.build(),
),
)
.build(),
)
response.choices()[0].message().content().getOrNull().orEmpty()
},
TraceConfig.builder().name("assistant").build(),
)
println(assistant("How long are LangSmith traces stored?"))View example trace
打开本示例的一个公开 LangSmith 运行记录。
3. 运行应用
bash
python app.pybash
npx tsx index.tsbash
./gradlew run4. 查看追踪
在 LangSmith UI 中，转到 Tracing 并选择你的 default 项目。点击 assistant 行打开追踪。Trajectory 选项卡显示发送给模型的对话。选择 Details 选项卡查看完整运行树，包括带有 get_context 工具调用的 assistant 函数以及嵌套在其中的 OpenAI 调用。
外层的 span 捕获 assistant 函数的输入和输出。嵌套的 get_context span 记录工具调用，ChatOpenAI span 记录发送给模型的确切提示词和返回的响应。
TIP
你也可以使用 LangSmith CLI 从终端检查追踪。
后续步骤
- 追踪集成：LangChain、LangGraph、Anthropic 和其他提供程序。
- 追踪 LLM 应用：从原型到生产的完整生命周期教程。
- 筛选追踪：搜索和浏览大型追踪项目。
- 记录到特定项目：将追踪发送到命名项目而不是 default。
INFO
记录追踪后，使用 Chat 分析它们，并获取关于应用性能的 AI 驱动洞察。