以编程方式使用文档

使用 LangSmith 追踪 LLM 调用时，您通常希望 追踪成本、比较模型配置以及分析不同提供商的性能。LangSmith 的原生集成（如 LangChain 或 OpenAI/Anthropic 包装器）自动处理此操作，但自定义模型包装器和自托管模型需要一种标准化方式来提供此信息。LangSmith 使用 ls_ 元数据参数来实现此目的。

这些元数据参数（全部以 ls_为前缀）让您可以通过标准 metadata 字段传递模型配置和标识信息。设置后，LangSmith 可以自动计算成本、在 UI 中显示模型信息，并启用 过滤 和跨追踪的分析功能。

使用 ls_ 元数据参数来：

  • 为自定义或自托管模型启用自动成本追踪 ，通过标识提供商和模型名称。
  • 追踪模型配置 如温度、最大令牌数和其他参数，以便进行实验比较。
  • 按提供商或配置设置 过滤和分析追踪
  • 为自定义代理检测自定义化消息视图渲染 。
  • 标记中断错误 以便 LangSmith 可以将中断的运行与其他错误分开渲染。
  • 改进调试 ，方法是通过精确记录每次运行使用的模型设置。

基本用法示例

最常见的用例是为自定义模型包装器启用成本追踪。为此，您需要提供两个关键信息：提供商名称（ls_provider）和模型名称（ls_model_name）。这两个参数共同作用以匹配 LangSmith 的定价数据库。

from langsmith import traceable

@traceable(
    run_type="llm",
    metadata={
        "ls_provider": "my_provider",
        "ls_model_name": "my_custom_model"
    }
)
def my_custom_llm(prompt: str):
    return call_custom_api(prompt)
const myCustomLlm = traceable(
  async (prompt: string) => {
    return callCustomApi(prompt);
  },
  {
    run_type: "llm",
    metadata: {
      ls_provider: "my_provider",
      ls_model_name: "my_custom_model"
    }
  }
);

这种最小化设置告诉 LangSmith 您正在使用的模型，如果模型存在于定价数据库中或者您已 配置了自定义定价.

，则可以启用自动成本计算。为了更全面地追踪，您可以使用其他可选的元数据参数。这些参数特别适用于 运行实验 或比较不同模型设置：

@traceable(
    run_type="llm",
    metadata={
        "ls_provider": "openai",
        "ls_model_name": "gpt-5.5",
        "ls_temperature": 0.7,
        "ls_max_tokens": 4096,
        "ls_stop": ["END"],
        "ls_invocation_params": {
            "top_p": 0.9,
            "frequency_penalty": 0.5
        }
    }
)
def my_configured_llm(messages: list):
    return call_llm(messages)
const myConfiguredLlm = traceable(
  async (messages: Array<any>) => {
    return callLlm(messages);
  },
  {
    run_type: "llm",
    metadata: {
      ls_provider: "openai",
      ls_model_name: "gpt-5.5",
      ls_temperature: 0.7,
      ls_max_tokens: 4096,
      ls_stop: ["END"],
      ls_invocation_params: {
        top_p: 0.9,
        frequency_penalty: 0.5
      }
    }
  }
);

使用此设置，您可以稍后按温度过滤追踪、比较具有不同最大令牌设置的运行，或分析哪些配置参数产生最佳结果。除成本追踪所需的 ls_provider 和 ls_model_name 配对外，所有这些参数都是可选的。

所有参数

用户可配置参数

参数类型必填描述
ls_providerstring是*用于成本追踪的 LLM 提供商名称
ls_model_namestring是*用于成本追踪的模型标识符
ls_temperaturenumber否使用的温度参数
ls_max_tokensnumber否使用的最大令牌数参数
ls_stopstring[]否使用的停止序列
ls_invocation_paramsobject否额外的调用参数
ls_agent_typestring否控制智能体运行在消息视图中的显示方式： "root", "subagent", or "middleware"
ls_message_view_excludeboolean否在消息视图中隐藏该运行
ls_is_error_interruptboolean否设置为时将错误运行标记为中断 true

\* ls_provider 和 ls_model_name 必须一起提供才能进行成本追踪

系统生成的参数

