第9课：LangSmith面板全功能精讲【项目管理、运行记录、筛选检索、时序分析】

文章目录

• • 一、开篇导读
  • 二、知识前置铺垫
  • • 2.1 控制台导航的整体布局
    • 2.2 Run与Trace在UI中的含义
    • 2.3 Tracing与Metrics两大视角的分工
    • 2.4 面板操作的学习层次
  • 三、核心概念精讲
  • • 3.1 项目页面的核心组件
    • 3.2 Runs视图的三大筛选维度
    • 3.3 Monitoring仪表板与指标监控
    • 3.4 分享、协作与人工标注链
  • 四、原理底层剖析
  • • 4.1 Runs列表的数据填充与分页机制
    • 4.2 Filter Query Language的执行路径
    • 4.3 预置仪表板的指标聚合计算
    • 4.4 Annotation Queue的数据流转
  • 五、环境配置手把手实战
  • • 5.1 登录并导航LangSmith主页
    • 5.2 创建演示项目与示例数据
    • 5.3 查看预置仪表板
    • 5.4 创建第一个Annotation Queue
  • 六、完整可运行代码案例
  • • 6.1 最佳筛选组合——使用前端filter框排查故障
    • 6.2 通过Python SDK运行复杂查询——找出比“基准链”更耗时的异常模式
    • 6.3 使用Prebuilt仪表板监控Token成本趋势
    • 6.4 Sharing URL快速传送异常Trace
    • 6.5 注解队列人工标注与多轮反馈闭环
    • 6.6 使用Insights Agent(洞察代理)自动发现Agent行为模式
  • 七、代码逐行详解
  • • 7.1 动态构建复杂filter组合查询
    • 7.2 使用client.list_runs实现分页和限流
    • 7.3 Project ID与Project Name的选择
  • 八、常见坑点与避坑指南
  • • 8.1 Filter表达式大小写敏感与空格问题
    • 8.2 误把Metadata当成Tag使用筛选效率低
    • 8.3 预置仪表板数值延迟现象
    • 8.4 Annotation Queue自动分流规则过于宽广
    • 8.5 Insights Agent需要足够的“冷数据”样本
  • 九、企业级落地最佳实践
  • • 9.1 统一仪表板设计规范
    • 9.2 团队协作与权限分离
    • 9.3 数据生命周期自动转储
    • 9.4 Annotation Queue与Evals集成
    • 9.5 嵌入团队文档自动报告
  • 十、本节知识点总结
  • 十一、课后思考练习题
  • • 练习题1：理论理解
    • 练习题2：动手实践
    • 练习题3：场景设计
  • 🔗《20节课 LangSmith 从入门到精通》系列课程导航

一、开篇导读

经过前面八节课的学习，我们已经从零开始构建了完整的LangSmith认知体系：从第一课的整体认知、第二课的账号注册与计费规则、第三课的环境搭建、第四课的核心概念拆解，到第五课的快速入门实战，再到第六课的环境变量密钥配置、第七课的Prompt-LLM-Chain全链路监控，以及第八课的LCEL链路拆解与可视化调试。现在，我们已经有了一个能稳定运行、全链路可追踪的LangSmith应用——每天有成百上千的Trace数据流入你的LangSmith项目。

但是，当数据量开始增长时，一个新的问题出现了：你不再只有一个孤立的Trace，而是面对一个包含成百上千个Runs的复杂项目。如何从海量数据中快速找到出错的调用？如何对比两个版本Prompt的效果差异？如何识别Token消耗异常升高的趋势？如何给团队成员分享一个问题的调试链接？如何让系统自动发现反复出现的故障模式？

这些问题无法仅靠“会写追踪代码”来回答。我们需要深入LangSmith Web控制台的每一个功能模块，把“查看数据”升级为“驾驭数据”。

