当您在 LangChain 或 LangSmith 支持的集成 之外直接调用 LLM 时,您需要提供特定的元数据,以便 LangSmith 能够显示令牌计数、计算成本,并允许您在 Playground 中使用正确的提供商和模型打开 运行。 要实现功能完整的 LLM 跟踪,需要满足四个要求:
如果您使用的是 LangChain OSS、OpenAI 封装器 或 Anthropic 封装器,这些细节会自动处理。本页示例使用 traceable 装饰器/封装器(Python 和 JS/TS 推荐方法)。如果您直接使用 RunTree 或 API,同样需要满足这些要求。

消息格式

当跟踪自定义模型或自定义输入/输出格式时,它必须遵循 LangChain 格式、OpenAI 补全格式或 Anthropic 消息格式。更多详情,请参阅 OpenAI Chat Completions 或 Anthropic Messages 文档。LangChain 格式如下:

将自定义 I/O 格式转换为 LangSmith 兼容格式

如果您使用的是自定义输入或输出格式,可以使用 @traceable 装饰器(Python)或 traceable 函数(TS)中的 process_inputs/processInputs 和 process_outputs/processOutputs 函数将其转换为 LangSmith 兼容格式。 process_inputs/processInputs 和 process_outputs/processOutputs 接受的函数允许您在特定跟踪的日志记录到 LangSmith 之前转换其输入和输出。它们可以访问跟踪的输入和输出,并可以返回一个包含处理后数据的新字典。 下面是一个样板示例,展示如何使用 process_inputs 和 process_outputs 将自定义 I/O 格式转换为 LangSmith 兼容格式:

在跟踪中标识自定义模型

使用自定义模型时,建议同时提供以下 metadata 字段,以便在查看跟踪和筛选时标识模型。
  • ls_provider:模型的提供商,例如 "openai"、"anthropic"。
  • ls_model_name:模型的名称,例如 "gpt-5.4-mini"、"claude-opus-4-8"。
如果您实现了自定义的流式 chat_model,您可以将输出“归约”为与非流式版本相同的格式。此功能仅在 Python 中支持:
在您的 metadata 中设置 ls_model_name 是 LangSmith 识别模型和计算自定义 LLM 跟踪成本所必需的。如果没有它,令牌计数可能仍会被记录,但成本不会被估算。
要了解更多关于如何使用 metadata 字段的信息,请参阅添加元数据和标签指南。要自定义自定义代理运行在消息视图中的显示方式,请参阅自定义消息视图。

提供令牌和成本信息

令牌计数支持成本计算,LangSmith 会在跟踪项目 UI 中显示。有两种方式可以提供它们:
  • 在运行树上设置 usage_metadata:在您的 @traceable 函数内部调用 get_current_run_tree() / getCurrentRunTree() 并设置 usage_metadata 字段。这不会改变您的函数的返回值。
  • 在输出中返回 usage_metadata:在您的函数返回的字典中包含 usage_metadata 作为顶级键。

支持的 usage_metadata 字段

要直接发送成本(对于非线性定价),您还可以包含 input_cost、output_cost 和 total_cost 字段。有关配置模型定价和在 UI 中查看成本的详细信息,请参阅成本跟踪页面。

首个令牌时间

如果您正在使用 traceable 或其中一个 SDK 封装器,LangSmith 会自动为流式 LLM 运行填充首个令牌时间。但是,如果您直接使用 RunTree API,您需要向运行树添加一个 new_token 事件,以便正确填充首个令牌时间。 这是一个示例:

相关内容