元数据参数参考

当您使用 LangSmith 追踪 LLM 调用时，通常希望追踪成本、比较模型配置，并分析不同提供商的性能。LangSmith 的原生集成（如 LangChain 或 OpenAI/Anthropic 包装器）会自动处理这些，但自定义模型包装器和自托管模型需要一种标准化的方式来提供这些信息。LangSmith 使用 ls_ 元数据参数来实现此目的。这些元数据参数（均以 ls_ 为前缀）允许您通过标准的 metadata 字段传递模型配置和标识信息。设置后，LangSmith 可以自动计算成本、在 UI 中显示模型信息，并启用跨追踪的过滤和分析。使用 ls_ 元数据参数来：

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

基本用法示例

最常见的用例是为自定义模型包装器启用成本追踪。为此，您需要提供两个关键信息：提供商名称 (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)

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 您正在使用哪个模型，如果该模型存在于定价数据库中，或者您已配置了自定义定价，则可以启用自动成本计算。为了进行更全面的追踪，您可以包含额外的配置参数。这在运行实验或比较不同模型设置时特别有用：

@traceable(
    run_type="llm",
    metadata={
        "ls_provider": "openai",
        "ls_model_name": "gpt-5.4",
        "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.4",
      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-5.4"
    }
)
def my_llm_call(prompt: str):
    return call_api(prompt)

关联关系：

需要 ls_model_name 才能使成本追踪正常工作。
与令牌使用数据结合以计算成本。

`ls_model_name`

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

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

OpenAI: "gpt-5.4", "gpt-5.4-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-5.4",
    "ls_temperature": 0.7
}

关联关系：

独立；仅用于追踪。
与其他配置参数结合用于实验比较时很有用。

`ls_max_tokens`

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

功能： 记录使用的最大令牌设置。这仅用于追踪——不影响 LangSmith 行为。 使用场景： 当您希望为实验或调试追踪模型配置时。 示例：

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

关联关系：

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

`ls_stop`

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

功能： 记录使用的停止序列。这仅用于追踪——不影响 LangSmith 行为。 使用场景： 当您希望为实验或调试追踪模型配置时。 示例：

metadata={
    "ls_provider": "openai",
    "ls_model_name": "gpt-5.4",
    "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-5.4",
    "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）来基于元数据值查询追踪。过滤语法支持相等检查、比较和逻辑运算符。

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-5.4"'
)

# 仅过滤根运行（顶层追踪）
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-5.4"'
})) {
  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-5.4'
metadata_key = 'ls_run_depth' AND metadata_value = 0

Tracing setup

Configuration & troubleshooting

Viewing & managing traces

Automations

Feedback & evaluation

Monitoring & alerting

Data type reference

基本用法示例

所有参数

用户可配置参数

系统生成参数

实验参数

参数详情

`ls_provider`

`ls_model_name`

`ls_temperature`

`ls_max_tokens`

`ls_stop`

`ls_invocation_params`

`ls_run_depth`

`ls_method`

`ls_example_*`

`ls_experiment_id`

参数关系

成本追踪依赖关系

配置追踪组

调用参数特殊情况

系统参数

按元数据参数过滤追踪

使用 API

使用 UI

相关内容

​基本用法示例

​所有参数

​用户可配置参数

​系统生成参数

​实验参数

​参数详情

​ls_provider

​ls_model_name

​ls_temperature

​ls_max_tokens

​ls_stop

​ls_invocation_params

​ls_run_depth

​ls_method

​ls_example_*

​ls_experiment_id

​参数关系

​成本追踪依赖关系

​配置追踪组

​调用参数特殊情况

​系统参数

​按元数据参数过滤追踪

​使用 API

​使用 UI

​相关内容

基本用法示例

所有参数

用户可配置参数

系统生成参数

实验参数

参数详情

`ls_provider`

`ls_model_name`

`ls_temperature`

`ls_max_tokens`

`ls_stop`

`ls_invocation_params`

`ls_run_depth`

`ls_method`

`ls_example_*`

`ls_experiment_id`

参数关系

成本追踪依赖关系

配置追踪组

调用参数特殊情况

系统参数

按元数据参数过滤追踪

使用 API

使用 UI

相关内容