以编程方式使用文档

这 LangSmith SDK 和 REST API 允许您使用一组筛选参数和结构化筛选查询语言以编程方式过滤、查询和导出 运行 。本页面记录了筛选参数和查询语言，并提供了常见查询的示例。

有关将这些筛选器与 SDK 结合使用的可运行端到端示例，请参阅 使用 SDK 查询追踪.

筛选参数

键名描述
project_id / project_name要从中获取运行的单个项目或项目列表。
trace_id获取属于特定追踪的运行。
run_type要获取的 运行类型 ，例如 llm, chain, tool, retriever.
dataset_name / dataset_id获取与指定数据集中某一行示例关联的运行。这对于比较给定数据集中的提示词或模型很有用。
reference_example_id获取与特定示例行关联的运行。这对于比较给定输入上的提示词或模型很有用。
parent_run_id获取作为给定运行的子级的运行。这对于获取使用上下文管理器分组的运行或获取智能体轨迹很有用。
error获取出错或未出错的运行。
run_ids按给定的运行 ID 列表获取运行。注意： **这将忽略所有其他筛选参数。**
filter获取匹配给定结构化筛选语句的运行。更多详细信息，请参阅 筛选查询语言 部分。
trace_filter应用于追踪的根运行的筛选器。与 filter 一起使用以按根运行的属性缩小范围。
tree_filter应用于追踪树中任何运行的筛选器（根运行、兄弟运行或子运行）。与 filter 一起使用以按追踪内任何运行的属性缩小范围。
is_root仅返回根运行。
select选择要在响应中返回的字段。默认返回所有字段。参见 运行数据格式 了解可用字段。
query (_实验性_)自然语言查询，可将您的查询转换为过滤语句。

过滤查询语言

LangSmith 支持使用过滤查询语言进行过滤功能，以便在获取运行记录时执行复杂的过滤操作。这在使用 SDK 或 API 以编程方式查询追踪时特别有用。例如，在 评估 管道、监控脚本或代理工作流中检查之前的 追踪.

比较器

过滤语法基于应用于运行对象字段的比较函数：

比较器描述示例
eq等于eq(run_type, "llm")
neq不等于neq(status, "error")
gt大于gt(latency, "5s")
gte大于或等于gte(latency, 1.5)
lt小于lt(start_time, "2024-01-01T00:00:00Z")
lte小于或等于lte(feedback_score, 0.5)
has检查运行是否包含标签或元数据键值对has(tags, "production")
search在所有字符串字段中搜索子字符串search("invoice")
in检查字段值是否在列表中in(metadata_key, ["session_id", "thread_id"])

逻辑运算符

使用 and 和 or 组合多个比较器：

and(eq(run_type, "llm"), gt(latency, "2s"))
or(eq(status, "error"), and(eq(feedback_key, "score"), lt(feedback_score, 0.5)))

可过滤字段

字段类型备注
id字符串 (UUID)运行 ID
name字符串运行名称
run_type字符串之一 llm, chain, tool, retriever, embedding, prompt, parser
status字符串"success", "error", or "pending"。使用此字段可过滤出错与成功的运行。
start_timeISO 8601 字符串例如 "2024-01-15T00:00:00Z"
end_timeISO 8601 字符串
latency持续时间字符串或数字秒数，例如 "5s", "1.5s", or 1.5。仅支持 s 后缀。
tags字符串列表使用 has(tags, "value")
metadata_key字符串运行元数据字典中的键
metadata_value字符串运行元数据字典中的值
feedback_key字符串反馈分数名称
feedback_score数字反馈分数的数值

值格式化

  • 字符串：用双引号或单引号包裹， eq(name, "MyChain") or eq(name, 'MyChain').
  • 时间戳：ISO 8601 格式， "2024-06-01T00:00:00Z".
  • 持续时间：秒数，可以是数字或带 s 后缀的字符串， "5s", "1.5s", "90s", or 1.5。其他单位后缀（m, h）不支持。
  • 列表：JSON 数组语法， ["session_id", "thread_id"].

快速参考示例

以下示例仅显示过滤器字符串。将字符串作为 filter, trace_filter, or tree_filter 参数传入 client.list_runs() 或 /runs/query API 端点。

按运行名称筛选

eq(name, "my_chain")

按错误状态筛选

# Runs that errored
eq(status, "error")

# Runs that did not error
eq(status, "success")

按延迟筛选

# Runs slower than 5 seconds
gt(latency, "5s")

# Runs faster than 1 second
lt(latency, "1s")

按时间范围筛选

and(gt(start_time, "2024-01-01T00:00:00Z"), lt(start_time, "2024-02-01T00:00:00Z"))

按标签筛选

has(tags, "production")

# Multiple tags (any match)
or(has(tags, "production"), has(tags, "staging"))

按元数据键或值筛选

# Runs with a "user_id" metadata key
eq(metadata_key, "user_id")

# Runs with a specific user ID value
and(eq(metadata_key, "user_id"), eq(metadata_value, "usr_abc123"))

# Runs from the production environment
and(eq(metadata_key, "environment"), eq(metadata_value, "production"))

按线程 ID 筛选

and(in(metadata_key, ["session_id", "thread_id"]), eq(metadata_value, "<your_thread_id>"))

按反馈分数筛选

# Runs with a "thumbs_up" score of 1
and(eq(feedback_key, "thumbs_up"), eq(feedback_score, 1))

# Runs with a "correctness" score below 0.5
and(eq(feedback_key, "correctness"), lt(feedback_score, 0.5))

跨所有字符串字段的全文搜索

search("my search term")

组合条件

# Errors that started after a specific time
and(gt(start_time, "2024-06-01T00:00:00Z"), eq(status, "error"))

# Slow LLM runs with low correctness feedback
and(gt(latency, "10s"), eq(feedback_key, "correctness"), lt(feedback_score, 0.5))

# Complex: errors OR low score, both starting after a timestamp
and(gt(start_time, "2023-07-15T12:34:56Z"), or(eq(status, "error"), and(eq(feedback_key, "Correctness"), eq(feedback_score, 0.0))))

使用追踪_过滤器和树_过滤器

filter 应用于返回的运行。 trace_filter 应用于追踪的根运行。 tree_filter 应用于追踪树中任意位置的运行。

# filter: the run you want
eq(name, "RetrieveDocs")

# trace_filter: condition on the root run (e.g. human feedback on the overall trace)
and(eq(feedback_key, "user_score"), eq(feedback_score, 1))

# tree_filter: condition on any run in the trace tree
eq(name, "ExpandQuery")