元数据参数参考

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

这些元数据参数（均以 ls_ 为前缀）允许您通过标准的 metadata 字段传递模型配置和标识信息。一旦设置，LangSmith 就可以自动计算成本、在 UI 中显示模型信息，并支持跨追踪进行过滤和分析。

使用 ls_ 元数据参数可以：

• 启用自动成本跟踪：通过标识供应商和模型名称，为自定义或自托管模型启用自动成本跟踪。
• 跟踪模型配置：如温度、最大令牌数和其他参数，以便进行实验比较。
• 按供应商或配置设置过滤和分析追踪
• 改进调试：通过准确记录每次运行使用的模型设置。

基本用法示例

最常见的用例是为自定义模型包装器启用成本跟踪。为此，您需要提供两个关键信息：供应商名称 (ls_provider) 和模型名称 (ls_model_name)。它们共同作用，与 LangSmith 的定价数据库进行匹配。

Python

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)

import { traceable } from "langsmith/traceable";

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

这个最小设置告诉 LangSmith 您正在使用的模型，如果模型存在于定价数据库中或您已配置自定义定价，则启用自动成本计算。

为了进行更全面的跟踪，您可以包含其他配置参数。这在运行实验或比较不同模型设置时特别有用：

Python

@traceable(
    run_type="llm",
    metadata={
        "ls_provider": "openai",
        "ls_model_name": "gpt-4.1",
        "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-4.1",
      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_provider	string	是*	用于成本跟踪的 LLM 供应商名称
ls_model_name	string	是*	用于成本跟踪的模型标识符
ls_temperature	number	否	使用的温度参数
ls_max_tokens	number	否	使用的最大令牌参数
ls_stop	string[]	否	使用的停止序列
ls_invocation_params	object	否	额外的调用参数

* 成本跟踪必须同时提供 ls_provider 和 ls_model_name

系统生成参数

参数	类型	描述
ls_run_depth	integer	在追踪树中的深度（0=根，1=子节点等）- 自动计算
ls_method	string	使用的追踪方法（例如，“traceable”）- 由 SDK 设置

实验参数

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

参数详情

ls_provider

• 类型： string
• 必需： 是（与 ls_model_name 一起）

作用： 标识 LLM 供应商。与 ls_model_name 结合，通过匹配 LangSmith 的模型定价数据库 来启用自动成本计算。

常见值：

• "openai"
• "anthropic"
• "azure"
• "bedrock"
• "google_vertexai"
• "google_genai"
• "fireworks"
• "mistral"
• "groq"
• 或任何自定义字符串

何时使用： 当您希望为自定义模型包装器或自托管模型启用自动成本跟踪时。

示例：

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

关联关系：

• 需要 ls_model_name 才能使成本跟踪生效。
• 与令牌使用数据一起工作以计算成本。

ls_model_name

• 类型： string
• 必需： 是（与 ls_provider 一起）

作用： 标识特定模型。与 ls_provider 结合，匹配定价数据库以进行自动成本计算。

常见值：

• OpenAI: "gpt-4.1", "gpt-4.1-mini", "gpt-3.5-turbo"
• Anthropic: "claude-3-5-sonnet-20241022", "claude-3-opus-20240229"
• 自定义：任何模型标识符

何时使用： 当您希望在 UI 中启用自动成本跟踪和模型标识时。

示例：

@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)

关联关系：

• 需要 ls_provider 才能使成本跟踪生效。
• 与令牌使用数据一起工作以计算成本。

ls_temperature

• 类型： number (可为空)
• 必需： 否

作用： 记录使用的温度设置。这仅用于跟踪，不影响 LangSmith 行为。

何时使用： 当您希望为实验或调试跟踪模型配置时。

示例：

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

关联关系：

• 独立；仅用于跟踪。
• 与其他配置参数一起用于实验比较很有用。

ls_max_tokens

• 类型： number (可为空)
• 必需： 否

作用： 记录使用的最大令牌设置。这仅用于跟踪，不影响 LangSmith 行为。

何时使用： 当您希望为实验或调试跟踪模型配置时。

示例：

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

关联关系：

• 独立；仅用于跟踪。
• 与实际令牌使用情况结合用于成本分析时很有用。

ls_stop

• 类型： string[] (可为空)
• 必需： 否

作用： 记录使用的停止序列。这仅用于跟踪，不影响 LangSmith 行为。

何时使用： 当您希望为实验或调试跟踪模型配置时。

示例：

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

关联关系：

• 独立；仅用于跟踪。

ls_invocation_params

• 类型： object (任意键值对)
• 必需： 否

作用： 存储不适合特定 ls_ 参数的额外模型参数。可以包含供应商特定的设置。

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

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

示例：

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

关联关系：

• 独立；存储任意配置。

ls_run_depth

• 类型： integer
• 设置者： LangSmith 后端（自动）
• 无法覆盖

作用： 指示在追踪树中的深度：

• 0 = 根运行（顶级）
• 1 = 直接子节点
• 2 = 孙节点
• 等等。

何时使用： 在追踪摄取期间自动计算。用于过滤（例如，“仅显示根运行”）和 UI 可视化。

示例查询：

metadata_key = 'ls_run_depth' AND metadata_value = 0

关联关系：

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

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"}，追踪会得到：

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

关联关系：

• 自动从示例元数据派生。
• 无法在追踪上手动设置。

ls_experiment_id

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

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

何时使用： 在数据集上运行实验/评估时自动添加。用于将同一实验的所有运行分组。

关联关系：

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

参数关联关系

成本跟踪依赖项

为了使 LangSmith 自动计算成本，几个参数必须协同工作。以下是所需内容：

主要要求： ls_provider + ls_model_name

• 两者都应存在以进行自动成本计算。
• 如果缺少 ls_model_name，系统将回退到检查 ls_invocation_params 中的模型名称。
• ls_provider 必须匹配定价数据库中的供应商（或使用自定义定价）。

额外要求：

• 运行必须具有 run_type="llm"（或必须启用任意成本跟踪）。
• 追踪中必须存在令牌使用数据（prompt_tokens, completion_tokens）。
• 模型必须存在于定价数据库中或已配置自定义定价。

回退行为： 如果元数据中没有 ls_model_name，系统会在放弃成本跟踪之前检查 ls_invocation_params 中是否有像 "model" 这样的模型标识符。

配置跟踪组

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

可选，独立工作： ls_temperature, ls_max_tokens, ls_stop

• 这些用于跟踪/显示。
• 不影响 LangSmith 行为或成本计算。
• 对实验比较和调试很有用。

调用参数特殊情况

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

Python

from langsmith import Client

client = Client()

# 按供应商过滤运行
runs = client.list_runs(
    project_name="my-app",
    filter='metadata_key = "ls_provider" AND metadata_value = "openai"'
)

# 按特定模型过滤
runs = client.list_runs(
    project_name="my-app",
    filter='metadata_key = "ls_model_name" AND metadata_value = "gpt-4.1"'
)

# 仅过滤根运行（顶级追踪）
runs = client.list_runs(
    project_name="my-app",
    filter='metadata_key = "ls_run_depth" AND metadata_value = 0'
)

# 按温度阈值过滤
runs = client.list_runs(
    project_name="my-app",
    filter='metadata_key = "ls_temperature" AND metadata_value > 0.5'
)

import { Client } from "langsmith";

const client = new Client();

// 按供应商过滤运行
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);
}

// 按特定模型过滤
const runsByModel: any[] = [];
for await (const run of client.listRuns({
  projectName: "my-app",
  filter: 'metadata_key = "ls_model_name" AND metadata_value = "gpt-4.1"'
})) {
  runsByModel.push(run);
}

// 仅过滤根运行（顶级追踪）
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);
}

// 按温度阈值过滤
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 中，使用带有过滤语法的过滤/搜索栏：

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

相关资源

• 成本跟踪指南：了解如何在 LangSmith 中跟踪和分析 LLM 成本。
• 记录 LLM 追踪：记录具有适当令牌跟踪的 LLM 调用的格式要求。
• 追踪查询语法：过滤和搜索追踪的完整参考。
• 评估快速入门：在数据集上运行实验以比较模型配置。
• 添加元数据和标签：向追踪添加元数据的通用指南。
• 在应用程序中过滤追踪：在代码中以编程方式过滤追踪。

---

Edit this page on GitHub or file an issue.

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.