追踪查询语法

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	获取给定运行的子运行。这对于获取使用上下文管理器分组在一起的运行或获取 agent 轨迹很有用。
error	获取出错或未出错的运行。
run_ids	获取具有给定运行 ID 列表的运行。注意：这将忽略所有其他过滤参数。
filter	获取匹配给定结构化过滤语句的运行。有关更多详细信息，请参阅过滤查询语言部分。
trace_filter	应用于追踪根运行的过滤器。与 filter 一起使用，以按根运行的属性缩小范围。
tree_filter	应用于追踪树中任何运行（根、同级或子级）的过滤器。与 filter 一起使用，以按追踪中任何运行的属性缩小范围。
is_root	仅返回根运行。
select	选择响应中要返回的字段。默认返回所有字段。可用字段请参阅运行数据格式。
query（实验性）	自然语言查询，会将你的查询转换为过滤语句。

NOTE

性能提示：传递 select 参数并从列表中排除 inputs 和 outputs 可以显著提高查询性能并减小响应大小，尤其是对于大型运行。

过滤查询语言

LangSmith 支持使用过滤查询语言进行过滤，以便在获取运行时执行复杂的过滤操作。这在通过 SDK 或 API 以编程方式查询追踪时特别有用。例如，在评估流水线、监控脚本或检查先前追踪的 agent 工作流中。

比较器

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

比较器	描述	示例
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	string (UUID)	运行 ID
name	string	运行名称
run_type	string	llm、chain、tool、retriever、embedding、prompt、parser 之一
status	string	"success"、"error" 或 "pending"。用于过滤出错与成功的运行。
start_time	ISO 8601 string	例如 "2024-01-15T00:00:00Z"
end_time	ISO 8601 string
latency	duration string or number	秒，例如 "5s"、"1.5s" 或 1.5。仅支持 s 后缀。
tags	list of strings	使用 has(tags, "value")
metadata_key	string	运行元数据字典中的键
metadata_value	string	运行元数据字典中的值
feedback_key	string	反馈分数的名称
feedback_score	number	反馈分数的数值

值格式

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

快速参考示例

以下示例仅显示过滤字符串。将该字符串作为 client.list_runs() 或 /runs/query API 端点中的 filter、trace_filter 或 tree_filter 参数传递。

TIP

有关包含 Python、TypeScript 和 Java 代码的完整 SDK 示例，请参阅使用 SDK 查询追踪。

按运行名称过滤

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

使用 trace_filter 和 tree_filter

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

NOTE

tree_filter 将相同的查询语法应用于追踪树中任意位置的运行。对于任意嵌套子运行字段（例如返回的 inputs、outputs 或 extra 负载路径）上的谓词，请先使用服务器端过滤器缩小候选范围，然后使用子运行填充根追踪并在本地遍历。请参阅使用子运行谓词查询追踪树。

---