★ FEATURED ARTICLE 【免费下载链接】Tracely-aiTrace-native CI/CD for AI agents: grade production traces, cluster failures, freeze them into replayable regression tests, and block PRs that regress. Self-hostable.项目地址https://gitcode.com/gh_mirrors/tr/Tracely-ai点击查看免费下载Tracely 是一款 Trace 原生的 AI Agent 可观测性与 CI/CD 工具。它的**失败聚类Failure Clustering**能力可以把生产环境中同因失败的 31 条 Trace 自动收敛成 1 个可追踪的故障 Issue自动归组、LLM 根因分析、版本归因还能一键把 Issue 冻结成可重放的回归测试从源头拦住下一次回归。为什么逐条看 Trace 定位不了 AI Agent 故障 一次部署之后Trace 列表里躺着 31 条失败记录。逐条打开你会发现它们其实死在同一个错误上——ValueError、工具超时、鉴权失败……但问题在于错误消息里的ID、订单号、时间戳各不相同两条同因失败看起来完全是两条不同的报错31 次失败可能来自200 次调用中的不同请求人眼无法快速确认它们是不是同一类问题就算确认了你还得回答什么时候开始出现的哪个版本引入的该修什么Tracely 的失败聚类把按失败种类分诊变成了自动流程同因失败的 Trace 自动归入同一个Failure cluster失败簇每个簇就是一个带计数、时间线、版本归因与修复建议的故障 issue而不是 31 个待办。失败聚类如何工作两阶段机制 第一阶段摄入时的结构签名秒级归组零模型成本一条 Trace 一旦被评估器判为失败Tracely 立刻计算它的结构签名signature取出失败的评估器集合错误文本掩码掉易变部分UUID/十六进制 ID →id、数字 →n、引号字符串 →*再压缩空白取sha256 前 16 位作为稳定的 cluster key。于是两条 Trace 抛出了同一个异常——哪怕消息里的订单号完全不同——也会在几秒内落入同一个簇全程不需要任何模型调用。签名里还内置了防碎片规则掩码后文本几乎一致token 重叠度 ≥ 0.9就判定为同一 issue 合并只有失败的评估器集合完全不同才会把措辞相似的失败保留成两个簇。这套签名逻辑实现在 signature.py。第二阶段按需语义聚类Analyze failures 按钮结构签名只能合并长得一样的失败。点一下页面上的⚡ Analyalyze failuresTracely 会做一次完整的语义重建每条失败 Trace 被描述成机制性文本——问了什么、哪个工具坏了、答案哪里跑偏文本转成embedding 向量用HDBSCAN做密度聚类数据量大时先UMAP 降维再聚类小数据集则直接按余弦距离聚类避免高维空间里出现幽灵簇一个 LLM 分析师为每个簇写出 issue标题、机制分析Analysis、修复建议Proposed fix甚至给出一个能继续拦住这类失败的建议评估器Suggested evaluator再来一轮合并与拆分真正是一个问题的 issue 合并藏着一个簇里的两个问题拆开。上一轮的 Promote / Ignore 状态会自动继承不会让你重复确认。聚类引擎的算法选择逻辑见 clustering.py完整流水线embedding → 聚类 → LLM 分析 → issue 整合在 failure_intel_service.py。 第二阶段依赖工作区的OpenRouter keyembedding LLM 分析都走它没有配置时按钮置灰你依然保留第一阶段的结构性簇。一个 Issue 长什么样从计数到版本归因 看一个真实形态的例子13 条 Trace 抛出了同样的ValueError: kaboom全部被收进一个 cluster。点进去每个区块都在回答一个分诊问题区块回答的问题Occurrences它何时发生尖峰 某次部署引入的平线 一直如此的老毛病By agent version哪个版本引入的见下方版本归因规则Analysis / Proposed fix机制是什么、该改什么——LLM 写好的成文分析Suggested evaluator一条能继续拦住这类失败的草稿评估器点Create evaluator直接预填创建表单Signature那个掩码后的结构指纹可复制到检索/告警里用Member traces簇里每一条 Trace标出REPRESENTATIVE代表样本点击直达详情版本归因introduced in的判定很克制只有当更早的版本已经服务过足够多的干净运行默认 20 条以上且一条都没落进这个簇时第一个出问题的版本才会被点名——v2 跑了 340 次零失败v3 跑出 41 次失败于是结论是introduced in v3。从第一个版本就存在的失败永远不会被冤枉到某一个版本头上规则实现见 versions.py。页面右上角只有两个动作Promote cluster to regression test—— 把失败变成永远会跑的测试Ignore—— 已知限制、噪音、第三方故障把 issue 藏起来但不删 Trace。从故障 Issue 到 CI 门禁一键晋升回归测试 点Promote cluster to regression test后Tracely 会从簇中冻结一条代表性失败 Trace生成一个回归 case。晋升时自动捕获四样东西原始输入——用户请求原样保存附带摘要保证同一输入不会被重复晋升Fixture bundle——该运行每一次工具调用、模型调用的参数与输出存入对象存储让 CI 里的重放工具走录制、代码走真实参考轨迹——失败运行实际走过的有序步骤Fail-to-pass 契约——候选运行必须满足的断言无运行错误、必须真正执行哪些工具、工具序列是否必须匹配……契约会先在源 Trace 上自证那条失败运行必须失败自己的 case。如果原失败还能通过说明这个 case 没抓住 bugTracely 直接拒绝创建。晋升后的 case 进入该 agent 的 CI gate之后每个 PR 都会重放它——bug 还在就红修好就绿。至此31 条 Trace 暴露的故障有了完整可追踪的闭环失败 → 自动聚类成 issue → 升成回归 case → CI 门禁拦住回归。让新失败模式主动找你配置告警 一个簇是全新的恰恰是最值得打断人的信号——说明一种没人分诊过的失败模式刚出现在生产。在Alerts里配一条New failure mode触发器任何新失败簇出现时立即推送到 Slack、邮件或 Webhook。之后你打开 Failure clusters 页面时已经是带着答案来的。模块路径速查 关注点模块结构签名掩码、token 相似度、cluster keybackend/tracely/domain/failure/signature.pyUMAP HDBSCAN 聚类引擎backend/tracely/domain/failure/clustering.py版本归因introduced inbackend/tracely/domain/failure/versions.py语义聚类 LLM 分析流水线backend/tracely/services/failure_intel_service.py集群 API列表/详情/rebuild/promote/ignorebackend/tracely/api/routers/clusters.py晋升回归 case 的业务逻辑backend/tracely/services/regression_service.py产品设计文档失败智能全景design/part2-tracely/07-failure-intelligence.md常见问题 FAQ ❓Q1失败聚类需要配置模型吗第一阶段摄入时的结构签名不需要任何模型失败发生几秒后就能看到归组。第二阶段语义聚类Analyze failures需要工作区配置 OpenRouter key没配置时按钮置灰你保留结构簇即可。Q2为什么同一个失败会出现在两个簇里结构签名阶段措辞差异过大的 LLM judge 评语可能暂时拆出多个簇点一次 Analyze failures 做语义重建后第二轮合并/拆分会把它们整合成一个 issue。Q3修改了评估器阈值、advisory后簇会跟着变吗会。Cluster 本质上是 score 的视图——改完评估器后重跑聚类下一轮结果自动反映变化没有需要同步的第二份 issue 列表。Q4大量只出现一两次的噪音簇怎么处理用列表页的Min occurrences过滤器比如设为 3只保留出现过至少 3 次的 issue也可以对单个 issue 点Ignore它从 open 计数中消失但 Trace 不会被删除。Q5版本归因显示不出来怎么办需要在tracely.agent(...)里带上version参数git sha 也可以且更早版本要有足够的干净运行默认 20 条Tracely 才会给出introduced in vX的结论避免误导二分排查。Q6Issue 可以修复掉吗Promote 成回归 case、修复部署、门禁持续绿灯后就可以 Ignore 这个 issue——失败 Trace 依然可查只是不再占用分诊注意力。总结Tracely 失败聚类的精髓在两层机制 两个动作两层机制摄入时的廉价结构签名负责秒级归组按需的 embedding HDBSCAN LLM 分析负责深度整合与成文结论两个动作一个 Issue 要么Promote成永远重放的回归测试要么Ignore掉新失败模式还能直接触发告警。下次生产环境再出现 31 条失败 Trace打开 Failure clusters 页面——你看到的应该只是 1 个带时间线、带版本归因、带修复建议的故障 Issue和一个随时可以拦下它复发的回归测试。赞分享【免费下载链接】Tracely-aiTrace-native CI/CD for AI agents: grade production traces, cluster failures, freeze them into replayable regression tests, and block PRs that regress. Self-hostable.项目地址https://gitcode.com/gh_mirrors/tr/Tracely-ai点击查看免费下载相关推荐Tracely失败聚类如何把31条崩溃运行归成1个问题并自动建议检测器Tracely失败聚类如何把31条崩溃运行归成1个问题并自动建议检测器 Tracely 是一款面向 AI Agent 的 Trace 原生 CI/CD 工具Jellyfin直播电视播放故障终极排查指南从点击到失败的完整技术追踪Jellyfin直播电视播放故障终极排查指南从点击到失败的完整技术追踪 Jellyfin作为一款强大的开源媒体服务器其直播电视功能为用户提供了丰富的流媒体体音视频前端Colota 故障排查完全手册后台追踪失效、同步失败的 12 个快速解决方案Colota 故障排查完全手册后台追踪失效、同步失败的 12 个快速解决方案 Colota 是一款开源自托管的 Android GPS 位置追踪 App它把上一篇为什么InternVideo2-Stage2_6B要蒸馏CLIP?揭秘clip_decoder特征对齐机制下一篇两种稀疏MoE的巅峰对决24B-A2B对阵Gemma 4 26B-A4B创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
