如何用 Witty-Insight 导出标准化 AI 轨迹数据？ATIF 完整指南

如何用 Witty-Insight 导出标准化 AI 轨迹数据ATIF 完整指南【免费下载链接】witty-insightThe witty-insight is an eBPF-based observability framework for tracing agent execution pipelines.项目地址: https://gitcode.com/openeuler/witty-insight前往项目官网免费下载https://ar.openeuler.org/ar/想知道 AI 代理在一次任务里到底干了什么Witty-Insight 可以给你答案。这个基于 eBPF 的可观测性框架能完整跟踪代理执行管道并把结果导出为标准化 ATIF 格式的 AI 轨迹数据。本文讲清 AI 轨迹导出的完整流程怎么导出、怎么读。先打开一份 Witty-Insight 导出的轨迹文档看看在学导出之前先看看成品长什么样。下面是一份 ATIF v1.6 轨迹文档的最小示例{ schema_version: ATIF-v1.6, session_id: trace-001, agent: { name: my-agent, version: 1.0, model_name: qwen-max }, steps: [ /* …共 6 步 */ ], final_metrics: { total_prompt_tokens: 1200, total_completion_tokens: 180, total_steps: 6 } }你可以把它理解成 AI 代理的“飞行黑匣子”✈️任务开始时的系统提示、用户问了什么、中途用了哪些工具、每一步花了多少令牌全都写在这一份文档里。顶层五个字段各司其职字段含义说明schema_version格式版本表明文档遵循的 ATIF 版本此处为 ATIF-v1.6session_id唯一编号标识整个代理运行agent代理配置记录代理系统是谁名称、版本、默认 LLM 模型等steps交互历史所有对话与响应的完整记录按先后顺序排列final_metrics汇总指标整条轨迹的令牌总账三种粒度导出 AI 轨迹数据的完整步骤Witty-Insight 内置了三个导出端点粒度各不相同按你想看多大范围来选粒度端点拿到的内容单条 traceGET /api/export/atif/trace/{trace_id}一次用户查询的完整调用链完整会话GET /api/export/atif/session/{session_id}该会话下的所有 trace指定对话GET /api/export/atif/conversation/{conversation_id}该对话内的全部 LLM 调用三者的区别本质是“取多少数据”trace最细对应一次用户查询包含这次查询背后发生的所有 LLM 调用。session更大一号里面装着多条 trace适合导出跑了很久的一整段任务。conversation按对话组织把某个对话内的所有 LLM 调用都收进来。请求方式都一样直接访问对应端点。返回的就已经是 ATIF v1.6 格式的完整轨迹文档拿到即用不用再加工。读懂 steps 与 final_metrics 字段steps 是整份文档的核心数组里每个元素都是一次交互的快照。看的时候先盯 source 字段——它告诉你这句话是谁说的system 代表系统提示user 代表用户消息agent 代表代理自己的响应。字段含义说明step_id步骤序号从 1 开始递增timestamp发生时间ISO 8601 格式source说话方system、user、agent 三者之一message消息文本这一步的实际内容model_name所用模型仅 agent 步骤携带reasoning_content内部推理仅 agent 步骤携带tool_calls工具调用AtifToolCall 列表observation环境反馈工具执行后的返回结果metrics步骤指标这一步的令牌统计其中 tool_calls 和 observation 是一对搭档。代理要调工具时tool_calls 会记下这次调用tool_call_id 是调用的唯一编号function_name 是函数名arguments 是传入的参数。工具跑完后observation.results 给出执行结果每条结果的 source_call_id 指回对应的 tool_call_idcontent 则是具体返回内容。靠着这个编号对应关系哪次调用产出了哪个结果一眼就能对上。指标字段分两级放一张表里对照着看字段含义说明prompt_tokens输入令牌本步发给模型的令牌数completion_tokens输出令牌本步模型生成的令牌数cached_tokens缓存命中输入令牌中命中缓存的部分total_prompt_tokens输入令牌合计整条轨迹的 prompt_tokens 之和total_completion_tokens输出令牌合计整条轨迹的 completion_tokens 之和total_cached_tokens缓存命中合计整条轨迹的 cached_tokens 之和total_steps步骤总数文档里 steps 的个数前三项属于 AtifStepMetrics每个步骤各有一份后四项属于 AtifFinalMetrics就是根文档里的 final_metrics。Witty-Insight 如何把采集记录变成 ATIF 文档这份轨迹不是手工写的而是 ATIF 模块自动转换出来的。Witty-Insight 先用 eBPF 采集到 LLM 调用记录存进本地 SQLite 数据库调用导出端点时转换器把相应记录取出重建成步骤序列——第一次调用里的系统提示与用户请求会拆成独立的 system、user 步骤每次 LLM 调用变成一个 agent 步骤工具调用的结果则跨相邻调用按编号关联起来。实现细节可以对照源码看数据结构定义在 src/atif/schema.rs转换逻辑在 src/atif/converter.rs完整实现集中在 src/atif/ 目录。导出的轨迹数据还能做什么拿到标准化轨迹数据至少有四件事值得做行为分析按步骤回放代理的决策过程看它从哪一步开始跑偏。性能优化翻 final_metrics 里的令牌统计找出输入过大的步骤再考虑精简提示或提升缓存命中。跨系统互通ATIF 是标准化交换格式轨迹数据可以在不同代理系统之间共享、对比和统一分析。调试定位任务失败时直接检查工具调用的 arguments 和 observation 结果快速定位问题环节。轨迹数据就是 AI 代理的黑匣子。Witty-Insight 的 eBPF 采集加上 ATIF 导出让你用一个请求就能把黑匣子取出来把代理内部的“玄学”变成可查、可算、可交接的普通数据。【免费下载链接】witty-insightThe witty-insight is an eBPF-based observability framework for tracing agent execution pipelines.项目地址: https://gitcode.com/openeuler/witty-insight创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考