过滤追踪

通过在搜索栏里写过滤查询，在一个 LangSmith 追踪项目中找到特定的线程、追踪和运行。

过滤把一个追踪项目里的运行收窄到那些需要注意的，例如出错的会话、慢的工具调用，或带低反馈分数的运行。在搜索栏里写一个查询，然后选择该查询在追踪或线程层级里针对哪些运行匹配。

NOTE

追踪项目有两种过滤体验。查看你项目顶部，确认哪一种适用于你：

• 一个带左侧范围选择器的搜索栏：参阅过滤追踪。
• 一个构建过滤 chip 的 Add filter 按钮：参阅过滤追踪（ClickHouse）。

本页涵盖：

• 在搜索栏里构建一个查询
• 用作用域选择过滤器匹配什么
• 查询语法以及可用于过滤的字段
• 供复制和改用的示例
• 从 Shortcuts 面板一键过滤
• 把一个过滤器另存为视图
• 过滤一条追踪内的运行
• 全文搜索索引什么
• 排查一个查询

要改以编程方式查询运行，参阅用 SDK 查询追踪。SDK 和 REST API 用一个独立的结构化查询语言，记录在追踪查询语法。

构建一个查询

一个查询由若干子句组成，每个子句把一个字段与一个运算符和一个值配对：

status:error

要构建一个查询，点击搜索栏并开始输入：

Choose a field

输入一个字段名，或从建议列表中选一个。建议按类别分组，Recents 列出你先前运行过的查询。用arrow="true" 键在列表中移动，按 Enter 选择。

Choose an operator

输入 : 以查看该字段支持的运算符，每个都带一个例子。

Enter a value

对于 LangSmith 会索引其值的字段（例如运行名和标签），建议列表会给出项目中最常见的值。

每个完成的子句在栏中变成一个 chip。点击一个 chip 编辑它，或点击它的移除图标删除它。在一个 chip 之后继续输入以添加另一个子句。

搜索栏之外的两个控件也会影响结果：

• 时间范围控件与查询一起应用。结果必须落在时间范围内且匹配查询。
• Threads、Traces 和 Runs 选择设定表中每行代表什么，它也决定一个查询能用哪些作用域。

NOTE

搜索栏使用本页描述的语法，它不是 SDK 和 REST API 接受的结构化查询语言。关于那门语言，参阅追踪查询语法。

选择过滤器匹配什么

一条追踪是一棵运行的树，一个线程是一串追踪。像 status:error 这样的子句在你说明它作用于该层级中哪些运行之前是有歧义的：启动追踪的那个运行、其内任意任意位置的运行，还是整个线程。作用域选择器就在搜索栏左侧，那是你说明的地方。

有四个作用域可用：

• Thread：匹配整个线程。
• Root run：只匹配入口运行。
• Single run：匹配运行自身。
• Any run：匹配树中任意位置。

作用域下拉菜单会针对一个示例追踪预览每个选项，因此你能在选择之前看到它覆盖哪些运行：

所提供的作用域，以及默认选中的那个，取决于表选择：

表选择	默认作用域	可用作用域
Threads	Any run	Thread、Root run、Any run
Traces	Root run	Root run、Any run
Runs	Single run	Single run、Root run、Any run

结合作用域

要一次在多个作用域上过滤，点击 Filter。这会添加一行，带它自己的作用域选择器和搜索栏。各行用 AND 结合，所以一个线程、追踪或运行必须满足每一行才会出现在表中。

每个作用域最多持有一行，所以 Threads 和 Runs 选择接受三行，而 Traces 接受两行。当每个可用作用域都在用时，Filter 被禁用。要移除一行，点击它旁边的 Remove filter。

例如，在 Threads 视图中，找到超过 20 轮且含一个失败工具调用的线程：

作用域	查询
Thread	turn_count:>20
Any run	run_type:tool AND status:error

表选择无法使用的作用域

