Skip to main content
LangSmith 与 LangChain(Python 和 JavaScript)无缝集成,后者是构建 LLM 应用的热门开源框架。

安装

为 Python 或 JS 安装以下内容(代码片段使用 OpenAI 集成)。 有关可用包的完整列表,请参阅 LangChain 文档

快速开始

1. 配置你的环境

如果你正在将 LangChain.js 与 LangSmith 一起使用,并且不在无服务器环境中,我们还建议显式设置以下内容以减少延迟:export LANGCHAIN_CALLBACKS_BACKGROUND=true如果你在无服务器环境中,我们建议设置相反的值以允许追踪在函数结束前完成:export LANGCHAIN_CALLBACKS_BACKGROUND=false

2. 记录追踪

无需额外代码即可将追踪记录到 LangSmith。只需像往常一样运行你的 LangChain 代码。

3. 查看你的追踪

默认情况下,追踪将记录到名为 default 的项目中。你可以在 LangSmith 中公开查看使用上述代码记录的追踪示例。

选择性追踪

上一节展示了如何通过设置单个环境变量来追踪应用程序中所有 LangChain 可运行对象的调用。虽然这是一种方便的入门方式,但你可能只想追踪特定的调用或应用程序的部分。 在 Python 中有两种方法:手动传入 LangChainTracer 实例作为回调,或使用 tracing_context 上下文管理器 在 JS/TS 中,你可以传入 LangChainTracer 实例作为回调。

记录到特定项目

静态配置

追踪概念指南中所述,LangSmith 使用项目概念来分组追踪。如果未指定,追踪器项目将设置为默认值。你可以设置 LANGSMITH_PROJECT 环境变量来为整个应用程序运行配置自定义项目名称。这应在执行应用程序之前完成。
LANGSMITH_PROJECT 标志仅在 JS SDK 版本 >= 0.2.16 中受支持,如果你使用的是旧版本,请改用 LANGCHAIN_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 中来自 langsmithtraceable)在模型调用周围创建自定义运行。

在追踪中覆盖模型名称

追踪 LangChain 模型调用时,LangSmith 会自动捕获 API 调用中使用的模型标识符。但是,你可能希望在追踪中显示不同的、更具描述性的名称,以便于组织或区分不同的模型配置。你可以通过在构造或配置 LangChain 模型时传递 ls_model_name 元数据参数来实现。 这在以下情况下特别有用:
  • 使用自托管或本地模型,其中模型 ID 可能不具描述性。
  • 使用相同模型但不同配置,并希望在追踪中区分它们。
  • 为模型创建别名,使追踪对你的团队更具可读性。
  • 在不同部署环境中标准化模型名称。
当你在模型的元数据中传递 ls_model_name 时,此名称将出现在涉及该模型实例的所有追踪的 LangSmith UI 中。这适用于任何 LangChain 聊天模型或 LLM,并且会被使用该模型的所有运行继承,包括当它是链的一部分时。
ls_model_name 元数据参数也用于成本跟踪。与 ls_provider 参数结合使用时,LangSmith 可以自动计算自定义或自托管模型的成本。有关所有可用元数据参数的更多信息,请参阅元数据参数参考

自定义运行 ID

你可以在调用或流式传输 LangChain 代码时通过在 Config 中提供 ID 来自定义给定运行的 ID。此 ID 用于在 LangSmith 中唯一标识运行,并可用于查询特定运行。该 ID 对于链接不同系统中的运行或实现自定义跟踪逻辑非常有用。这可以通过在构造时在 RunnableConfig 对象中设置 run_id,或在调用参数中传递 run_id 来实现。
此功能目前不直接支持 LLM 对象。
请注意,如果你在追踪的(即顶层运行)执行此操作,该运行 ID 将用作 trace_id

访问 LangChain 调用的运行(跨度)ID

当你调用 LangChain 对象时,你可以手动指定调用的运行 ID。此运行 ID 可用于在 LangSmith 中查询运行。 在 JS/TS 中,你可以使用 RunCollectorCallbackHandler 实例来访问运行 ID。

确保在退出前提交所有追踪

在 LangChain Python 中,LangSmith 的追踪在后台线程中完成,以避免阻碍你的生产应用程序。这意味着你的进程可能在所有追踪成功发布到 LangSmith 之前结束。这在无服务器环境中尤其普遍,因为一旦你的链或代理完成,你的虚拟机可能会立即终止。 你可以通过将 LANGCHAIN_CALLBACKS_BACKGROUND 环境变量设置为 "false" 来使回调同步。 对于两种语言,LangChain 都提供了方法来在退出应用程序之前等待追踪提交。以下是一个示例:

不设置环境变量进行追踪

如其他指南中所述,以下环境变量允许你配置追踪启用、API 端点、API 密钥和追踪项目:
  • LANGSMITH_TRACING
  • LANGSMITH_API_KEY
  • LANGSMITH_ENDPOINT
  • LANGSMITH_PROJECT
然而,在某些环境中,无法设置环境变量。在这些情况下,你可以以编程方式设置追踪配置。 这主要建立在上一节的基础上。

使用 LangChain(Python)进行分布式追踪

LangSmith 支持使用 LangChain Python 进行分布式追踪。这允许你链接不同服务和应用程序中的运行(跨度)。其原理与 LangSmith SDK 的分布式追踪指南类似。

LangChain(Python)和 LangSmith SDK 之间的互操作性

如果你在应用程序的一部分使用 LangChain,在其他部分使用 LangSmith SDK(参见自定义检测),你仍然可以无缝地追踪整个应用程序。 LangChain 对象在 traceable 函数内调用时将被追踪,并作为 traceable 函数的子运行绑定。
这将产生以下追踪树:追踪树 Python 互操作

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 结合使用时存在以下限制:
  1. 修改从 RunnableLambda 上下文的 getCurrentRunTree() 获取的 RunTree 将导致无操作。
  2. 不鼓励遍历通过 getCurrentRunTree() 从 RunnableLambda 获取的 RunTree,因为它可能不包含所有 RunTree 节点。
  3. 不同的子运行可能具有相同的 execution_orderchild_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 包装函数的第一个参数传递。
如果你更喜欢视频教程,请查看 LangSmith 课程介绍中的替代追踪方式视频