当您使用 LangSmith 追踪 LLM 调用时,通常希望跟踪成本、比较模型配置并分析不同提供商的性能。LangSmith 的原生集成(如 LangChain 或 OpenAI/Anthropic 封装器)会自动处理这些,但自定义模型封装器和自托管模型需要一种标准化的方式来提供此信息。LangSmith 使用 ls_ 元数据参数来实现这一目的。 这些元数据参数(均以 ls_ 为前缀)允许您通过标准的 metadata 字段传递模型配置和标识信息。一旦设置,LangSmith 就可以自动计算成本、在用户界面中显示模型信息,并支持对您的追踪进行过滤和分析。 使用 ls_ 元数据参数可以:
  • 启用自动成本跟踪:通过标识提供商和模型名称,为自定义或自托管模型自动计算成本。
  • 跟踪模型配置:如温度、最大 token 数等参数,便于实验比较。
  • 过滤和分析追踪:按提供商或配置设置进行筛选。
  • 自定义消息视图渲染:用于自定义的智能体插桩。
  • 标记中断错误:使 LangSmith 能将中断的运行与其他错误分开渲染。
  • 改进调试:准确记录每次运行所使用的模型设置。

基本用法示例

最常见的用例是为自定义模型封装器启用成本跟踪。为此,您需要提供两条关键信息:提供商名称 (ls_provider) 和模型名称 (ls_model_name)。它们共同工作,与 LangSmith 的定价数据库进行匹配。
这个最小化设置告诉 LangSmith 您正在使用哪个模型,如果该模型存在于定价数据库中,或者您配置了自定义定价,就能启用自动成本计算。 要获得更全面的跟踪,您可以包含额外的配置参数。这在运行实验或比较不同模型设置时特别有用:
通过此设置,您之后可以按温度筛选追踪、比较具有不同最大 token 设置的运行,或者分析哪些配置参数产生了最佳结果。除了成本跟踪所需的 ls_provider 和 ls_model_name 配对外,所有这些参数都是可选的。

所有参数

用户可配置参数

* ls_provider 和 ls_model_name 必须同时提供才能进行成本跟踪

系统生成参数

实验参数

参数详情

ls_provider

功能: 标识 LLM 提供商。与 ls_model_name 结合,通过与 LangSmith 模型定价数据库 匹配来启用自动成本计算。 常见值:
  • "openai"
  • "anthropic"
  • "azure"
  • "bedrock"
  • "google_vertexai"
  • "google_genai"
  • "fireworks"
  • "mistral"
  • "groq"
  • 或任何自定义字符串
何时使用: 当您希望为自定义模型封装器或自托管模型启用自动成本跟踪时。 示例:
关联关系:
  • 需要 ls_model_name 才能使成本跟踪工作。
  • 与 token 使用数据结合来计算成本。

ls_model_name

  • 类型: string
  • 必填: 是 (需配合 ls_provider)
功能: 标识具体模型。与 ls_provider 结合,通过与定价数据库匹配来进行自动成本计算。 常见值:
  • OpenAI: "gpt-5.5", "gpt-5.4-mini", "gpt-3.5-turbo"
  • Anthropic: "claude-sonnet-4-6", "claude-opus-4-8"
  • 自定义: 任何模型标识符
何时使用: 当您希望在 UI 中实现自动成本跟踪和模型识别时。 示例:
关联关系:
  • 需要 ls_provider 才能使成本跟踪工作。
  • 与 token 使用数据结合来计算成本。

ls_temperature

  • 类型: number (可空)
  • 必填: 否
功能: 记录使用的温度设置。仅用于跟踪 - 不影响 LangSmith 行为。 何时使用: 当您想为实验或调试跟踪模型配置时。 示例:
关联关系:
  • 独立参数;仅用于跟踪。
  • 与其他配置参数一起使用,便于实验比较。

ls_max_tokens

  • 类型: number (可空)
  • 必填: 否
