跳到主要内容

归档追踪

追踪归档（Trace archival）功能允许 MLflow 将旧的追踪跨度（trace span）负载从 SQL 追踪存储中移出，转存到配置的归档制品位置，同时确保这些追踪在 UI 和 API 中依然可读。要在自托管服务器上启用追踪归档，请参阅 MLflow 追踪服务器。

注意

追踪归档与删除追踪不同，也与将模型版本移动到模型注册表的 Archived（已归档）阶段不同。

追踪归档的作用​

追踪归档后，MLflow 会将追踪元数据和归档指针保留在追踪存储中；当您打开该追踪时，系统会从归档存储中读取跨度负载。

这有助于减少 SQL 后端中存储的追踪内容总量，同时为调试、审计和评估工作流保留对旧追踪的访问权限。

注意

归档后的重要限制

归档后的追踪仍然可读，但依赖跨度负载的搜索（例如 trace.text 和 span.content）在这些负载移出追踪存储后将无法工作。MLflow 也不允许向已归档的追踪附加新的跨度。

从宏观层面看，该流程如下所示

Trace archival flow

配置保留策略​

如何解析保留策略​

MLflow 从最宽泛到最窄的范围解析归档策略

范围如何配置控制内容
服务器MLFLOW_TRACE_ARCHIVAL_CONFIG YAML默认归档位置、默认保留期限和调度程序设置
工作空间mlflow.create_workspace() / mlflow.update_workspace() (使用 TraceArchivalConfig)特定于工作空间的归档位置和默认保留期限
实验mlflow experiments create / mlflow experiments update特定于实验的保留期限覆盖，以及仅限“立即归档”请求

较短的实验保留期限会自动覆盖较宽泛的策略。较长的实验保留期限仅在实验 ID 列在服务器的 long_retention_allowlist 中时才生效；否则，MLflow 将回退到更宽泛的保留策略。

归档位置仅从服务器或工作空间配置中解析。实验级设置可以更改保留期限并请求立即处理归档，但不能更改归档跨度负载的存储位置。

当确定了有效的保留期限后，MLflow 会在聚焦于追踪的实验视图中将其显示为 Archive after: ...（归档于：...）徽章。

Archive after badge in the trace list

::::warning 归档不可撤销 MLflow 目前不支持将已归档的跨度负载恢复到追踪存储中。已归档的追踪仍然可读，但一旦归档完成，该追踪将继续从归档存储中提供服务，而不是从数据库中提供。 :::

配置保留策略前​

追踪归档是一项服务器级功能。工作空间级和实验级设置仅在管理员在追踪服务器上启用归档后才会生效。

有关工作空间特定的设置，请参阅 工作空间入门。

设置工作空间级默认值​

启用工作空间后，管理员可以为特定工作空间覆盖更宽泛的归档默认值

python
import mlflow
from mlflow.entities import TraceArchivalConfig

mlflow.set_tracking_uri("https://:5000")

workspace = mlflow.create_workspace(
    name="team-a",
    description="Workspace for Team A traces",
    default_artifact_root="s3://team-a-artifacts",
    trace_archival_config=TraceArchivalConfig(
        location="s3://mlflow-trace-archive/team-a",
        retention="14d",
    ),
)

print(workspace)

以相同方式更新现有工作空间

python
import mlflow
from mlflow.entities import TraceArchivalConfig

mlflow.set_tracking_uri("https://:5000")

updated = mlflow.update_workspace(
    name="team-a",
    trace_archival_config=TraceArchivalConfig(
        location="s3://mlflow-trace-archive/team-a",
        retention="7d",
    ),
)

print(updated)

使用空字符串清除工作空间覆盖，并回退到更宽泛的服务器策略

python
import mlflow
from mlflow.entities import TraceArchivalConfig

mlflow.set_tracking_uri("https://:5000")

mlflow.update_workspace(
    name="team-a",
    trace_archival_config=TraceArchivalConfig(location="", retention=""),
)

设置实验级保留期限​

您可以在创建实验时或稍后通过 CLI 或实验 UI 设置特定于实验的保留期限覆盖。

创建带有保留期限覆盖的实验

bash
mlflow experiments create \
  --experiment-name "support-bot" \
  --trace-archival-retention 7d

稍后更新或清除覆盖

bash
mlflow experiments update \
  --experiment-id 123 \
  --trace-archival-retention 7d

mlflow experiments update \
  --experiment-id 123 \
  --clear-trace-archival-retention

这些命令用于配置归档策略；它们不会立即归档追踪。

立即触发归档​

当您希望服务器在下一次调度程序运行期间处理特定实验，且不更改其长期保留策略时，请使用立即归档（archive-now）。

归档实验的所有合规追踪

bash
mlflow experiments update \
  --experiment-id 123 \
  --trace-archive-now

仅归档早于特定期限的追踪

bash
mlflow experiments update \
  --experiment-id 123 \
  --trace-archive-now-older-than 1d

清除待处理的立即归档请求

bash
mlflow experiments update \
  --experiment-id 123 \
  --clear-trace-archive-now
注意

“立即归档”会将该实验标记为在下一次调度程序运行期间处理。它不会从客户端内联执行归档。

归档后的变化​

已归档的追踪在 MLflow 中仍然可访问。您仍然可以在 UI 中打开它们，并通过追踪 API 检索它们。

最大的行为变化是可搜索性。依赖跨度负载的搜索（包括 trace.text 和 span.content 过滤器）在这些负载被归档出 SQL 存储后将不再起作用。基于元数据和标签的过滤器将继续工作。

已归档的追踪也会拒绝新的跨度写入。如果您的应用程序尝试在追踪被归档后附加更多跨度，MLflow 将返回写入冲突错误。

限制与故障排除​

  • 重试行为取决于故障类型。瞬时的存储、存储库或数据库故障仍然可以重试，并会在随后的调度程序运行中再次被拾取。格式错误的追踪故障会被标记为 mlflow.trace.archivalFailure 系统标签，并在未来的运行中被跳过，直到基础追踪数据被修复且标签被清除。
  • 如果追踪卡在格式错误状态，管理员可以在修复底层追踪数据后，使用 mlflow.client.MlflowClient.delete_trace_tag() 清除 mlflow.trace.archivalFailure，以便调度程序可以再次尝试。
  • 如果为实验请求了 archive-now，则只要存在可重试或未解决的追踪，该请求就会保持挂起状态。在匹配的追踪成功归档或仅剩下最终的格式错误时，它才会清除。
  • 如果您需要永久删除旧追踪而不是仅移动其负载，请使用 删除追踪。

有关相关工作流，请参阅 查看追踪 和 搜索追踪。