目前LangSmith国内中文站已上线Playground、数据集评估和Trace对比等核心指引页面。这些功能深度嵌入在项目的各个视图中；学会它们，就掌握了现代LLM工程化中调试、监控与迭代的完整能力。本节课秉持“从实战中来，到实战中去”的原则——每一节都配有具体功能的分步骤解析和大量真实场景实用示例。我们会从三大模块展开：Project与组织管理模块、Runs视图与筛选检索模块，以及时序仪表板和指标分析模块。

本节课你将收获：

• 项目全景管理：掌握LangSmith左侧边栏的Structure结构——Projects/Traces/Playground/Automations等核心入口，学会创建和归档项目
• 精细化筛选查询：灵活使用Project页面、Traces页面和Monitors页面三层筛选视图，掌握基于Run列表头、属性面板及前端filter比较器的全部筛选语法
• 高级查找与分组：在SDK层面使用list_runs及其强大Filter Query Language，实现跨维度运行数据组合分析；在UI层面学会按Tag或Metadata进行分组聚合统计
• 完善的协作工具链：熟练使用Annotation Queue做人工审查数据标注，掌握Shared Links和Embed功能
• 智能运维辅助：掌握Insights Agent自动Agent分析功能、Playground快速迭代、Evaluation评估工作流与数据集驱动的一键测试

二、知识前置铺垫

2.1 控制台导航的整体布局

LangSmith主界面的左侧边栏是日常效率和体验的核心。主要模块包括：

• Projects（项目）：所有追踪数据的根容器，项目之间数据天然隔离
• Playground（游乐场）：可视化交互环境，用来微调提示词原型、实时测试不同参数配置
• Datasets & Experiments（数据集与实验）：归集评估数据和实验运行记录的关键入口
• Monitoring（监控）：时序仪表板（含预置仪表板与自定义仪表板），实时观测KPI指标趋势
• Automations（自动化）：规则引擎与自动化评测、队列自动分发
• Settings（设置）：团队权限、API Keys、计费等管理

2.2 Run与Trace在UI中的含义

在LangSmith面板中，“Run”指代追踪树中的一个操作单元，“Trace”则由Root Run及其所有子Run构成。Run视图精确还原了链式调用中每一个组件（Prompt、LLM、Tool、Retriever等）的属性组。大多数时间，我们都是在Runs列表视图和详情视图中分析问题。

2.3 Tracing与Metrics两大视角的分工

LangSmith提供两种互补的数据观察视角：

• Traces视角：侧重微观每一次执行的“体内结构”（用于深入调试、对比链中环节）
• Monitoring视角：侧重宏观聚合指标（trace计数、延迟、错误率、token消耗、成本），以及时序趋势洞察

实践中，我们常先看Monitors仪表板发现潜在异常，再点击最高频错误或延迟最高的Trace，进入Traces视图进一步归因。

2.4 面板操作的学习层次

LangSmith面板学习可以遵循三阶段：熟悉界面布局和默认功能、利用筛选器和查询语法定向检索、参与高度定制化指标监控和团队行为管理。本节课将完整覆盖这三层能力。

三、核心概念精讲

3.1 项目页面的核心组件

Project概述：Projects页面位于左侧边栏首位，每个项目都包含一个独特的project_id，可通过URL直接定位。点击项目名称，进入默认的“Runs”视图，展示该项目的全部运行记录。LangSmith官方将Project描述为负责组织和隔离Tracing与Runs的逻辑容器。

项目级数据一览——当点击项目展开细节，顶部横幅汇总Trace总数和最近活跃状态；底部Runs列表支持时间排序与自定义列宽，右侧可随时切换“Graph”、“Feedback”等视图。

项目级操作：左上角菜单可创建新项目、重命名或归档归档项目不会删除数据但会从活动项目列表中隐藏。在项目设置中还可以查看项目ID，为API筛选提供project_id。

3.2 Runs视图的三大筛选维度

LangSmith的Runs视图是日常调试的“主战场”，具有多层级筛选能力：

维度一：静态过滤参数——在Runs列表上方，指定筛选条件包括run_type或error等。例如选择“Error”分类，所有失败Trace自动聚合。使用start_time与end_time可精准限定分析窗口。

