Run（span）数据格式

LangSmith 将每个 run 存储为结构化记录。在导出 trace、查询 API 或构建集成时，了解此格式很有用。

字段名	类型	描述
id	UUID	该 span 的唯一标识符。
name	string	与该 run 关联的名称。
inputs	object	提供给该 run 的输入映射。对于 run_type='llm' 的 run，这通常包含发送给模型的消息对象数组 messages。
run_type	string	Run 的类型，例如 'llm'、'chain'、'tool'。
start_time	datetime	Run 的开始时间。
end_time	datetime	Run 的结束时间。
extra	object	该 run 的任何额外信息。
error	string	如果 run 遇到错误，则为错误消息。
outputs	object	该 run 生成的输出映射。对于 run_type='llm' 的 run，这通常包含模型返回的消息对象数组 messages。
events	array of objects	与该 run 关联的事件对象列表。这与以流式方式执行的 run 相关。
tags	array of strings	与该 run 关联的标签或标记。
trace_id	UUID	该 run 所属 trace 的唯一标识符。它也是该 trace 根 run 的 id 字段
dotted_order	string	排序字符串，具有层级结构。格式：<run_start_time>Z<run_uuid>.<child_run_start_time>Z<child_run_uuid>...
status	string	Run 执行的当前状态，例如 'error'、'pending'、'success'
child_run_ids	array of UUIDs	所有子 run 的 ID 列表。
direct_child_run_ids	array of UUIDs	该 run 的直接子 run 的 ID 列表。
parent_run_ids	array of UUIDs	所有父 run 的 ID 列表。
feedback_stats	object	该 run 的反馈统计聚合
reference_example_id	UUID	与该 run 关联的参考示例 ID。这通常只出现在评估 run 中。
total_tokens	integer	该 run 处理的 token 总数。
prompt_tokens	integer	该 run 的 prompt 中的 token 数。
completion_tokens	integer	该 run 的 completion 中的 token 数。
total_cost	decimal	处理该 run 相关的总成本。
prompt_cost	decimal	该 run 的 prompt 部分相关成本。
completion_cost	decimal	该 run 的 completion 相关成本。
first_token_time	datetime	模型输出第一个 token 生成的时间。仅适用于 run_type="llm" 且启用了流式传输的 run。
session_id	string	该 run 的会话标识符，也称为追踪项目 ID。
in_dataset	boolean	指示该 run 是否包含在数据集中。
parent_run_id	UUID	父 run 的唯一标识符。
execution_order (deprecated)	integer	该 run 在 trace 中的执行顺序。
serialized	object	执行该 run 的对象的序列化状态（如果适用）。
manifest_id (deprecated)	UUID	与该 span 关联的 manifest 标识符。
manifest_s3_id	UUID	该 manifest 的 S3 标识符。
inputs_s3_urls	object	输入的 S3 URL。
outputs_s3_urls	object	输出的 S3 URL。
price_model_id	UUID	应用于该 run 的定价模型标识符。
app_path	string	该 run 的应用（UI）路径。
last_queued_at	datetime	该 span 最后一次排队的时间。
share_token	string	用于共享该 run 数据访问权限的 token。

以下是采用上述格式的 run JSON 表示示例：

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "inputs": {},
  "run_type": "llm",
  "start_time": "2024-04-29T00:49:12.090000",
  "end_time": "2024-04-29T00:49:12.459000",
  "extra": {},
  "error": "string",
  "execution_order": 1,
  "serialized": {},
  "outputs": {},
  "parent_run_id": "f8faf8c1-9778-49a4-9004-628cdb0047e5",
  "manifest_id": "82825e8e-31fc-47d5-83ce-cd926068341e",
  "manifest_s3_id": "0454f93b-7eb6-4b9d-a203-f1261e686840",
  "events": [{}],
  "tags": ["foo"],
  "inputs_s3_urls": {},
  "outputs_s3_urls": {},
  "trace_id": "df570c03-5a03-4cea-8df0-c162d05127ac",
  "dotted_order": "20240429T004912090000Z497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "status": "string",
  "child_run_ids": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"],
  "direct_child_run_ids": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"],
  "parent_run_ids": ["f8faf8c1-9778-49a4-9004-628cdb0047e5"],
  "feedback_stats": {
    "correctness": {
      "n": 1,
      "avg": 1.0
    }
  },
  "reference_example_id": "9fb06aaa-105f-4c87-845f-47d62ffd7ee6",
  "total_tokens": 0,
  "prompt_tokens": 0,
  "completion_tokens": 0,
  "total_cost": 0.0,
  "prompt_cost": 0.0,
  "completion_cost": 0.0,
  "price_model_id": "0b5d9575-bec3-4256-b43a-05893b8b8440",
  "first_token_time": null,
  "session_id": "1ffd059c-17ea-40a8-8aef-70fd0307db82",
  "app_path": "string",
  "last_queued_at": null,
  "in_dataset": true,
  "share_token": "d0430ac3-04a1-4e32-a7ea-57776ad22c1c"
}