更改表选择可能让一行留在新选择不支持的作用域上，例如从 Runs 切到 Threads 后的一个 Single run 行。该行带着一个 Not applied 徽标保持可见，其查询被保留但不应用。更改该行的作用域，或返回一个兼容的表选择，以再次应用它。

查询语法

运算符

一个字段接受的运算符取决于它的类型。

运算符	语法	匹配
is	field:value	对值精确匹配。
is not	-field:value	除精确匹配外的一切。
matches	field:~value	对该字段的全文搜索。给值加引号以搜索一个短语。
does not match	-field:~value	全文搜索不匹配的一切。
wildcard	field:value*	一个模式，其中 * 代表任意字符序列。
exists	field:*	该字段被设置的记录。
does not exist	-field:*	该字段未被设置的记录。
comparison	field:>value	高于给定值的值。也接受 >=、< 和 <=。
inclusive range	field:[10 TO 20]	从 10 到 20 的值，含两个边界。
exclusive range	field:{10 TO 20}	10 与 20 之间的值，不含两个边界。
mixed range	field:[10 TO 20}	从 10 起但不含 20 的值。交换定界符以反转哪个边界含端点。

某些字段只接受这些运算符的一个子集：

• 全文字段：input、output、metadata 和 error 只接受 ~。
• 比较和范围运算符：这些适用于像 latency 和 total_tokens 这样的数值字段、像 first_token_time 这样的时间戳字段，以及数值型的 metadata 路径。

要匹配几个值中的任一个，用 OR 组合子句，例如 status:error OR status:interrupted。在一个子句内列出几个值不受支持。

组合子句

用 AND、OR、NOT 和括号组合子句：

• AND：两个子句都必须匹配。两个子句之间的空白充当 AND，所以 status:error run_type:llm 与 status:error AND run_type:llm 等价。
• OR：任一子句必须匹配。
• NOT：否定其后的子句。- 前缀做同样的事，所以 NOT status:error 与 -status:error 等价。
• 括号：分组子句以控制优先级。

AND 比 OR 结合更紧，所以 a OR b AND c 匹配 a OR (b AND c)。分组子句以改变这一点：(a OR b) AND c。

关键字不区分大小写。

引用值

给一个含空格、含冒号，或包含一个字面匹配字符的值加双引号：

name:"docs agent"
tags:"env:prod"

加引号也会关闭通配符匹配，所以 name:"docs*" 匹配字面字符串 docs*。作为加引号的替代，用一个反斜杠转义那个字符，如 name:docs\ agent。

在运行作用域中，一个未加引号、含空格的值会拆成两个子句，所以 name:docs agent 匹配名字是 docs、且其被索引内容含 agent 的运行。

不命名字段就搜索

在 Single run、Root run 和 Any run 作用域中，一个裸词会搜索每个被索引字段：

"capital of France"

Thread 作用域不支持裸词搜索。

字段

建议列表把字段分成类别。可用的字段取决于过滤器行的作用域。

运行字段

这些字段在 Single run、Root run 和 Any run 作用域中可用。

运行属性

字段	描述
name	运行名。支持通配符。
status	运行状态：pending、success、error 或 interrupted。
run_type	运行类型，例如 llm、chain、tool 或 retriever。
tags	运行标签。若运行上任一标签匹配，则子句匹配。

内容

字段	描述
input	运行输入。用 ~ 搜索文本，或用 input.<key> 匹配一个 JSON 键。
output	运行输出。用 ~ 搜索文本，或用 output.<key> 匹配一个 JSON 键。
metadata	运行元数据。用 metadata.<key> 匹配一个 JSON 键，或用 ~ 搜索元数据值。
error	错误文本。用 ~ 搜索文本。
attachments	附件名。

身份

字段	描述
id、trace_id、thread_id、parent_run_id	按 ID 匹配一个特定的运行、追踪、线程或父运行。
ls_user_id	该运行归属到的 LangSmith 用户。

性能

