元数据参数参考

当你用 LangSmith 追踪 LLM 调用时，你常想跟踪成本、比较模型配置，并跨不同提供商分析性能。LangSmith 的原生集成（像 LangChain 或 OpenAI/Anthropic 包装器）会自动处理这些，但自定义模型包装器和自托管模型需要一个标准化的方式来提供这些信息。LangSmith 为此使用 ls_ 元数据参数。

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

用 ls_ 元数据参数来：

• 通过识别提供商和模型名，为自定义或自托管模型启用自动成本跟踪。
• 跟踪模型配置，如 temperature、max tokens 和其他参数，用于实验比较。
• 按提供商或配置设置过滤并分析追踪
• 为自定义 agent 插桩自定义 Trajectory 视图渲染。
• 标记被中断的错误，以便 LangSmith 把被中断的运行与其他错误分开渲染。
• 通过记录每次运行究竟用了哪些模型设置来改进调试。

基本用法示例

最常见的用例是为自定义模型包装器启用成本跟踪。要做到这一点，你需要提供两条关键信息：提供商名（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)

TypeScript

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"
    }
  }
);

Java

import com.langchain.smith.tracing.RunType;
import com.langchain.smith.tracing.TraceConfig;
import com.langchain.smith.tracing.Tracing;
import java.util.HashMap;
import java.util.Map;
import java.util.function.Function;

Map<String, Object> metadata = new HashMap<>();
metadata.put("ls_provider", "my_provider");
metadata.put("ls_model_name", "my_custom_model");

Function<String, String> myCustomLlm =
    Tracing.traceFunction(
        prompt -> callCustomApi(prompt),
        TraceConfig.builder()
            .runType(RunType.LLM)
            .metadata(metadata)
            .build());

Kotlin

import com.langchain.smith.tracing.RunType
import com.langchain.smith.tracing.TraceConfig
import com.langchain.smith.tracing.traceable

val myCustomLlm =
    traceable(
        { prompt: String -> callCustomApi(prompt) },
        TraceConfig.builder()
            .runType(RunType.LLM)
            .metadata(
                mapOf(
                    "ls_provider" to "my_provider",
                    "ls_model_name" to "my_custom_model",
                ),
            )
            .build(),
    )

这个最小设置告诉 LangSmith 你在用哪个模型，若该模型存在于定价数据库中、或你配置了自定义定价，就能实现自动成本计算。

要做更全面的跟踪，你能包含额外的配置参数。当运行实验或比较不同模型设置时，这尤其有用：

Python

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

TypeScript

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
      }
    }
  }
);

Java

import com.langchain.smith.tracing.RunType;
import com.langchain.smith.tracing.TraceConfig;
import com.langchain.smith.tracing.Tracing;
import java.util.Collections;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.function.Function;

Map<String, Object> metadata = new HashMap<>();
metadata.put("ls_provider", "openai");
metadata.put("ls_model_name", "gpt-5.5");
metadata.put("ls_temperature", 0.7);
metadata.put("ls_max_tokens", 4096);
metadata.put("ls_stop", Collections.singletonList("END"));

Map<String, Object> invocationParams = new HashMap<>();
invocationParams.put("top_p", 0.9);
invocationParams.put("frequency_penalty", 0.5);
metadata.put("ls_invocation_params", invocationParams);

Function<List<Map<String, String>>, String> myConfiguredLlm =
    Tracing.traceFunction(
        messages -> callLlm(messages),
        TraceConfig.builder()
            .runType(RunType.LLM)
            .metadata(metadata)
            .build());

Kotlin

val myConfiguredLlm =
    traceable(
        { messages: List<Map<String, String>> -> callLlm(messages) },
        TraceConfig.builder()
            .runType(RunType.LLM)
            .metadata(
                mapOf(
                    "ls_provider" to "openai",
                    "ls_model_name" to "gpt-5.5",
                    "ls_temperature" to 0.7,
                    "ls_max_tokens" to 4096,
                    "ls_stop" to listOf("END"),
                    "ls_invocation_params" to
                        mapOf(
                            "top_p" to 0.9,
                            "frequency_penalty" to 0.5,
                        ),
                ),
            )
            .build(),
    )

有了这个设置，你以后能按 temperature 过滤追踪、比较带不同 max token 设置的运行，或分析哪些配置参数产出最佳结果。除了成本跟踪所需的 ls_provider 和 ls_model_name 这一对外，所有这些参数都是可选的。

所有参数

用户可配置参数

参数	类型	必需	描述
ls_provider	string	是*	用于成本跟踪的 LLM 提供商名
ls_model_name	string	是*	用于成本跟踪的模型标识符
ls_temperature	number	否	所用的 temperature 参数
ls_max_tokens	number	否	所用的最大 token 参数
ls_stop	string[]	否	所用的停止序列
ls_invocation_params	object	否	额外的调用参数
ls_agent_type	string	否	控制 agent 运行在 Trajectory 视图中如何出现："root"、"subagent" 或 "middleware"
ls_message_view_exclude	boolean	否	把该运行从 Trajectory 视图中隐藏
ls_is_error_interrupt	boolean	否	当设为 true 时把一个 errored 运行标记为 interrupted