运行类型

run_type 字段标识 span 所代表的操作类型。LangSmith 使用它在 trace UI 中应用适当的渲染，并启用类型特定的功能。

Run 类型	描述
chain	步骤的序列或组合。
llm	对语言模型的调用。
embedding	Embedding API 调用。（在 UI 中显示为 chain 图标。）
prompt	在将输入传给模型之前对其进行格式化的 prompt 模板。
tool	由模型调用的函数或外部操作。
retriever	获取相关文档或上下文的查找操作。
parser	将原始模型输出转换为结构化格式的输出解析器。

run_type 应在使用 @traceable 或 RunTree 进行埋点时设置：

Python

from langsmith import traceable

@traceable(run_type="tool")
def my_tool(query: str) -> str:
    ...

TypeScript

import { traceable } from "langsmith/traceable";

const myTool = traceable(
  async (query: string): Promise<string> => {
    // ...
  },
  { run_type: "tool" }
);

某些 run 类型在 LangSmith UI 中有专门的 trace 视图：

• 记录 LLM 调用
• 记录 retriever trace

什么是 dotted_order？

Run 的 dotted order 是一个可排序的键，完整指定了它在追踪层级中的位置。

以下面的示例为例：

import langsmith as ls

@ls.traceable
def grandchild():
    p("grandchild")

@ls.traceable
def child():
    grandchild()

@ls.traceable
def parent():
    child()

如果你打印每个阶段的 ID，可能会得到以下结果：

parent	run_id=0e01bf50-474d-4536-810f-67d3ee7ea3e7	trace_id=0e01bf50-474d-4536-810f-67d3ee7ea3e7  parent_run_id=null	dotted_order=20240919T171648521691Z0e01bf50-474d-4536-810f-67d3ee7ea3e7
child	run_id=a8024e23-5b82-47fd-970e-f6a5ba3f5097	trace_id=0e01bf50-474d-4536-810f-67d3ee7ea3e7  parent_run_id=0e01bf50-474d-4536-810f-67d3ee7ea3e7	dotted_order=20240919T171648521691Z0e01bf50-474d-4536-810f-67d3ee7ea3e7.20240919T171648523407Za8024e23-5b82-47fd-970e-f6a5ba3f5097
grandchild	run_id=0ec6b845-18b9-4aa1-8f1b-6ba3f9fdefd6	trace_id=0e01bf50-474d-4536-810f-67d3ee7ea3e7  parent_run_id=a8024e23-5b82-47fd-970e-f6a5ba3f5097	dotted_order=20240919T171648521691Z0e01bf50-474d-4536-810f-67d3ee7ea3e7.20240919T171648523407Za8024e23-5b82-47fd-970e-f6a5ba3f5097.20240919T171648523563Z0ec6b845-18b9-4aa1-8f1b-6ba3f9fdefd6

注意几个不变量：

• id 等于 dotted order 的最后 36 个字符（最后一个 'Z' 之后的后缀）。例如，孙级 run 中的 0ec6b845-18b9-4aa1-8f1b-6ba3f9fdefd6。
• trace_id 等于 dotted order 中的第一个 UUID（即 dotted_order.split('.')[0].split('Z')[1]）
• 如果 parent_run_id 存在，则它是 dotted order 中的倒数第二个 UUID。例如，孙级 run 中的 a8024e23-5b82-47fd-970e-f6a5ba3f5097。
• 如果按点拆分 dotted_order，则每一段的格式为（<run_start_time>Z<run_id>）

---