运行树 (Run Trees)

langsmith.run_trees

LangSmith API 的模式。

RunTree

基类：RunBase

带有用于发布运行的向后引用的运行模式。

方法	描述
infer_defaults	为运行分配名称。
ensure_dotted_order	确保运行的点分顺序。
__setattr__	特殊地设置 _client。
set	设置运行的输入、输出、标签和元数据。
add_tags	向运行添加标签。
add_metadata	向运行添加元数据。
add_outputs	将给定的输出更新并插入到运行中。
add_inputs	将给定的输出更新并插入到运行中。
add_event	向事件列表添加一个事件。
end	设置运行和所有子运行的结束时间。
create_child	向运行树添加一个子运行。
post	异步地将运行树发布到 API。
patch	在后台线程中将运行树修补到 API。
wait	等待所有 _futures 完成。
get_url	返回运行的 URL。
from_dotted_order	根据提供的点分顺序创建一个新的“子”跨度。
from_runnable_config	根据提供的可运行配置创建一个新的“子”跨度。
from_headers	根据提供的头信息创建一个新的“父”跨度。
to_headers	将 RunTree 作为头信息字典返回。
__repr__	返回 RunTree 对象的字符串表示形式。

name 实例属性

name: str

运行的人类可读名称。

id 类属性 实例属性

id: UUID = Field(default_factory=uuid4)

运行的唯一标识符。

run_type 类属性 实例属性

run_type: str = Field(default='chain')

运行的类型，例如工具、链、LLM、检索器、嵌入、提示、解析器。

start_time 类属性 实例属性

start_time: datetime = Field(default_factory=lambda: now(utc))

运行的开始时间。

extra 类属性 实例属性

extra: dict = Field(default_factory=dict)

与运行相关的附加元数据或设置。

tags 类属性 实例属性

tags: list[str] | None = Field(default_factory=list)

用于分类或注释运行的标签。

events 类属性 实例属性

events: list[dict] = Field(default_factory=list)

与运行相关联的事件列表，如开始和结束事件。

client 属性

client: Client

返回客户端。

end_time 类属性 实例属性

end_time: datetime | None = None

运行的结束时间（如果适用）。

error 类属性 实例属性

error: str | None = None

错误消息，如果运行遇到任何问题。

serialized 类属性 实例属性

serialized: dict | None = None

执行运行的序列化对象，以备潜在重用。

inputs 类属性 实例属性

inputs: dict = Field(default_factory=dict)

用于运行的输入。

outputs 类属性 实例属性

outputs: dict | None = None

由运行生成的输出（如果有）。

reference_example_id 类属性 实例属性

reference_example_id: UUID | None = None

对此运行可能基于的示例的引用。

parent_run_id 类属性 实例属性

parent_run_id: UUID | None = None

父运行的标识符，如果此运行是子运行。

attachments 类属性 实例属性

attachments: Attachments | dict[str, AttachmentInfo] = Field(default_factory=dict)

与运行相关联的附件。每个条目是一个（mime_type, bytes）的元组。

metadata 属性

metadata: dict[str, Any]

检索元数据（如果有）。

revision_id 属性

revision_id: UUID | None

检索修订 ID（如果有）。

latency 属性

latency: float | None

延迟，以秒为单位。

Config

Pydantic 模型配置。

infer_defaults

infer_defaults(values: dict) -> dict

为运行分配名称。

ensure_dotted_order

ensure_dotted_order(values: dict) -> dict

确保运行的点分顺序。

__setattr__

__setattr__(name, value)

特殊地设置 _client。

set

set(
    *,
    inputs: Mapping[str, Any] | None = NOT_PROVIDED,
    outputs: Mapping[str, Any] | None = NOT_PROVIDED,
    tags: Sequence[str] | None = NOT_PROVIDED,
    metadata: Mapping[str, Any] | None = NOT_PROVIDED,
    usage_metadata: ExtractedUsageMetadata | None = NOT_PROVIDED,
) -> None

设置运行的输入、输出、标签和元数据。

如果执行此操作，将覆盖 end() 方法的默认行为，以忽略由 @traceable 装饰器添加的新输出。

如果您的 LangChain 或 LangGraph 版本足够新，这也会覆盖 LangChainTracer 的默认行为。

参数	描述
inputs	要设置的输入。 类型： Mapping[str, Any] | None 默认值： NOT_PROVIDED
outputs	要设置的输出。 类型： Mapping[str, Any] | None 默认值： NOT_PROVIDED
tags	要设置的标签。 类型： Sequence[str] | None 默认值： NOT_PROVIDED
metadata	要设置的元数据。 类型： Mapping[str, Any] | None 默认值： NOT_PROVIDED
usage_metadata	要设置的使用信息。 类型： ExtractedUsageMetadata | None 默认值： NOT_PROVIDED

返回	描述
None	None

add_tags

add_tags(tags: Sequence[str] | str) -> None

向运行添加标签。

add_metadata

add_metadata(metadata: dict[str, Any]) -> None

向运行添加元数据。

add_outputs

add_outputs(outputs: dict[str, Any]) -> None

将给定的输出更新并插入到运行中。

参数	描述
outputs	包含要添加的输出的字典。 类型： Dict[str, Any]

返回	描述
None	None

add_inputs

add_inputs(inputs: dict[str, Any]) -> None

将给定的输出更新并插入到运行中。