参数类型描述
ls_run_depthinteger追踪树中的深度 (0=根，1=子级等) - 自动计算
ls_methodstring使用的追踪方法（例如 "traceable"）- 由 SDK 设置

实验参数

参数类型描述
ls_example_*any以 ls_example_ 为前缀的示例元数据 - 在实验期间添加
ls_experiment_idstring （UUID）唯一的实验标识符 - 在实验期间添加

参数详情

ls_provider

功能说明： 识别 LLM 提供商。结合 ls_model_name使用，可通过匹配 LangSmith 的模型定价数据库自动计算成本.

常见值： - "openai" - "anthropic" - "azure" - "bedrock" - "google_vertexai" - "google_genai" - "fireworks" - "mistral" - "groq" - 或任何自定义字符串

使用场景： 当你需要 自动成本追踪 用于自定义模型包装器或自托管模型时。

Example:

@traceable(
    run_type="llm",
    metadata={
        "ls_provider": "openai",
        "ls_model_name": "gpt-5.5"
    }
)
def my_llm_call(prompt: str):
    return call_api(prompt)

Relationships: - **需要** ls_model_name 才能使成本追踪生效。 - 与令牌使用数据配合计算成本。

ls_model_name

  • Type: string
  • Required: 是（配合 ls_provider)

功能说明： 识别具体模型。结合 ls_provider使用，可通过匹配定价数据库自动计算成本。

常见值： - OpenAI: "gpt-5.5", "gpt-5.4-mini", "gpt-3.5-turbo" - Anthropic: "claude-3-5-sonnet-20241022", "claude-3-opus-20240229" - 自定义：任意模型标识符

使用场景： 当你需要自动 成本追踪 和模型识别 UI.

Example:

@traceable(
    run_type="llm",
    metadata={
        "ls_provider": "anthropic",
        "ls_model_name": "claude-3-5-sonnet-20241022"
    }
)
def my_claude_call(messages: list):
    return call_claude(messages)

Relationships: - **需要** ls_provider 才能使成本追踪生效。 - 与令牌使用数据配合计算成本。

ls_temperature

  • Type: number （可为空）
  • Required: No

功能说明： 记录使用的温度设置。这仅用于追踪目的，不会影响 LangSmith 的行为。

使用场景： 当您想跟踪模型配置以进行实验或调试时。

Example:

metadata={
    "ls_provider": "openai",
    "ls_model_name": "gpt-5.5",
    "ls_temperature": 0.7
}

Relationships: - 独立的；仅用于跟踪。 - 与其他配置参数结合使用，便于实验比较。

ls_max_tokens

  • Type: number （可为空）
  • Required: No

功能说明： 记录所使用的最大令牌数设置。此功能仅用于跟踪，不影响 LangSmith 的行为。

使用场景： 当您想跟踪模型配置以进行实验或调试时。

Example:

metadata={
    "ls_provider": "openai",
    "ls_model_name": "gpt-5.5",
    "ls_max_tokens": 4096
}

Relationships: - 独立的；仅用于跟踪。 - 与实际令牌使用量结合时可用于成本分析。

ls_stop

  • Type: string[] （可为空）
  • Required: No

功能说明： 记录所使用的停止序列。此功能仅用于跟踪，不影响 LangSmith 的行为。

使用场景： 当您想跟踪模型配置以进行实验或调试时。

Example:

metadata={
    "ls_provider": "openai",
    "ls_model_name": "gpt-5.5",
    "ls_stop": ["END", "STOP", "\n\n"]
}

Relationships: - 独立的；仅用于跟踪。

ls_invocation_params

  • Type: object （任意键值对）
  • Required: No

功能说明： 存储不适合特定类别的其他模型参数 ls_ 的参数。可以包含特定于提供商的设置。

常见参数： top_p, frequency_penalty, presence_penalty, top_k, seed，或任何自定义参数

使用场景： 当您需要跟踪标准参数之外的额外配置时。

Example:

metadata={
    "ls_provider": "openai",
    "ls_model_name": "gpt-5.5",
    "ls_invocation_params": {
        "top_p": 0.9,
        "frequency_penalty": 0.5,
        "presence_penalty": 0.3,
        "seed": 12345
    }
}

Relationships: - 独立的；存储任意配置。

ls_agent_type

  • Type: "root" | "subagent" | "middleware"
  • Required: No

