SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场mlflow-to-atif

mlflow-to-atif

数据与分析

查看项目

更新于 10-17 10:28

技能介绍

用途

将 MLflow 追踪数据转换为规范化的 ATIF 轨迹。转换不经过 Intake，每条 MLflow 追踪生成一个仅所有者可访问的 .atif.json 文件，脚本只打印不含内容的摘要。可使用 NeMo Compass 的 scripts/load_mlflow_trace.py 获取共享的规范化 span 证据，但其输出不是 ATIF，也不替代本转换及下游校验约定。

数据保护

除非用户另有证明，源文件和转换文件均视为受限数据。不得打印追踪负载、放入 Git，或写入公开/共享输出目录。脚本将输出目录设为 0700、轨迹文件设为 0600。

输入选择

导出数据支持单个 Trace.to_dict() 值、其 JSON 数组，或 {"traces": [...]} 结构：

python scripts/convert_mlflow_to_atif.py \
  --input <private-export.json> \
  --output-dir <private-atif-dir> \
  --agent-name <stable-agent-name> \
  --agent-version <agent-version>

实时 MLflow 存储需显式指定实验和有界时间范围，并使用已装有 MLflow 的 Python 环境（不要代为安装或改动认证）：

python scripts/convert_mlflow_to_atif.py \
  --tracking-uri <mlflow-uri> \
  --experiment-id <experiment-id> \
  --since <inclusive-ISO-8601-time> \
  --until <exclusive-ISO-8601-time> \
  --output-dir <private-atif-dir> \
  --agent-name <stable-agent-name> \
  --agent-version <agent-version>

实时转换要求远程服务器使用 HTTPS，仅回环主机允许 HTTP，拒绝禁用 TLS 校验，不跟随 HTTP 重定向。使用分页的 MlflowClient.search_traces() API，兼容早于 fluent API return_type="list" 的 MLflow 版本。除非用户要求替换同一次转换并提供 --overwrite，否则拒绝覆盖已有轨迹。

版本与校验

输出 ATIF v1.7；若已安装 Harbor，可加 --validate-with-harbor。ATIF v1.8 新增音频内容部分，但本转换器仅投影文本和 JSON 数据，v1.8 未带来所需表示，故不将 v1.7 输出标记为 v1.8；待转换器与下游同时支持 v1.8 时再一并迁移。

转换约定

从根 span 或追踪输入恢复人类指令，不存在时直接失败而非虚构指令。LLM span 输出为 agent 步骤，保留 MLflow 记录的模型与 token 指标。工具、检索器、嵌入、重排器和防护栏 span 输出为确定性 agent 步骤，配对的工具调用与观察。按时间戳顺序展平 span 树，同时以命名空间 mlflow 元数据保留原生 ID、父 ID、属性、事件、状态和评估。当事件父 span 边界证明其名义 time_unix_nano 实为微秒时，规范化为纳秒并记录于 extra.mlflow_to_atif.normalization_codes。拒绝未解析父级、循环及 next_page_token 非空的导出分页；需先收集完整导出。在每条结果的 extra.mlflow.output_state 中区分缺失、显式 null 与已填充的工具输出。所有已知有损投影记录于 extra.mlflow_to_atif.loss_codes。转换后向下游消费者提供一份输出文件作为规范 ATIF，受限原始文件与受限转换输出分开保存。

前置条件

离线转换需 Python 3.11+ 和完整的本地 Trace.to_dict() 导出；实时转换另需现有环境中的 MLflow、所选存储的配置访问、实验 ID 和明确时间边界；可选 Harbor 校验需已安装的 Harbor 环境。需选择私有输出目录及稳定的 agent 名称与版本。

可用脚本

在本技能目录运行，或使用脚本绝对安装路径，并使用为所选输入模式准备的 Python 环境。

  • scripts/load_mlflow_trace.py：通过固定版本 NeMo Compass 加载完整导出，不生成 ATIF；参数 --input --max-traces --output-dir。
  • scripts/convert_mlflow_to_atif.py：为每条选定 MLflow 追踪导出一份 ATIF 轨迹；参数为 --input 或实时存储标志，以及 --output-dir --agent-name --agent-version。

限制

转换器将文本和 JSON 投影到 ATIF v1.7 并保留已知损失；无法恢复未记录的人类输入、工具输出或多媒体。转换不证明任务正确性或覆盖度。实时读取限定于所给实验和时间范围，且不改变认证。

故障排查

缺少人类指令：获取完整导出，切勿虚构输入文本。next_page_token 非空：先收集剩余导出分页再转换。未解析父级或循环：获取一致的追踪导出，不要删除 span 使其可解析。TLS 或重定向被拒：使用启用校验的授权 HTTPS 端点，HTTP 仅支持回环。已有输出：使用新目录，除非明确要求替换同一次转换，此时才用 --overwrite。