字段	描述
latency	运行时长（秒）。
first_token_time	首个 token 产生之时。
prompt_tokens、completion_tokens、total_tokens	运行的 token 数。
prompt_cost、completion_cost、total_cost	运行的成本。
prompt_token_details、completion_token_details	token 细分。用点记法寻址一个组件，例如 prompt_token_details.cache_read 或 completion_token_details.reasoning。
prompt_cost_details、completion_cost_details	成本细分，组件与 token 细分相同。

反馈

字段	描述
feedback	运行上的反馈。参阅在反馈上过滤。

元数据和标签通常是最高产的过滤字段，因为你能控制往里放什么。见向追踪添加元数据和标签。

线程字段

Thread 作用域就线程整体的属性过滤，因此它支持一组不同的字段。建议列表把该组标为 Thread attributes。

字段	描述
thread_id	线程 ID。
turn_count	线程中的轮次。
num_errored_turns	以错误结束的轮次。
thread_duration	从首轮开始到末轮结束。
trace_latency_p50	轮次延迟中位数。
trace_latency_p99	P99 轮次延迟。
total_tokens	线程跨所有 token。
total_cost	线程跨所有成本。
prompt_token_details、completion_token_details、prompt_cost_details、completion_cost_details	线程跨所有的 token 与成本细分。

NOTE

像 name、status 和 input 这样的运行字段在 Thread 作用域中不可用。要按线程内所含运行的某个属性过滤线程，在 Any run 作用域添加第二行过滤器。参阅结合作用域。

匹配一个 JSON 键

input、output 和 metadata 持有 JSON。用点记法寻址它们内部的一个键：

metadata.env:production
input.user_id:abc123
output.status:success

嵌套路径以同样方式工作，例如 metadata.config.temperature:0.7。给一个含点的键加引号，如 metadata."my.key":production。

只有 metadata 路径支持比较和范围运算符，且只在值为数值时：

metadata.retries:>=3

在反馈上过滤

用点记法寻址一个反馈键及其某个子字段：

feedback.correctness.score:>=0.5
feedback.relevance.value:pass
feedback.quality.comment:~helpful

可用的子字段是 key、score、value、comment、source 和 error。在 Thread 作用域中，只有 key、score 和 value 可用。

要匹配携带任何反馈的记录，用 feedback:*。要匹配携带某个特定反馈键（不论其值）的记录，用 feedback.<key>:*。比较一个值需要点名一个子字段，所以 feedback.correctness:0.5 无效。

用 feedback:{...} 分组一个反馈条件：

feedback:{correctness.score:>0.5}

示例

供复制和改用的查询。除非另有说明，每个都假设其表选择的默认作用域。

也慢的出错 LLM 调用。 用 Runs 选择：

run_type:llm AND status:error AND latency:>10

你的评估器打分很差的运行。 用 Runs 选择：

run_type:llm AND feedback.correctness.score:<0.5

未成功的生产流量。 用 Traces 选择：

metadata.env:production AND -status:success

提到某话题且出了错的会话。 用 Threads 选择：

input:~"refund" AND status:error

调用了某个特定工具的追踪。 用 Traces 选择配 Any run 作用域，使该子句针对追踪内每个运行而非入口运行匹配：

run_type:tool AND name:search_documents

昂贵的追踪。 用 Traces 选择：

total_cost:>0.5

用快捷方式过滤

表左侧的 Shortcuts 面板列出项目中最常见的值，按 Status、Run Name、Run Type、Tag、Metadata 和 Feedback 分组。这些组对应 status、name、run_type、tags、metadata 和 feedback 字段。选一个值会把匹配的子句加到搜索栏，所以最常见的过滤器只需一键而非一个手打查询。

每个组标题显示它的值有多少是活动的。用 Feedback 组里的搜索框来找一个反馈键。

要给表腾出更多空间，点击 Hide shortcuts，然后 Show shortcuts 把面板带回。右侧的 Stats 面板以同样方式折叠，用 Hide stats 和 Show stats。

保存一个过滤器

已保存视图存储一个过滤器以便复用。一个视图属于追踪项目而非创建它的人，所以任何有项目访问权的人都能选它。

要保存当前过滤器：