功能: 记录使用的最大 token 数设置。仅用于跟踪 - 不影响 LangSmith 行为。 何时使用: 当您想为实验或调试跟踪模型配置时。 示例:
关联关系:
  • 独立参数;仅用于跟踪。
  • 与实际 token 使用结合时,可用于成本分析。

ls_stop

  • 类型: string[] (可空)
  • 必填: 否
功能: 记录使用的停止序列。仅用于跟踪 - 不影响 LangSmith 行为。 何时使用: 当您想为实验或调试跟踪模型配置时。 示例:
关联关系:
  • 独立参数;仅用于跟踪。

ls_invocation_params

  • 类型: object (任意键值对)
  • 必填: 否
功能: 存储不适合特定 ls_ 参数的额外模型参数。可以包含特定于提供商的设置。 常用参数: top_p, frequency_penalty, presence_penalty, top_k, seed 或任何自定义参数 何时使用: 当您需要跟踪超出标准参数范围的额外配置时。 示例:
关联关系:
  • 独立参数;存储任意配置。

ls_agent_type

  • 类型: "root" | "subagent" | "middleware"
  • 必填: 否
功能: 控制来自自定义智能体类运行的消息在消息视图中的显示方式。 最新版 LangSmith SDK 的追踪封装器集成在需要时会自动设置此元数据。对于自定义插桩,请在代表智能体或中间件步骤的运行上设置此键。 值:
  • "root": 此运行的消息出现在主消息视图中。
  • "subagent": 此运行的消息出现在侧边线程中,与主对话分开。
  • "middleware": 此运行的消息在消息视图中隐藏。
何时使用: 当您正在构建自定义智能体插桩,并希望消息视图能够区分根智能体、子智能体和中间件时。 更多详情,请参阅自定义消息视图。 关联关系:
  • 独立于模型识别和成本跟踪元数据。
  • 通过标识运行在智能体追踪中所扮演的角色,来补充追踪的父子结构。

ls_message_view_exclude

  • 类型: boolean (基于存在性)
  • 必填: 否
功能: 在消息视图中隐藏该运行。被排除的运行仍然会出现在常规追踪视图、运行浏览器和指标中。 该过滤器检查的是键是否存在,而不是其真值。{LS_MESSAGE_VIEW_EXCLUDE: False} 仍然会排除该运行。要包含该运行,需完全省略该键。 导入常量: 该键在 langsmith (Python 和 JS) 中以常量 LS_MESSAGE_VIEW_EXCLUDE 导出,其值是字符串 "ls_message_view_exclude"。推荐使用常量以避免拼写错误;字面量字符串仍然有效。 何时使用: 用于那些不是对话轮次的 LLM 子跨度,例如分类调用、嵌入查询、安全过滤器或路由/护栏决策。您可能仍希望它们在 LangSmith 的其他地方可见,但不希望它们使对话记录混乱。 示例:
更多 Python 和 JS 上下文(@traceable, trace, wrap_openai, RunnableConfig, wrapAISDK, RunTree.createChild)的代码示例,请参阅从消息视图中排除运行。 关联关系:
  • 独立于模型识别和成本跟踪元数据。
  • 与 ls_agent_type 互补,后者按角色路由消息,而不是完全隐藏运行。

ls_is_error_interrupt

  • 类型: boolean
  • 必填: 否
功能: 在包含错误的运行上设置为 true 时,会将运行状态标记为中断,而不是错误。 何时使用: 当您的插桩能够识别某个错误代表的是中断的运行(例如用户中断或人在回路中断),并且您希望 LangSmith 将其与其他错误分开渲染时。 示例:
关联关系:
  • 仅影响包含错误的运行。
  • 独立于模型识别和成本跟踪元数据。

ls_run_depth

  • 类型: integer
  • 由…设置: LangSmith 后端 (自动)
  • 不可覆盖
功能: 表示追踪树中的深度:
  • 0 = 根级运行 (顶层)
  • 1 = 直接子级
  • 2 = 孙级
  • 等等
