@traceable装饰器:推荐用于大多数情况trace上下文管理器:仅限 PythonRunTreeAPI:显式、底层控制
- 指定自定义运行 ID,这对于在运行后立即附加反馈或与外部系统关联很有用。
- 确保在退出前提交所有追踪。
如果您使用的是内置 LangSmith 集成的 LLM 提供商或代理框架,请参阅集成概述。
前提条件
在追踪之前,请设置以下环境变量:-
LANGSMITH_TRACING=true:启用追踪。设置此变量可以在不更改代码的情况下切换追踪的开启和关闭。LANGSMITH_TRACING控制@traceable装饰器和trace上下文管理器。要在运行时为@traceable覆盖此设置而不更改环境变量,请使用tracing_context(enabled=True/False)(Python)或直接向traceable传递tracingEnabled(JS/TS)。RunTree对象不受这些控制中的任何一个影响;它们在发布时总是向 LangSmith 发送数据。 -
LANGSMITH_API_KEY:您的 LangSmith API 密钥。 -
默认情况下,LangSmith 将追踪记录到名为
default的项目中。要记录到不同的项目,请设置LANGSMITH_PROJECT。更多详情,请参阅将追踪记录到特定项目。
使用 @traceable / traceable
将 @traceable(Python)或 traceable(TypeScript)应用于任何函数,使其成为被追踪的运行。LangSmith 会自动处理嵌套调用之间的上下文传播。
以下示例追踪一个简单的管道:run_pipeline 调用 format_prompt 构建消息,调用 invoke_llm 调用模型,然后调用 parse_output 提取结果。
每个函数都被单独追踪,并且由于它们是从 run_pipeline(也被追踪)内部调用的,LangSmith 会自动将它们嵌套为子运行。invoke_llm 使用 run_type="llm" 将其标记为 LLM 调用,以便 LangSmith 可以正确渲染令牌计数和延迟:
run_pipeline 追踪,其中 format_prompt、invoke_llm 和 parse_output 作为嵌套的子运行。
当您用
traceable 包装同步函数(例如,前面示例中的 formatPrompt)时,请在调用它时使用 await 关键字,以确保追踪被正确记录。使用 trace 上下文管理器(仅限 Python)
在 Python 中,您可以使用 trace 上下文管理器将追踪记录到 LangSmith。这在以下情况下很有用:
- 您想为特定代码块记录追踪。
- 您想控制追踪的输入、输出和其他属性。
- 使用装饰器或包装器不可行。
- 以上任何或全部情况。
traceable 装饰器和 wrap_openai 包装器无缝集成,因此您可以在同一应用程序中一起使用它们。
以下示例展示了三者一起使用的情况。wrap_openai 包装 OpenAI 客户端,使其调用被自动追踪。my_tool 使用带有 run_type="tool" 和自定义 name 的 @traceable,以便在追踪中正确显示。chat_pipeline 本身没有被装饰;相反,ls.trace 包装了调用,允许您显式传递项目名称和输入,并通过 rt.end() 手动设置输出:
使用 RunTree API
另一种将追踪记录到 LangSmith 的更显式的方法是通过 RunTree API。此 API 允许您对追踪进行更多控制。您可以手动创建运行和子运行来组装您的追踪。您仍然需要设置 LANGSMITH_API_KEY,但此方法不需要 LANGSMITH_TRACING。
此方法不推荐用于大多数用例;与自动处理上下文传播的 @traceable 相比,手动管理追踪上下文容易出错。
示例用法
您可以扩展上一节中解释的实用程序来追踪任何代码。以下代码显示了一些示例扩展。 追踪类中的任何公共方法:指定自定义运行 ID
默认情况下,LangSmith 为每个运行分配一个随机 ID。当您需要提前知道运行 ID 时(例如,在运行后立即附加反馈),可以覆盖此 ID,将 LangSmith 运行与外部系统的 ID 关联,或使用确定性 ID 使运行幂等。自定义运行 ID 请使用 UUID v7。UUIDv7 嵌入时间戳,这保留了追踪中运行的正确时间顺序。LangSmith SDK 导出了一个
uuid7 辅助函数(Python v0.4.43+,JS v0.3.80+):- Python:
from langsmith import uuid7 - JS/TS:
import { uuid7 } from 'langsmith'
-
@traceable:在调用@traceable函数时,在langsmith_extra中传递run_id(Python),或在传递给traceable的配置对象中传递id(TypeScript): -
trace上下文管理器(仅限 Python):直接向 trace 上下文管理器构造函数传递run_id:Python
确保在退出前提交所有追踪
LangSmith 在后台线程中执行追踪,以避免阻碍您的生产应用程序。这意味着您的进程可能在所有追踪成功发布到 LangSmith 之前结束。请参阅以下选项:- 如果您使用的是 LangChain,请参阅 LangChain 追踪指南。
-
如果您独立使用 LangSmith SDK,可以在退出前使用
flush方法:
相关内容
- 可观测性概念:关于运行、追踪和 LangSmith 数据模型的背景
- 运行(跨度)数据格式:运行字段的模式参考,包括
dotted_order、trace_id和parent_run_id - 使用 SDK 记录用户反馈:预先指定运行 ID 的常见用例
- 在被追踪的函数中访问当前运行(跨度):从追踪内部读取或修改活动运行
- 将追踪记录到特定项目:将追踪路由到命名项目而不是
default - 使用 API 追踪:SDK 的底层 REST API 替代方案
- 追踪基础视频,来自 LangSmith 入门课程
将这些文档连接到 Claude、VSCode 等,通过 MCP 获取实时答案。

