ls_ 元数据参数来实现这一目的。
这些元数据参数(均以 ls_ 为前缀)允许您通过标准的 metadata 字段传递模型配置和标识信息。一旦设置,LangSmith 就可以自动计算成本、在用户界面中显示模型信息,并支持对您的追踪进行过滤和分析。
使用 ls_ 元数据参数可以:
- 启用自动成本跟踪:通过标识提供商和模型名称,为自定义或自托管模型自动计算成本。
- 跟踪模型配置:如温度、最大 token 数等参数,便于实验比较。
- 过滤和分析追踪:按提供商或配置设置进行筛选。
- 自定义消息视图渲染:用于自定义的智能体插桩。
- 标记中断错误:使 LangSmith 能将中断的运行与其他错误分开渲染。
- 改进调试:准确记录每次运行所使用的模型设置。
基本用法示例
最常见的用例是为自定义模型封装器启用成本跟踪。为此,您需要提供两条关键信息:提供商名称 (ls_provider) 和模型名称 (ls_model_name)。它们共同工作,与 LangSmith 的定价数据库进行匹配。
ls_provider 和 ls_model_name 配对外,所有这些参数都是可选的。
所有参数
用户可配置参数
*
ls_provider 和 ls_model_name 必须同时提供才能进行成本跟踪
系统生成参数
实验参数
参数详情
ls_provider
- 类型:
string - 必填: 是 (需配合
ls_model_name)
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" - 自定义: 任何模型标识符
- 需要
ls_provider才能使成本跟踪工作。 - 与 token 使用数据结合来计算成本。
ls_temperature
- 类型:
number(可空) - 必填: 否
- 独立参数;仅用于跟踪。
- 与其他配置参数一起使用,便于实验比较。
ls_max_tokens
- 类型:
number(可空) - 必填: 否
- 独立参数;仅用于跟踪。
- 与实际 token 使用结合时,可用于成本分析。
ls_stop
- 类型:
string[](可空) - 必填: 否
- 独立参数;仅用于跟踪。
ls_invocation_params
- 类型:
object(任意键值对) - 必填: 否
ls_ 参数的额外模型参数。可以包含特定于提供商的设置。
常用参数:
top_p, frequency_penalty, presence_penalty, top_k, seed 或任何自定义参数
何时使用:
当您需要跟踪超出标准参数范围的额外配置时。
示例:
- 独立参数;存储任意配置。
ls_agent_type
- 类型:
"root" | "subagent" | "middleware" - 必填: 否
"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 的其他地方可见,但不希望它们使对话记录混乱。
示例:
@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= 孙级- 等等
- 由追踪的父子结构决定。
- 无法手动设置。
ls_method
- 类型:
string - 由…设置: 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中的模型名称。 ls_provider必须与定价数据库中的提供商匹配(或使用自定义定价)。
- 运行必须具有
run_type="llm"(或必须启用任意成本跟踪)。 - Token 使用数据必须存在于追踪中(prompt_tokens, completion_tokens)。
- 模型必须存在于定价数据库中,或已配置自定义定价。
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 中,使用过滤/搜索栏配合过滤语法:相关内容
- 成本跟踪指南: 了解如何在 LangSmith 中跟踪和分析 LLM 成本。
- 记录 LLM 追踪: 记录 LLM 调用并正确进行 token 跟踪的格式要求。
- 追踪查询语法: 过滤和搜索追踪的完整参考。
- 评估快速入门: 在数据集上运行实验以比较模型配置。
- 添加元数据和标签: 向追踪添加元数据的通用指南。
- 在应用程序中过滤追踪: 在代码中以编程方式过滤追踪。
Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