何时使用: 在追踪摄取过程中自动计算。用于过滤(例如”仅显示根级运行”)和 UI 可视化。 查询示例:
关联关系:
  • 由追踪的父子结构决定。
  • 无法手动设置。

ls_method

  • 类型: string
  • 由…设置: SDK (自动)
功能: 指示创建追踪的 SDK 方法(对于 @traceable 装饰器,通常为 "traceable")。 何时使用: 由追踪 SDK 自动设置。用于调试和分析。 关联关系:
  • 由 SDK 根据追踪的创建方式设置。
  • 无法手动设置。

ls_example_*

  • 类型: 任何 (取决于示例元数据)
  • 模式: ls_example_{original_key}
  • 由…设置: LangSmith 实验系统 (自动)
功能: 在对数据集运行实验时,示例的元数据会自动加上 ls_example_ 前缀并添加到追踪中。 特殊参数:
  • ls_example_dataset_split: 数据集分割 (例如 “train”, “test”, “validation”)
何时使用: 在数据集实验期间。允许按示例特征进行过滤/分组。 示例: 如果示例有元数据 {"category": "technical", "difficulty": "hard"},追踪将获得:
关联关系:
  • 从示例元数据自动派生。
  • 无法在追踪上手动设置。

ls_experiment_id

  • 类型: string (UUID)
  • 由…设置: LangSmith 实验系统 (自动)
功能: 实验运行的唯一标识符。 何时使用: 在对数据集运行实验/评估时自动添加。用于将同一实验的所有运行分组。 关联关系:
  • 将运行链接到特定实验。
  • 无法手动设置。

参数关系

成本跟踪依赖项

为了让 LangSmith 自动计算成本,几个参数必须协同工作。以下是所需内容: 主要要求: ls_provider + ls_model_name 附加要求: 回退行为: 如果元数据中没有 ls_model_name,系统会在放弃成本跟踪之前检查 ls_invocation_params 中的模型标识符(如 "model")。

配置跟踪组

这些参数帮助您跟踪模型设置,但不影响 LangSmith 的核心功能: 可选,独立工作: ls_temperature, ls_max_tokens, ls_stop
  • 这些用于跟踪/显示。
  • 不影响 LangSmith 行为或成本计算。
  • 便于实验比较和调试。

中断渲染

当运行错误应被渲染为中断而非错误时,请将 ls_is_error_interrupt 设置为 true。此参数仅影响包含错误的运行。

调用参数特殊情况

ls_invocation_params 参数具有双重作用,既是跟踪字段,也是回退机制: ls_invocation_params; 部分独立,具有回退作用:
  • 主要存储任意配置以供跟踪。
  • 如果缺少 ls_model_name,可作为回退用于成本跟踪。
  • 当 ls_model_name 存在时,不直接影响成本计算。

系统参数

这些参数由 LangSmith 自动生成,无法手动设置: 无法由用户设置: ls_run_depth, ls_method, ls_example_*, ls_experiment_id
  • 由系统自动设置。
  • 用于过滤、分析和系统跟踪。

按元数据参数过滤追踪

一旦您向追踪添加了 ls_ 元数据参数,就可以通过 API 或在 LangSmith UI 中以编程方式或交互式地使用它们来过滤和搜索追踪。这使您能够按模型、提供商、配置设置或追踪深度缩小追踪范围。

使用 API

使用 Client 类配合 list_runs() 方法 (Python) 或 listRuns() 方法 (TypeScript) 来基于元数据值查询追踪。过滤语法支持相等性检查、比较和逻辑运算符。
这些示例展示了常见的过滤模式:
  • 按提供商或模型过滤,以分析特定模型的使用模式或成本
  • 按运行深度过滤,仅获取根级追踪(深度为 0)或特定嵌套级别的子运行
  • 按配置过滤,以比较具有不同温度、最大 token 数或其他设置的实验

使用 UI

在 LangSmith UI 中,使用过滤/搜索栏配合过滤语法:

相关内容