维度二：列过滤——Run列表每个列头的筛选图标可独立过滤，如name列筛选特定链名称，Tags和Metadata支持快速限定用户维度数据。

维度三：前端filter查询语言——点击列表上方“Filter”输入框，直接输入LangSmith Filter Query Language语句。该语法支持我们对所有Run字段执行精确搜索和比较运算。具体搜索语法将在后续实操部分详细展开——在Filter Query框中输入and error=null latency: >10.0可快速筛选耗时长于10秒的成功执行。

3.3 Monitoring仪表板与指标监控

Monitoring仪表板分为预置仪表板和自定义仪表板两类。

预置仪表板由LangSmith为每个项目自动生成，提供即时关键视图：

• Traces | 追踪板块：展示追踪计数、延迟和错误率变化
• LLM调用 | 模型调用：LLM调用计数与平均延迟，仅包含run_type="llm"的记录
• 成本和Token | Cost & Tokens：按Token类型细分的总量与成本估算
• 工具 | Tools：按工具名称聚合统计
• 运行类型 | Run Types：根运行的直接子运行聚合
• 反馈分数 | Feedback Scores：均值/类别计数图表

自定义仪表板支持按具体分析目标创建专属图表集合，指定项目、过滤条件、指标、分组依据（如按tags.env分组）、时间窗口，最后保存为团队可复用的监控视图。

特别提醒：2025年10月LangChain推出了Insights Agent（洞察代理），它可以自动分析项目中Agent行为模式，从大规模生产Trace中挖掘常见Agent行为与失败模式。

3.4 分享、协作与人工标注链

分享（Share） ：Trace右上角点击分享生成Public Link或仅限组织access的分享链接。生成可嵌入到工单或调试报告的短链。

注解队列（Annotation Queues） ：将Runs聚合到指定队列，让团队成员集中评审标注每条数据是否符合预期。最新的成对注解队列还支持两个agent输出并排比较，人工选择胜者生成标注分数，辅助模型微调。

反馈（Feedback） ：可在UI内直接对Run或Trace添加评价，也可以收集最终用户的内联标注。典型用法：在内测版本中人工标注“正确/错误”，反馈数据驱动下一次实验优化。

四、原理底层剖析

4.1 Runs列表的数据填充与分页机制

当打开项目Runs页面时，前端向后端API发起/runs/query请求，携带project_id等参数。返回的Run对象符合LangSmith内部数据架构，其中inputs和outputs字段完整存储了链调用全量输入输出。服务端默认采用游标分页，前端无限滚动一步步加载下一页Run条目。

4.2 Filter Query Language的执行路径

用户在前端Filter输入框中写入筛选表达式，内部HTTP调用执行/runs/query，携带filter参数。后端请求查询引擎将filter语句转化为AST再执行SQL查询。这一模式在Python SDK的client.list_runs(filter='…')中完全一致，保证开发与分析的统一语法。

关键筛选参数和比较器（依据LangSmith API文档）：

• project_id / project_name：约束特定项目
• run_type：过滤特定类型（llm/chain/tool/retriever等）
• error：True/False筛选成功或失败请求
• is_root：True仅返回根Run（即独立Trace入口）
• gte/gt/lte/lt/eq/neq：对延迟、开始时间、结束时间、total_tokens等字段进行数值比较。
• has：用于检测tags或metadata的包含性条件
• search：字符串模糊匹配
• and / or：组合多条件
• query（实验性）：用户以自然语言描述查询条件，LangSmith会将其自动转换为filter表达式

这些表达式可在Runs UI和API调用之间无缝复用。

4.3 预置仪表板的指标聚合计算

预置仪表板每个图表的统计值都通过LangSmith后端聚合引擎动态计算。例如每小时请求错误率：SQL引擎扫描选定时间窗口，针对root runs计算error IS NOT NULL的比例，再按时序汇总给前端Highcharts渲染。分组的支持源于tags和metadata字段上建立关键词索引再进行分层汇总。

4.4 Annotation Queue的数据流转

