安装
为 Python 或 JS 安装以下内容(代码片段使用 OpenAI 集成)。 有关可用包的完整列表,请参阅 LangChain 文档。快速开始
1. 配置你的环境
如果你正在将 LangChain.js 与 LangSmith 一起使用,并且不在无服务器环境中,我们还建议显式设置以下内容以减少延迟:
export LANGCHAIN_CALLBACKS_BACKGROUND=true如果你在无服务器环境中,我们建议设置相反的值以允许追踪在函数结束前完成:export LANGCHAIN_CALLBACKS_BACKGROUND=false2. 记录追踪
无需额外代码即可将追踪记录到 LangSmith。只需像往常一样运行你的 LangChain 代码。3. 查看你的追踪
默认情况下,追踪将记录到名为default 的项目中。你可以在 LangSmith 中公开查看使用上述代码记录的追踪示例。
选择性追踪
上一节展示了如何通过设置单个环境变量来追踪应用程序中所有 LangChain 可运行对象的调用。虽然这是一种方便的入门方式,但你可能只想追踪特定的调用或应用程序的部分。 在 Python 中有两种方法:手动传入LangChainTracer 实例作为回调,或使用 tracing_context 上下文管理器。
在 JS/TS 中,你可以传入 LangChainTracer 实例作为回调。
记录到特定项目
静态配置
如追踪概念指南中所述,LangSmith 使用项目概念来分组追踪。如果未指定,追踪器项目将设置为默认值。你可以设置LANGSMITH_PROJECT 环境变量来为整个应用程序运行配置自定义项目名称。这应在执行应用程序之前完成。
动态配置
这主要建立在上一节的基础上,允许你为特定的LangChainTracer 实例设置项目名称,或在 Python 中作为 tracing_context 上下文管理器的参数。
向追踪添加元数据和标签
你可以通过在RunnableConfig 中提供任意元数据和标签来注释你的追踪。这对于将附加信息与追踪关联非常有用,例如执行环境或发起它的用户。有关如何按元数据和标签查询追踪和运行的信息,请参阅查询追踪(SDK)。
当你将元数据或标签附加到可运行对象(通过
RunnableConfig 或在运行时通过调用参数)时,它们会被该可运行对象的所有子可运行对象继承。自定义运行名称
你可以在调用或流式传输 LangChain 代码时通过在 Config 中提供名称来自定义给定运行的名称。此名称用于在 LangSmith 中标识运行,并可用于过滤和分组运行。该名称也用作 LangSmith UI 中运行的标题。这可以通过在构造时在RunnableConfig 对象中设置 run_name,或在 JS/TS 中在调用参数中传递 run_name 来实现。
run_name 参数仅更改你调用的可运行对象(例如,链、函数)的名称。它不会重命名调用 LLM 对象(如 ChatOpenAI (gpt-5.4-mini))时自动创建的嵌套运行。在示例中,外层运行将在 LangSmith 中显示为 MyCustomChain,而嵌套的 LLM 运行仍显示模型的默认名称。要为 LLM 运行提供更有意义的名称,你可以:- 将模型包装在另一个可运行对象中,并为该步骤分配一个
run_name。 - 使用追踪装饰器或辅助函数(例如,Python 中的
@traceable,或 JS/TS 中来自langsmith的traceable)在模型调用周围创建自定义运行。
在追踪中覆盖模型名称
追踪 LangChain 模型调用时,LangSmith 会自动捕获 API 调用中使用的模型标识符。但是,你可能希望在追踪中显示不同的、更具描述性的名称,以便于组织或区分不同的模型配置。你可以通过在构造或配置 LangChain 模型时传递ls_model_name 元数据参数来实现。
这在以下情况下特别有用:
- 使用自托管或本地模型,其中模型 ID 可能不具描述性。
- 使用相同模型但不同配置,并希望在追踪中区分它们。
- 为模型创建别名,使追踪对你的团队更具可读性。
- 在不同部署环境中标准化模型名称。
ls_model_name 时,此名称将出现在涉及该模型实例的所有追踪的 LangSmith UI 中。这适用于任何 LangChain 聊天模型或 LLM,并且会被使用该模型的所有运行继承,包括当它是链的一部分时。
自定义运行 ID
你可以在调用或流式传输 LangChain 代码时通过在 Config 中提供 ID 来自定义给定运行的 ID。此 ID 用于在 LangSmith 中唯一标识运行,并可用于查询特定运行。该 ID 对于链接不同系统中的运行或实现自定义跟踪逻辑非常有用。这可以通过在构造时在RunnableConfig 对象中设置 run_id,或在调用参数中传递 run_id 来实现。
此功能目前不直接支持 LLM 对象。
trace_id。
访问 LangChain 调用的运行(跨度)ID
当你调用 LangChain 对象时,你可以手动指定调用的运行 ID。此运行 ID 可用于在 LangSmith 中查询运行。 在 JS/TS 中,你可以使用RunCollectorCallbackHandler 实例来访问运行 ID。
确保在退出前提交所有追踪
在 LangChain Python 中,LangSmith 的追踪在后台线程中完成,以避免阻碍你的生产应用程序。这意味着你的进程可能在所有追踪成功发布到 LangSmith 之前结束。这在无服务器环境中尤其普遍,因为一旦你的链或代理完成,你的虚拟机可能会立即终止。 你可以通过将LANGCHAIN_CALLBACKS_BACKGROUND 环境变量设置为 "false" 来使回调同步。
对于两种语言,LangChain 都提供了方法来在退出应用程序之前等待追踪提交。以下是一个示例:
不设置环境变量进行追踪
如其他指南中所述,以下环境变量允许你配置追踪启用、API 端点、API 密钥和追踪项目:LANGSMITH_TRACINGLANGSMITH_API_KEYLANGSMITH_ENDPOINTLANGSMITH_PROJECT
使用 LangChain(Python)进行分布式追踪
LangSmith 支持使用 LangChain Python 进行分布式追踪。这允许你链接不同服务和应用程序中的运行(跨度)。其原理与 LangSmith SDK 的分布式追踪指南类似。LangChain(Python)和 LangSmith SDK 之间的互操作性
如果你在应用程序的一部分使用 LangChain,在其他部分使用 LangSmith SDK(参见自定义检测),你仍然可以无缝地追踪整个应用程序。 LangChain 对象在traceable 函数内调用时将被追踪,并作为 traceable 函数的子运行绑定。
LangChain.JS 和 LangSmith SDK 之间的互操作性
在 traceable 内追踪 LangChain 对象(仅限 JS)
从 langchain@0.2.x 开始,LangChain 对象在 @traceable 函数内使用时会自动被追踪,继承 traceable 函数的客户端、标签、元数据和项目名称。
对于低于 0.2.x 的旧版本 LangChain,你需要手动传递从 @traceable 中找到的追踪上下文创建的 LangChainTracer 实例。
通过 traceable / RunTree API 追踪 LangChain 子运行(仅限 JS)
我们正在努力改进
traceable 和 LangChain 之间的互操作性。将 LangChain 与 traceable 结合使用时存在以下限制:- 修改从 RunnableLambda 上下文的
getCurrentRunTree()获取的 RunTree 将导致无操作。 - 不鼓励遍历通过
getCurrentRunTree()从 RunnableLambda 获取的 RunTree,因为它可能不包含所有 RunTree 节点。 - 不同的子运行可能具有相同的
execution_order和child_execution_order值。因此在极端情况下,一些运行可能最终顺序不同,具体取决于start_time。
traceable 函数作为 RunnableSequence 的一部分运行,或通过 RunTree API 命令式地追踪 LangChain 运行的子运行。从 LangSmith 0.1.39 和 @langchain/core 0.2.18 开始,你可以直接在 RunnableLambda 内调用 traceable 包装的函数。

RunTree.fromRunnableConfig 将 LangChain 的 RunnableConfig 转换为等效的 RunTree 对象,或将 RunnableConfig 作为 traceable 包装函数的第一个参数传递。
将这些文档连接到 Claude、VSCode 等,通过 MCP 获取实时答案。