功能说明： 控制自定义代理类运行中的消息如何显示在 消息视图.

LangSmith SDK 最新版本的追踪包装器集成会在需要时自动设置此元数据。对于自定义插桩，请在代表代理或中间件步骤的运行上设置此键。

Values: - "root"：此运行中的消息会出现在主消息视图中。 - "subagent"：此运行中的消息会出现在侧线程中，与主对话分离。 - "middleware"：此运行中的消息会从消息视图中隐藏。

使用场景： 当您构建自定义代理插桩并希望消息视图能够区分根代理、子代理和中间件时。

更多详情，请参阅 自定义消息视图.

Relationships: - 独立于模型识别和成本跟踪元数据。 - 通过识别运行在代理追踪中的角色来补充追踪的父子结构。

ls_message_view_exclude

  • Type: boolean （基于存在性）
  • Required: No

功能说明： 从 消息视图中隐藏此运行。被排除的运行仍会出现在常规追踪视图、运行浏览器和指标中。

过滤器检查的是该键的 **存在性**，而不是真假值。 {LS_MESSAGE_VIEW_EXCLUDE: False} 仍然会排除该运行。完全省略该键以包含该运行。

导入常量： 该键作为 LS_MESSAGE_VIEW_EXCLUDE 从导出 langsmith (Python 和 JS) 导出，其值为字符串 "ls_message_view_exclude"。建议使用常量以避免拼写错误；字符串字面量仍然有效。

使用场景： For LLM subspans that are not conversational turns, such as classification calls, embedding lookups, safety filters, or routing/guardrail decisions, that you still want visible elsewhere in LangSmith but do not want cluttering the conversation transcript.

Example:

from langsmith import LS_MESSAGE_VIEW_EXCLUDE, traceable

@traceable(run_type="llm", metadata={LS_MESSAGE_VIEW_EXCLUDE: True})
def classify_intent(query: str) -> str:
    return llm.predict(f"Classify: {query}")

有关 Python 和 JS 上下文的更多代码示例（@traceable, trace, wrap_openai, RunnableConfig, wrapAISDK, RunTree.createChild），请参阅 从消息视图中排除运行.

Relationships: - 独立于模型识别和成本跟踪元数据。 - 补充 ls_agent_type，后者按角色路由消息而非完全隐藏运行。

ls_is_error_interrupt

  • Type: boolean
  • Required: No

功能说明： 当设置为 true 对于包含错误的运行，将运行状态标记为已中断而非错误。

使用场景： 当您的检测代码能够识别某个错误代表被中断的运行（如用户中断或人在环中断），且您希望 LangSmith 将其与其他错误分开显示时。

Example:

metadata={
    "ls_is_error_interrupt": True
}

Relationships: - 仅影响包含错误的运行。 - 独立于模型识别和成本跟踪元数据。

ls_run_depth

  • Type: integer
  • 设置方： LangSmith 后端（自动）
  • 无法覆盖

功能说明： 指示在追踪树中的深度： - 0 = 根运行（顶级） - 1 = 直接子级 - 2 = 孙子 - etc.

使用场景： 自动在追踪数据摄取期间计算。用于筛选（例如“仅显示根运行”）和 UI 可视化。

示例查询：

metadata_key = 'ls_run_depth' AND metadata_value = 0

Relationships: - 由追踪父子结构决定。 - 无法手动设置。

ls_method

  • Type: string
  • 设置者： SDK（自动）

功能说明： 指示创建跟踪的 SDK 方法（通常用于 "traceable" 用于 @traceable 装饰器）。

使用场景： 由追踪 SDK 自动设置。用于调试和分析。

Relationships: - 由 SDK 根据追踪的创建方式设置。 - 无法手动设置。

ls_example_*

  • Type: 任意（取决于示例元数据）
  • Pattern: ls_example_{original_key}
  • 设置者： LangSmith 实验系统（自动）

作用： 运行 数据集实验时，示例中的元数据会自动添加前缀 ls_example_ 并添加到追踪中。

特殊参数： - ls_example_dataset_split：数据集划分（例如 "train"、"test"、"validation"）

使用时机： During dataset experiments. Allows filtering/grouping by example characteristics.

Example: 如果示例包含元数据 {"category": "technical", "difficulty": "hard"}，trace 获取：