注解队列本质上是存储Run ID引用的特殊数据库表。当项目内Runs匹配用户预设的过滤规则（如从线上选择错误样本）时系统自动将Run ID加入待审队列。评审员在前端打标打分后，Feedback API将该Run的对错信号存为结构化反馈对象，既可链式查询也可纳入实验评估汇总。

五、环境配置手把手实战

5.1 登录并导航LangSmith主页

你可以使用Google/GitHub或邮箱登录，进入LangSmith控制台后左侧边栏呈现Projects、Playground、Datasets & Experiments、Monitoring、Automations等核心模块。右上角个人图标可切换组织、查看用量文档；顶栏搜索框提供全局快速查找。

5.2 创建演示项目与示例数据

为了展示全功能操作，新建“demo-training”项目并注入足够多样本数据。使用之前学过的基础LangChain链快速打底：

# 文件名: prep_demo_runs.py
# 说明: 生成演示项目所需的多样本Run

import os
import random
from datetime import datetime, timedelta
from dotenv import load_dotenv
from langchain_openai import ChatOpenAI
from langchain_core.prompts import PromptTemplate
from langchain_core.runnables import RunnableConfig

load_dotenv()
os.environ["LANGCHAIN_PROJECT"] = "demo-training"

llm = ChatOpenAI(model="gpt-3.5-turbo")
prompt = PromptTemplate.from_template("用{emotion}的语气介绍{topic}")
chain = prompt | llm

topics = ["LangSmith", "AI Observability", "Trace Analysis"]
emotions = ["热情", "冷静", "幽默"]
users = ["user_alpha", "user_beta", "user_gamma"]

for i in range(120):
topic = random.choice(topics)
emotion = random.choice(emotions)
user = random.choice(users)
# 随机注入10%的错误场景
config = RunnableConfig(tags=[f"user:{user}", f"scenario:demo"],
metadata={"batch": "demo"})
try:
if random.random() < 0.1:
chain.invoke({"topic": topic, "emotion": emotion}, config=config)
else:
chain.invoke({"topic": topic, "emotion": emotion}, config=config)
except Exception as e:
print(f"模拟异常: {e}")

print("已向demo-training项目写入120条记录")

运行脚本产生多样化追踪数据，包括几种运行类型、标签维度和模拟错误率。

5.3 查看预置仪表板

在左侧导航栏打开Monitoring选项卡，选择演示项目“demo-training”。预置仪表板将自动加载Trace计数、Token统计、Tools和Run Types等预置图表。熟悉每个图表展示的指标，为自定义仪表板做好准备。

5.4 创建第一个Annotation Queue

点击左侧边栏“Automations”进入注解队列管理。点击“+ New Annotation Queue”命名为“Demo审核队列”。可选配置过滤器，让所有user:user_alpha标签的Run自动进入队列等待人工评审。

六、完整可运行代码案例

6.1 最佳筛选组合——使用前端filter框排查故障

假设团队成员反馈某个user:beta用户在业务高峰期反复收到错误响应。登录LangSmith选定项目，在Filter框直接输入：

and tags has "user:beta", error = true

立即筛选出该用户的错误Run。双击某一条Trace进入详情页查看具体异常原因：可能是超时或工具调用异常。

6.2 通过Python SDK运行复杂查询——找出比“基准链”更耗时的异常模式

生产环境经常需要从海量数据中自动圈定异常对象，生成监控报告。下列脚本利用list_runs配合filter参数进行跨维度组合分析：

# 文件名: advanced_filtering.py
# 说明: 使用SDK检索延迟异常的llm调用

from langsmith import Client
from datetime import datetime, timedelta

client = Client()

one_day_ago = datetime.now() – timedelta(days=1)
# 组合过滤器：llm类型 + 耗时长于5秒 + 无错误
filter_condition = (
'and(eq(run_type, "llm"), '
'gt(latency, 5.0), '
'eq(error, null))'
)

abnormal_llms = list(client.list_runs(
project_name="demo-training",
start_time=one_day_ago,
filter=filter_condition,
limit=300
))