1. 构建查询。
2. 点击 Save View。
3. 输入一个名字和描述，然后保存。

该视图随后会出现在 Views 下拉菜单中，与 Default view 并列。每个条目列出它的过滤器使用哪些作用域，这一眼就能看出它是否适用于当前表选择。

要更新一个已保存视图，选中它、更改查询，然后点击 Save View。要重命名或删除一个视图，点击它在

•

Views 下拉菜单中旁边的图标。

要丢弃未保存的更改并返回选中的视图，点击 Reset。

用先前语法保存的视图

在这个过滤体验发布之前保存的视图继续工作。选中一个会把它的过滤器翻译成本页的语法，LangSmith 会提示你保存翻译后的视图。

过滤一条追踪内的运行

在一条打开的追踪内过滤会高亮匹配的运行，这就是你在大追踪中找到重要那个的方式。打开一个线程或追踪以进入 Details 视图，然后用运行列表上方的 Filter runs。

匹配的运行就地高亮，追踪的其余部分保持在它们周围可见，所以一个匹配保留了解释它的上下文。在 Any run 作用域应用的过滤器会自动带过来，所以从表中打开一个线程或追踪会高亮匹配它的运行。

这个搜索栏接受与项目页上 Single run 作用域相同的字段和语法。它没有作用域选择器，因为它总是匹配打开追踪内的单个运行。要移除过滤器，点击过滤器框里的清除图标。

Visibility 选项是运行列表上方那个

•

图标后面的选项，Most relevant 和 Show All，在应用了过滤器时被禁用。

全文搜索索引

~ 运算符和裸词搜索是针对一个派生的搜索索引匹配，而非针对所存的运行数据。LangSmith 通过从运行输入、输出和错误里的字符串值递归提取搜索令牌来构建那个索引。对象键不被索引，值也不会因其长度而被拒绝或截断。

以下限制适用于索引：

• 每字段令牌数：LangSmith 为每个被索引字段保留最多 2,000 个不同的搜索令牌，从最多 200,000 个不同候选中选出。
• 嵌套深度：LangSmith 处理嵌套数据到最大 30 层深度。
• 令牌长度：一个搜索令牌介于 2 到 44 个 ASCII 字符之间。该范围之外的字符串不被索引，且非 ASCII 文本按其占据的空间而非字符数衡量。
• 排除内容：URL、图片数据 URL、纯数值令牌，以及像 "the" 和 "of" 这样的常见停用词不被索引。

这些限制只管搜索索引。运行数据被完整存储，所以索引略去的一个值在追踪本身中仍可见。

元数据和键路径被分别索引。键路径过滤不受全文令牌限制约束，且 LangSmith 目前不为它发布单独的限制。像 input.<key> 或 metadata.<key> 这样的过滤器在某个特定路径找值，所以它仍能匹配全文索引略去的值。参阅匹配一个 JSON 键。

排查一个查询

搜索栏把查询标为无效。 该栏在你输入时验证并内联点名问题，包括未知字段名、不平衡的引号或括号，以及一个被空格从其冒号分开的运算符。修复它所指的那个子句。

查询有效但什么都不匹配。 按顺序排查这些：

1. 检查时间范围。 它与查询一起应用，所以若匹配的运行落在窗口之外，一个正确的过滤器仍会返回空。
2. 检查作用域。 一个针对层级错误一级测试的子句是最常见的原因。在 Root run 作用域用 run_type:llm 过滤追踪，只匹配入口运行是 LLM 调用的追踪，这很少是你想要的。把该行切到 Any run。
3. 检查有没有 Not applied 徽标。 一行处在当前表选择不支持的作用域上，会被保留但不应用。
4. 检查值是否被索引。 全文搜索跳过 URL、停用词、纯数值令牌，以及很短或很长的令牌。改用一个 JSON 键过滤，它不受那些限制。

另请参阅

• 查看追踪
• 线程
• 向追踪添加元数据和标签
• 面向 SDK 和 REST API 查询语言的追踪查询语法
• 用 SDK 查询追踪

---