* 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.5"
    }
)
def my_llm_call(prompt: str):
    return call_api(prompt)

关系：

• 需要 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 中做模型识别时。

示例：

@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，成本跟踪才能工作。
• 与 token 用量数据协同计算成本。

ls_temperature

• 类型： number（可空）
• 必需： 否

它做什么： 记录所用的 temperature 设置。这仅为跟踪用——不影响 LangSmith 行为。

何时使用： 当你想为实验或调试跟踪模型配置时。

示例：

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

关系：

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

ls_max_tokens

• 类型： number（可空）
• 必需： 否

它做什么： 记录所用的最大 token 设置。这仅为跟踪用——不影响 LangSmith 行为。

何时使用： 当你想为实验或调试跟踪模型配置时。

示例：

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

关系：

• 独立；仅为跟踪用。
• 与实际 token 用量结合时，对成本分析很有用。

ls_stop

• 类型： string[]（可空）
• 必需： 否

它做什么： 记录所用的停止序列。这仅为跟踪用——不影响 LangSmith 行为。

何时使用： 当你想为实验或调试跟踪模型配置时。

示例：

metadata={
    "ls_provider": "openai",
    "ls_model_name": "gpt-5.5",
    "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.5",
    "ls_invocation_params": {
        "top_p": 0.9,
        "frequency_penalty": 0.5,
        "presence_penalty": 0.3,
        "seed": 12345
    }
}

关系：

• 独立；存储任意配置。

ls_agent_type

• 类型： "root" | "subagent" | "middleware"
• 必需： 否

它做什么： 控制来自自定义类 agent 运行的消息在 Trajectory 视图中如何出现。

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

值：

• "root"：来自该运行的消息出现在主 Trajectory 视图中。
• "subagent"：来自该运行的消息出现在一个侧线程中，与主会话分开。
• "middleware"：来自该运行的消息从 Trajectory 视图中隐藏。

何时使用： 当你在构建自定义 agent 插桩、并希望 Trajectory 视图区分根 agent、子 agent 和中间件时。

更多细节，见自定义 Trajectory 视图。

关系：

• 独立于模型识别和成本跟踪元数据。
• 通过识别一个运行在 agent 追踪中扮演的角色，补充追踪的父子结构。

ls_message_view_exclude

• 类型： boolean（基于存在）
• 必需： 否

它做什么： 把该运行从 Trajectory 视图中隐藏。被排除的运行仍出现在常规追踪视图、运行浏览器和指标中。

该过滤器检查键的存在，而非真值性。{LS_MESSAGE_VIEW_EXCLUDE: False} 仍会排除该运行。要包含该运行，请完全省略这个键。

导入常量： 这个键作为 LS_MESSAGE_VIEW_EXCLUDE 常量从 langsmith（Python 和 JS）导出，其值是字符串 "ls_message_view_exclude"。优先用该常量以避免拼写错误；字面字符串也仍有效。

何时使用： 对于不是会话回合的 LLM 子 span，例如分类调用、嵌入查找、安全过滤器，或路由/护栏决策——你仍想在 LangSmith 其他地方可见、但不希望它 clutter 会话记录的那些。

示例：

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）的额外代码示例，见把运行从 Trajectory 视图排除。

关系：

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

ls_is_error_interrupt

• 类型： boolean
• 必需： 否

它做什么： 当在一个带错误的运行上设为 true 时，把运行状态标记为 interrupted 而非 error。

何时使用： 当你的插桩能识别出一个错误代表的是一次被中断的运行（例如用户中断或人在回路中断）、并希望 LangSmith 把它与其他错误分开渲染时。

示例：

metadata={
    "ls_is_error_interrupt": True
}

关系：

• 只影响含错误的运行。
• 独立于模型识别和成本跟踪元数据。

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"（或启用了任意成本跟踪）。
• token 用量数据必须存在于追踪中（prompt_tokens、completion_tokens）。
• 模型必须存在于定价数据库中或有配置的自定义定价。

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

配置跟踪组

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

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

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

中断渲染

当一个运行错误应被渲染为 interrupted 而非 error 时，设 ls_is_error_interrupt 为 true。这个参数只影响含错误的运行。

invocation params 的特殊情形

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

# 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'
)

TypeScript

import { Client } from "langsmith";

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）或特定嵌套层级的子运行
• 按配置过滤以比较带不同 temperature、max token 或其他设置的实验

使用 UI

在 LangSmith UI 中，用配过滤器语法的过滤/搜索栏：

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

相关

• 成本跟踪指南：学习如何在 LangSmith 中跟踪并分析 LLM 成本。
• 记录 LLM 追踪：以正确的 token 跟踪记录 LLM 调用的格式要求。
• 追踪查询语法：过滤和搜索追踪的完整参考。
• 评估快速开始：在数据集上运行实验以比较模型配置。
• 添加元数据和标签：向追踪添加元数据的通用指南。
• 过滤追踪（ClickHouse）：在你的代码中以编程方式过滤追踪。

---