print(f"发现{len(abnormal_llms)}个耗时长于5秒的LLM调用")

for run in abnormal_llms[:5]:
print(f"Run名:{run.name}, 延迟:{run.latency}秒, tags:{run.tags}")

这段查询会找出demo-training项目中llm类型且延迟超过5秒的正常完成请求。结合tags属性，可以排查哪些异常组合与高延迟有关。

6.3 使用Prebuilt仪表板监控Token成本趋势

进入预置仪表板成本和Token面板，过滤最近7天数据观察Prompt Tokens与Completion Tokens的比较，如发现prompt token近期消耗暴涨，可定位Prompt模板修改造成的长度增加。

6.4 Sharing URL快速传送异常Trace

在Traces视图选中一个错误Trace，点击右上角Share → “Copy link”，获得格式类似https://smith.langchain.com/public/<trace-id>/r的短链。将该链接附到工单或告警消息中，团队成员无须LangSmith权限即可一键查看完整调用树。

6.5 注解队列人工标注与多轮反馈闭环

在Annotation Queue中打开“待审核队列”，前端并排对比模型输入和输出数据，评审员可直接打标签。LangSmith最近引入的成对注解队列比较两个实验输出的代理回答质量，手动选择偏好版本，LangSmith自动将结果写为Comparison Feedback，进而和评估任务联动。

6.6 使用Insights Agent(洞察代理)自动发现Agent行为模式

确保已开启生产级Agent项目的充足采样。在Projects页面相关Agent项目下，点击Insights Agent入口（需要Pro或Enterprise套餐）。分析任务自动对过去数万条追踪记录做无监督聚类，发现高频Agent行为路径，如“大部分对话在3轮后切换工具”。按所提供的高频失败模式和建议，直接勾选为评估用例纳入数据集。

七、代码逐行详解

7.1 动态构建复杂filter组合查询

在advanced_filtering.py中：

filter_condition = (
'and(eq(run_type, "llm"), '
'gt(latency, 5.0), '
'eq(error, null))'
)

LangSmith Filter Language采用类似Lisp风格的前缀形式。and多个条件嵌套，每个条件的结构为comparator(field, value)。eq即Equal；gt(latency, 5.0)限制响应耗时大于5秒。error字段是可选字符串，eq(error, null)即代表执行成功。

7.2 使用client.list_runs实现分页和限流

list_runs方法返回的生成器支持分页，底层自动处理游标递延。加上limit=N会限制每次请求返回到客户端的数量。参数优先级run_ids指定单个ID时会忽略其他筛选参数。

abnormal_llms = list(client.list_runs(project_name="demo-training",
start_time=one_day_ago,
filter=filter_condition,
limit=300))

此写法会一次性请求300条结果，超过limit则由分页游标自动拉取。

7.3 Project ID与Project Name的选择

过滤器project_name语义直观；不过当企业应用重命名项目场景下，用project_id更稳妥。project_id可在项目Setting复制。如果API筛选需要，从代码获取当前project_id的方式：

proj = client.read_project(project_name="demo-training")
project_id = proj.id

八、常见坑点与避坑指南

8.1 Filter表达式大小写敏感与空格问题

LangSmith的Filter Language对标识符和比较器大小写敏感。有效比较器一定是eq, gt, has, search等小写组合。run_type字段是固定的字符串枚举（llm/chain/tool）。另外value值含有空格时必须用双引号包裹，否则解析异常。

8.2 误把Metadata当成Tag使用筛选效率低

Tag是扁平字符串列表，适合低基数的业务属性（如env、version）；Meta是高基数的任意键值对。当在filter中使用“has(metadata.key, value)”时后端查询开销较大。筛选规模较大生产数据时，优先将常用维度抽象为tag值。

8.3 预置仪表板数值延迟现象

预置仪表板默认采样频率约为分钟级，Traces实时写入后并非立刻呈现在仪表板最高点，可能延迟几十秒至数分钟。正确使用方式：先在Traces视图确认数据写入，再检查仪表板长时段趋势。

