1. 当 Agent 跑出几千条 Trace 之后人眼已经不够用了做 Agent 开发的朋友大概率都经历过这个阶段刚上线时每天几十个 Session打开 Trace 面板一条条翻还能靠直觉判断哪里出了问题。等到用户量上来一天几千甚至几万条 Trace 涌进来事情就完全变了——你盯着满屏的 span 列表根本不知道从哪看起更别提回答我的 Agent 到底表现怎么样这种问题了。这就是智能聚类要解决的核心痛点。它做的事情说白了就一句话把海量 Trace 按照 Agent 的行为模式自动分组让你从逐条看变成按类看。同一类的 Trace 往往共享相似的执行路径、相似的失败原因、相似的性能瓶颈聚类之后你只需要看几十个簇就能覆盖几万条 Trace 的信息量。这篇文章适合三类人一是正在做 Agent 可观测性建设的大模型开发工程师二是手上有 Trace 数据但不知道怎么挖掘价值的团队三是对 Embedding、Session 管理、Agent 架构有一定了解想把它们串起来解决实际问题的从业者。我会从 Trace 的数据结构讲起一路讲到 Embedding 怎么选、聚类怎么调、结果怎么落地中间穿插我自己踩过的坑。先明确一个前提这里说的 Trace指的是 Agent 执行过程中产生的调用链数据包含 Session 维度、Span 维度、工具调用、模型请求、耗时、状态等字段。它和传统微服务的 Trace 在结构上相似但语义复杂得多——因为 Agent 的行为是半开放的同一个任务可能走完全不同的路径这让聚类变得既有挑战也有价值。2. Trace 到底长什么样先搞清楚你要聚的是什么2.1 从 Session 到 Span 的层级结构很多人一上来就想做聚类结果连自己的数据长什么样都没理清。我建议先把 Trace 的层级关系画出来。一个典型的 Agent Trace 结构是这样的Session一次完整的用户会话可能包含多轮对话Turn一轮用户输入到 Agent 给出回复SpanTurn 内部的原子操作比如一次 LLM 调用、一次工具调用、一次检索EventSpan 内部的细粒度事件比如 token 流式输出、工具参数解析这个层级决定了你的聚类粒度。聚 Session 能看出用户都在问什么类型的问题聚 Turn 能看出Agent 的响应模式聚 Span 能看出哪个环节最容易出问题。三者用途完全不同别混着做。我见过一个团队把所有 Span 拉平了做聚类结果簇里全是LLM 调用这种无意义的分组。原因很简单Span 类型本身就那么几种聚类算法再强也变不出花来。聚类的价值在于发现意料之外的分组而不是复述你已经知道的分类。2.2 哪些字段真正有区分度Trace 字段很多但不是每个都适合喂给聚类。我按经验把字段分成三类字段类型举例是否适合聚类原因结构特征span 数量、工具调用次数、嵌套深度适合数值化直接区分度高语义特征用户输入、工具参数、模型输出适合需 Embedding信息量大但需转换状态特征成功/失败、错误码、耗时适合做后处理更适合作为簇的标签而非聚类输入元信息session_id、时间戳、用户 ID不适合无区分意义会引入噪声关键点在于结构特征和语义特征要分开处理最后再融合。结构特征直接归一化后拼成向量语义特征走 Embedding 模型转成稠密向量两者拼接或者分别聚类后再做交叉分析。我试过直接混在一起喂给 KMeans效果很差因为两类特征的量纲和分布差异太大。2.3 一个容易被忽略的坑Trace 采样生产环境的 Trace 量级往往大到没法全量聚类。这时候采样策略就很重要。常见的做法是随机采样但我要提醒一句随机采样会稀释掉长尾行为而长尾恰恰是聚类最该发现的东西。我的做法是分层采样正常 Trace 按 10% 采样失败 Trace 全量保留耗时超过 P99 的 Trace 全量保留。这样既控制了数据量又保证了异常行为不被漏掉。这个策略在多个项目里验证过聚类结果的惊喜度明显提升。3. 把 Trace 变成向量Embedding 选型与特征工程3.1 语义部分Embedding 模型怎么选Trace 里的语义内容主要是用户输入、工具调用参数、模型输出文本。这部分需要 Embedding 模型来转成向量。选型时我关注三个维度中文支持如果你的用户主要说中文别用纯英文模型效果差得不是一点半点维度与性能768 维和 1536 维在聚类效果上差异没有想象中大但计算成本差一倍领域适配通用模型对工具调用参数这类结构化文本的编码效果一般有条件的话做点微调我实测下来对于 Agent Trace 这种混合了自然语言和结构化文本的场景中等维度的多语言模型性价比最高。太小的模型语义区分度不够太大的模型在几万条数据上跑一次要等很久迭代效率低。这里有个实操细节Embedding 之前一定要做文本清洗。Trace 里的文本经常夹杂大量特殊字符、JSON 片段、重复的模板话术。不清洗直接编码向量里全是噪声。我的清洗流程是去特殊字符 → 截断超长文本保留头尾→ 去除高频模板句 → 统一大小写。3.2 结构部分数值特征怎么归一化结构特征包括 span 数量、工具调用次数、嵌套深度、各类型 span 占比等。这些数值直接拼进向量有两个问题量纲不一致、分布偏斜。我的处理方式是对计数类特征做 log 变换缓解长尾分布对占比类特征保持原值本身就在 0-1 之间对所有特征做标准化减均值除标准差import numpy as np def normalize_structural_features(features): # features: dict of feature_name - value transformed {} for name, value in features.items(): if name.endswith(_count): transformed[name] np.log1p(value) # log 变换 else: transformed[name] value # 标准化 arr np.array(list(transformed.values())) arr (arr - arr.mean()) / (arr.std() 1e-8) return arr这段代码看着简单但 log 变换那一步很关键。我一开始没做结果 span 数量这个特征完全主导了聚类结果所有簇都是按长 Trace和短 Trace分的毫无意义。3.3 融合策略拼接、加权还是分别聚类语义向量和结构向量怎么合三种方案我都试过直接拼接简单但语义向量维度远大于结构向量结构特征容易被淹没加权拼接给结构特征乘一个权重系数需要调参分别聚类再交叉先各自聚类再看两个聚类结果的交叉分布我的推荐是加权拼接权重通过实验确定。经验值是语义向量权重 0.7结构向量权重 0.3但这个比例因场景而异。如果你的 Agent 行为差异主要体现在执行路径上比如工具调用序列结构权重可以提到 0.5。提示融合之前务必确认两类向量的维度。我踩过一次坑语义向量是 768 维结构向量是 12 维拼接后 780 维结果聚类时结构特征几乎不起作用。后来把结构向量复制扩展到 100 维左右效果才正常。4. 聚类算法落地从 KMeans 到 HDBSCAN 的取舍4.1 为什么我不推荐一上来就用 KMeansKMeans 是最容易上手的聚类算法但它有两个硬伤需要预先指定簇数量 K且假设簇是球形的。Agent Trace 的分布往往是不规则的簇的形状千奇百怪KMeans 强行切出来的结果经常把明显不同的行为混在一起。我早期项目用 KMeans调 K 值调到怀疑人生。K10 时太粗K50 时太碎而且每次重新跑结果都不一样随机初始化导致。后来换成 HDBSCAN问题迎刃而解。4.2 HDBSCAN 在 Trace 聚类中的实际表现HDBSCAN 的优势在于不需要指定簇数量、能发现任意形状的簇、能识别噪声点。这三点完美契合 Trace 聚类的需求。import hdbscan from sklearn.preprocessing import StandardScaler # 假设 vectors 是融合后的向量矩阵 scaler StandardScaler() vectors_scaled scaler.fit_transform(vectors) clusterer hdbscan.HDBSCAN( min_cluster_size15, # 最小簇大小 min_samples5, # 核心点邻域样本数 metriceuclidean, cluster_selection_methodeom ) labels clusterer.fit_predict(vectors_scaled)参数怎么调min_cluster_size是最关键的。设太小簇碎得没法看设太大很多行为被归为噪声。我的经验是先按数据量的 0.5% 到 1% 设定再根据结果微调。比如 2 万条 Tracemin_cluster_size 从 100 开始试。min_samples影响噪声点的判定。设大一点噪声多但簇更紧凑设小一点更多点被纳入簇。我一般设 5-10 之间。4.3 聚类效果怎么评估别只看轮廓系数轮廓系数是常用指标但在 Trace 聚类场景下参考价值有限因为它假设簇是凸的。我更看重三个实际指标簇的稳定性换一批数据重新聚类簇的分布是否一致簇的可解释性随机抽几条簇内 Trace能不能用一句话概括这簇在干什么噪声比例噪声点占比超过 30% 说明参数有问题其中可解释性最重要。聚类不是为了数学上的漂亮是为了让你理解 Agent 行为。如果一簇 Trace 你看了半天说不出它在干什么那这个簇就是失败的。我通常会做一个簇画像对每个簇统计其高频工具调用、平均耗时、失败率、典型用户输入。这个画像直接决定了这个簇有没有业务价值。簇 ID样本数高频工具平均耗时失败率行为概括03200search, summarize2.3s2%标准检索问答1890code_exec, debug8.7s15%代码执行类任务2450-0.8s45%快速失败参数错误32100search, calc, format4.1s5%多工具组合任务这张表一出来产品和技术都能立刻看懂 Agent 在干什么、哪里有问题。簇 2 失败率 45%点进去一看全是参数校验失败这就是明确的优化点。5. 从聚类结果到可执行洞察几个真实场景5.1 场景一发现隐形的失败模式有一次聚类跑完发现一个簇的失败率异常高但错误码都是成功。点进去看 Trace 才发现Agent 调用了工具工具返回了空结果Agent 没报错但也没给出有效回答。这种静默失败在逐条看 Trace 时极难发现聚类把它聚成了一簇一眼就暴露了。修复方式是在工具调用后加一个结果有效性校验空结果触发重试或降级。这个改动上线后该簇的有效回答率从 55% 提到了 92%。5.2 场景二Session 级别的行为漂移监控把聚类按天跑观察簇的分布变化。正常情况下各簇占比应该稳定。如果某天某个簇突然膨胀说明用户行为或 Agent 行为发生了漂移。我遇到过一次某个多轮追问簇的占比从 8% 涨到 25%。排查发现是模型更新后Agent 对某类问题的首次回答质量下降导致用户频繁追问。这个信号在传统监控指标成功率、耗时上完全看不出来但聚类捕捉到了。5.3 场景三为 Agent 优化提供优先级聚类结果天然是一个优先级排序工具。簇的大小代表影响面簇的失败率代表严重程度两者一乘就是优化优先级。我一般会输出一个优化看板按影响面 × 严重度排序列出 Top 10 需要处理的簇。团队每周过一遍逐个击破。这比拍脑袋决定优化什么靠谱得多。注意聚类结果不是一成不变的。Agent 每次迭代、模型每次更新都可能改变行为分布。建议把聚类做成定期任务比如每天一次持续跟踪。6. 工程化落地性能、成本与常见坑6.1 几万条 Trace 的聚类要跑多久这是大家最关心的问题。我实测的数据2 万条 TraceEmbedding 阶段调用模型 API大概 3-5 分钟聚类阶段HDBSCAN大概 1-2 分钟。总体 10 分钟内能跑完。优化点主要在 Embedding 阶段。两个方向一是批量调用一次传多条文本二是缓存相同文本不重复编码。Trace 里重复文本比例不低尤其是模板化的工具调用缓存能省 30% 以上的时间。6.2 成本控制Embedding 调用是主要开销如果按 API 计费2 万条 Trace 的 Embedding 成本不算低。控制成本的手段预过滤明显无意义的 Trace比如空输入、纯报错直接跳过降采样如前所述分层采样本地模型数据量大且稳定的话部署本地 Embedding 模型更划算我一般建议先用 API 跑通流程验证价值后再考虑本地化。6.3 我踩过的三个坑坑一把 session_id 当特征。早期我把 session_id 的哈希值当特征喂进去结果聚类完全乱套。session_id 是标识符不是特征没有任何语义。坑二忽略时间维度。Trace 是有时序的同一个 Session 内的 Span 顺序很重要。我一开始把 Span 当无序集合处理丢失了顺序信息。后来加入了工具调用序列作为特征聚类效果明显提升。坑三聚类完就完事。聚类只是手段不是目的。我见过团队跑完聚类出了个报告就搁置了没有任何后续动作。正确的做法是把聚类结果接入日常流程告警、看板、优化排期让它真正驱动决策。6.4 可视化让非技术同学也能看懂聚类结果最终要给人看。我常用的可视化方式簇分布饼图各簇占比看整体行为构成簇演化折线图各簇占比随时间变化看漂移簇画像卡片每个簇一张卡片包含样本数、失败率、典型 Trace 示例工具上Python 生态里 UMAP 降维 散点图是最直观的。把高维向量降到 2D不同簇用不同颜色一眼就能看出分群效果。但要注意UMAP 的降维结果只用于可视化不要用它来做聚类会丢失信息。import umap import matplotlib.pyplot as plt reducer umap.UMAP(n_neighbors15, min_dist0.1, n_components2) embedding_2d reducer.fit_transform(vectors_scaled) plt.scatter(embedding_2d[:, 0], embedding_2d[:, 1], clabels, cmapSpectral, s5) plt.colorbar() plt.title(Trace Clusters Visualization) plt.show()这张图放在周报里比任何文字描述都有说服力。7. 关于这套方法我自己的几点体会做 Agent 可观测性这几年我越来越觉得聚类不是一个技术问题而是一个认知问题。技术上的实现Embedding、HDBSCAN、可视化都有成熟方案真正的难点在于你得先想清楚要回答什么问题再去设计聚类方案。如果你的问题是Agent 哪里容易失败那就该聚失败 Trace重点看错误模式和上下文如果你的问题是用户都在用 Agent 干什么那就该聚 Session重点看意图分布如果你的问题是Agent 的性能瓶颈在哪那就该聚 Span重点看耗时分布。问题不同方案完全不同。另外一点体会是别追求一次做到完美。我第一个版本的聚类方案很粗糙特征就选了五六个算法用的还是 KMeans。但它已经帮我发现了一个之前完全没注意到的问题簇。先跑起来再迭代比憋大招强得多。最后分享一个实用技巧聚类结果出来后别急着看统计数字先随机抽 10 条 Trace 逐条读一遍。这 10 条读下来你对这簇的理解会比任何统计指标都深刻。统计告诉你是什么逐条读告诉你为什么。两者结合才是完整的洞察。