参数	描述
outputs	包含要添加的输出的字典。 类型： Dict[str, Any]

返回	描述
None	None

add_event

add_event(events: RunEvent | Sequence[RunEvent] | Sequence[dict] | dict | str) -> None

向事件列表添加一个事件。

返回	描述
None	None

end

end(
    *,
    outputs: dict | None = None,
    error: str | None = None,
    end_time: datetime | None = None,
    events: Sequence[RunEvent] | None = None,
    metadata: dict[str, Any] | None = None,
) -> None

设置运行和所有子运行的结束时间。

create_child

create_child(
    name: str,
    run_type: RUN_TYPE_T = "chain",
    *,
    run_id: ID_TYPE | None = None,
    serialized: dict | None = None,
    inputs: dict | None = None,
    outputs: dict | None = None,
    error: str | None = None,
    reference_example_id: UUID | None = None,
    start_time: datetime | None = None,
    end_time: datetime | None = None,
    tags: list[str] | None = None,
    extra: dict | None = None,
    attachments: Attachments | None = None,
) -> RunTree

向运行树添加一个子运行。

post

post(exclude_child_runs: bool = True) -> None

异步地将运行树发布到 API。

patch

patch(*, exclude_inputs: bool = False) -> None

在后台线程中将运行树修补到 API。

参数	描述
exclude_inputs	是否从修补请求中排除输入。 类型： bool 默认值： False

wait

wait() -> None

等待所有 _futures 完成。

get_url

get_url() -> str

返回运行的 URL。

from_dotted_order 类方法

from_dotted_order(dotted_order: str, **kwargs: Any) -> RunTree

根据提供的点分顺序创建一个新的“子”跨度。

返回	描述
RunTree	新的跨度。 类型： RunTree

from_runnable_config 类方法

from_runnable_config(config: dict | None, **kwargs: Any) -> RunTree | None

根据提供的可运行配置创建一个新的“子”跨度。

需要安装 langchain。

返回	描述
RunTree | None	Optional[RunTree]：新的跨度，如果未找到父跨度信息则为 None。

from_headers 类方法

from_headers(
    headers: Mapping[str | bytes, str | bytes], **kwargs: Any
) -> RunTree | None

根据提供的头信息创建一个新的“父”跨度。

从头信息中提取父跨度信息并创建一个新的跨度。元数据和标签从 baggage 头中提取。点分顺序和跟踪 ID 从 trace 头中提取。

返回	描述
RunTree | None	Optional[RunTree]：新的跨度，如果未找到父跨度信息则为 None。

to_headers

to_headers() -> dict[str, str]

将 RunTree 作为头信息字典返回。

__repr__

__repr__()

返回 RunTree 对象的字符串表示形式。

configure

configure(
    client: Client | None = _SENTINEL,
    enabled: bool | None = _SENTINEL,
    project_name: str | None = _SENTINEL,
    tags: list[str] | None = _SENTINEL,
    metadata: dict[str, Any] | None = _SENTINEL,
)

配置全局 LangSmith 跟踪上下文。

此函数允许您为 LangSmith 跟踪设置全局配置选项，这些选项将应用于所有后续的跟踪操作。它会修改控制您应用程序中跟踪行为的上下文变量。

在启动时执行此操作一次，以在代码中配置全局设置。

如果您只想为单次调用配置跟踪，请改用 tracing_context 上下文管理器。

参数	描述
client	一个 LangSmith 客户端实例，用于所有跟踪操作。如果提供，将使用此客户端而不是创建新客户端。传递 None 可明确清除全局客户端。 类型： Client | None 默认值： _SENTINEL
enabled	跟踪是否已启用。可以是：- True：启用跟踪并将数据发送到 LangSmith - False：完全禁用跟踪 - "local"：启用跟踪但仅在本地存储数据 - None：清除设置（回退到环境变量） 类型： bool | None 默认值： _SENTINEL
project_name	跟踪将被发送到的 LangSmith 项目名称。这决定了哪个项目仪表板将显示您的跟踪。传递 None 可明确清除项目名称。 类型： str | None 默认值： _SENTINEL
tags	将应用于所有被跟踪运行的标签列表。标签对于在 LangSmith UI 中过滤和组织运行很有用。传递 None 可明确清除所有全局标签。 类型： list[str] | None 默认值： _SENTINEL
metadata	附加到所有被跟踪运行的元数据字典。元数据可以存储有关您运行的任何附加上下文。传递 None 可明确清除所有全局元数据。 类型： dict[str, Any] | None 默认值： _SENTINEL

返回	描述
	None

示例

基本配置

>>> import langsmith as ls
>>> # Enable tracing with a specific project
>>> ls.configure(enabled=True, project_name="my-project")

设置全局跟踪掩码

>>> def hide_keys(data):
...     if not data:
...         return {}
...     return {k: v for k, v in data.items() if k not in ["key1", "key2"]}
>>> ls.configure(
...     client=ls.Client(
...         hide_inputs=hide_keys,
...         hide_outputs=hide_keys,
...     )
... )

添加全局标签和元数据

>>> ls.configure(
...     tags=["production", "v1.0"],
...     metadata={"environment": "prod", "version": "1.0.0"},
... )

禁用跟踪

>>> ls.configure(enabled=False)

validate_extracted_usage_metadata

validate_extracted_usage_metadata(
    data: ExtractedUsageMetadata,
) -> ExtractedUsageMetadata

验证字典只包含允许的键。