8.4 Annotation Queue自动分流规则过于宽广

创建队列时“Add to queue”过滤器设置得过于宽泛可能会导致海量级普通请求涌入队列，挤占人力资源。建议引入精确限定条件，如eq(error, true)或特定版本tag+采样条件。

8.5 Insights Agent需要足够的“冷数据”样本

AI行为模式需要足够多的样本才能聚类出显著模式。建议在流量上万条的项目上启用；少量Trace无法有效显示行为洞察。

九、企业级落地最佳实践

9.1 统一仪表板设计规范

为每个环境（dev/staging/prod）创建专属自定义仪表板，统一命名前缀（例如“核心错误监控”“成本环比Top 5”）。核心仪表板至少包含请求量趋势、P95/P99延迟、错误率、总Token消耗四个基础图表，供值班人员一眼判断系统健康度。

9.2 团队协作与权限分离

按角色定制仪表板视图：SRE监控时查看延迟和错误率指标；项目经理关注Token成本和用户满意度。Annotation Queue设置明确负责人和整改时限，每周评审标注数据，驱动Prompt迭代。

9.3 数据生命周期自动转储

利用SDK批量导出+LangSmith Bulk Data Export定期备份解析，尤其是在免费版配额限制下。推荐每小时增量拉取失败Trace或大额延迟Trace到数据湖，与内部告警系统联动。

9.4 Annotation Queue与Evals集成

高级流程：设置自动化规则将在生产环境中的低分请求自动推送到标注队列，人工修正后写回正确示例推送至数据集版本组，再触发自动评估任务跑回归测试，形成闭环。

9.5 嵌入团队文档自动报告

在Jenkins/Github Action中集成脚本，每日准时从LangSmith API拉取核心指标，自动更新到公司Confluence仪表板页面，确保上层管理者随时了解LLM应用运行状况。

十、本节知识点总结

十一、课后思考练习题

练习题1：理论理解

Q1.1：通过Monitors仪表板查看最近一周Trace总数上升但Token用量却轻微下降，推测从工程层面会有什么改动导致这种现象产生？

Q1.2：如果要按特定group_by逻辑在前端Dashboard刻画不同user_tier（免费版/高级版）的Prompt Tokens消耗对比，请给出两种可行的实现路径。

Q1.3：对比前端filter UI和后端SDK list_runs筛选方式，指出各自适用场景及组合方式。

练习题2：动手实践

2.1 在demo-training项目中练习filter框语法：查询retriever类型且tags包含version:v2，耗时超过5秒的Runs列表。

2.2 利用client.list_runs抓取过去48小时内运行中run_type为tool且失败的所有运行，通过tags元数据识别是哪个具体工具引起的错误频率最高。

2.3 启用Insights Agent（若拥有Pro套餐），撰写一份当前演示项目Agent行为模式报告摘要。

练习题3：场景设计

3.1 公司金融客服Agent上线一周后用户投诉响应质量下降。你如何组合LangSmith面板功能快速定位差异区域？

3.2 针对Demo项目设计专用Annotation Queue Workflow，每月收集高质量“真实标注数据集”，并推送给LLM评估器做反馈训练。

3.3 周末轮到时你发现自定义仪表板中延迟P99指标突然恶化。结合Runs视图、共享链接和Annotation Queue设计一套完整的响应-诊断-改进流程。

下节课预告：

第10节课将着力学习LangSmith进阶的标签元数据管理，掌握业务维度归类和日志精细化分发能力，为大规模工程化应用构建全链路观测生态。

下一节课见！

🔗《20节课 LangSmith 从入门到精通》系列课程导航

去订阅

🌟 感谢您耐心阅读到这里！ 💡 如果本文对您有所启发欢迎： 👍 点赞📌 收藏 📤 分享给更多需要的伙伴。 🗣️ 期待在评论区看到您的想法, 共同进步。 🔔 关注我，持续获取更多干货内容～ 🤗 我们下篇文章见～