{
  "metadata": {
    "ls_example_category": "technical",
    "ls_example_difficulty": "hard",
    "ls_example_dataset_split": "test"
  }
}

Relationships: - 自动从示例元数据派生。 - 无法在 trace 上手动设置。

ls_experiment_id

  • Type: string (UUID)
  • 设置者： LangSmith 实验系统（自动）

作用： 实验运行的唯一标识符。

使用时机： 运行实验时自动添加 experiments/evaluations on datasets。用于将同一实验的所有运行分组。

Relationships: - 将运行链接到特定实验。 - 无法手动设置。

参数关系

成本跟踪依赖项

要让 LangSmith 自动计算成本，必须多个参数协同工作。以下是所需条件：

主要要求： ls_provider + ls_model_name - 两者都必须存在才能进行自动成本计算。 - If ls_model_name 缺失时，系统将回退到检查 ls_invocation_params 中的模型名称。 - ls_provider 必须与 定价数据库 中的提供商匹配

附加要求： - 运行必须具有 run_type="llm" (or 任意成本跟踪 必须启用）。 - 令牌使用数据 必须存在于 trace 中（提示_令牌、完成_令牌）。 - 模型必须存在于定价数据库或具有 已配置自定义定价.

回退行为： If ls_model_name 不在元数据中，系统会检查 ls_invocation_params 中的模型标识符，例如 "model" ，然后放弃成本跟踪。

配置跟踪组

这些参数帮助您跟踪模型设置，但不影响 LangSmith 的核心功能：

可选，独立工作： ls_temperature, ls_max_tokens, ls_stop - These are for tracking/display. - 不影响 LangSmith 行为或成本计算。 - 可用于实验比较和调试。

中断渲染

设置 ls_is_error_interrupt to 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）根据元数据值查询追踪。 过滤语法 支持等值检查、比较和逻辑运算符。

from langsmith import Client

client = Client()

# Filter runs by provider
runs = client.list_runs(
    project_name="my-app",
    filter='metadata_key = "ls_provider" AND metadata_value = "openai"'
)

# Filter by specific model
runs = client.list_runs(
    project_name="my-app",
    filter='metadata_key = "ls_model_name" AND metadata_value = "gpt-5.5"'
)

# Filter root runs only (top-level traces)
runs = client.list_runs(
    project_name="my-app",
    filter='metadata_key = "ls_run_depth" AND metadata_value = 0'
)

# Filter by temperature threshold
runs = client.list_runs(
    project_name="my-app",
    filter='metadata_key = "ls_temperature" AND metadata_value > 0.5'
)
const client = new Client();

// Filter runs by provider
const runsByProvider: any[] = [];
for await (const run of client.listRuns({
  projectName: "my-app",
  filter: 'metadata_key = "ls_provider" AND metadata_value = "openai"'
})) {
  runsByProvider.push(run);
}

// Filter by specific model
const runsByModel: any[] = [];
for await (const run of client.listRuns({
  projectName: "my-app",
  filter: 'metadata_key = "ls_model_name" AND metadata_value = "gpt-5.5"'
})) {
  runsByModel.push(run);
}

// Filter root runs only (top-level traces)
const rootRuns: any[] = [];
for await (const run of client.listRuns({
  projectName: "my-app",
  filter: 'metadata_key = "ls_run_depth" AND metadata_value = 0'
})) {
  rootRuns.push(run);
}

// Filter by temperature threshold
const highTempRuns: any[] = [];
for await (const run of client.listRuns({
  projectName: "my-app",
  filter: 'metadata_key = "ls_temperature" AND metadata_value > 0.5'
})) {
  highTempRuns.push(run);
}

这些示例展示了常见的过滤模式： - **按提供商或模型过滤** 分析特定模型的使用模式或成本 - **按运行深度过滤** 仅获取根追踪（深度 0）或特定嵌套级别的子运行 - **按配置过滤** 比较不同温度、最大令牌数或其他设置下的实验

使用 UI

在 LangSmith UI, use the filter/search bar with the 过滤语法:

metadata_key = 'ls_provider' AND metadata_value = 'openai'
metadata_key = 'ls_model_name' AND metadata_value = 'gpt-5.5'
metadata_key = 'ls_run_depth' AND metadata_value = 0

相关