Kubeflow Pipeline + MLflow 集成

本指南介绍如何使用 MLflow Python 客户端,将 Kubeflow Pipelines (KFP) 组件的参数、指标和模型记录到 Alauda AI Platform 上的 MLflow。身份验证以及工作区/RBAC 遵循使用 MLflow Python SDK 进行身份验证和 RBAC中的说明——每个组件都使用用户身份令牌进行身份验证,服务器会将运行记录在该用户名下。

适用范围

  • Alauda AI 2.5 及更高版本。
  • 已安装 Kubeflow Pipelines 和 MLflow Operator,并且正在运行 MLflow 自定义资源。
  • MLflow 工作区是带有 mlflow-enabled=true 标签的命名空间。
  • 对于 bearer token 方法,请保留默认的 spec.auth.oauth.skipJwtBearerTokens: true——请参阅 SDK 指南中的验证令牌方法。无需更改全局身份验证,cookie 方法也完全无需设置。

先决条件

  • kfp 和 kfp-kubernetes Python SDK (pip install kfp kfp-kubernetes)。
  • 对 KFP endpoint 的访问权限(请参阅使用 Kubeflow Pipelines)。
  • 专用非个人账户的 Dex id token(普通平台登录账户,而非 Kubernetes ServiceAccount),通过 authorization-code 流程在无需浏览器的情况下生成(请参阅 SDK 指南)。将其存储在 Kubernetes Secret 中,并将其注入组件。
  • 一个账户可以访问的 MLflow 工作区(带有 mlflow-enabled=true 的命名空间)。

组件如何访问 MLflow

Pipeline 组件在集群内部运行,因此会通过集群内 Service http://mlflow-tracking-server.kubeflow:5000 与 MLflow 通信(该 Service 前面由 OAuth proxy 提供代理——组件绝不会直接使用 MLflow 容器端口)。它的身份验证方式与其他 MLflow 客户端完全相同:

  • MLFLOW_TRACKING_TOKEN — Dex id token;MLflow 客户端将其作为 Authorization: Bearer … 发送。
  • mlflow.set_workspace(...) — 选择工作区 (X-MLFLOW-WORKSPACE)。

服务器从令牌中读取身份,并将运行记录在该用户名下。有关如何获取令牌以及授权工作原理,请参阅 SDK 指南。

完整示例:使用 MLflow 的训练 Pipeline

该组件使用 MLflow 客户端,并从通过 kfp-kubernetes 注入的 Secret 中读取 MLFLOW_TRACKING_TOKEN。KFP v2 会从每个组件自身的源代码打包组件,因此 import mlflow 位于函数内部。

from kfp import dsl, compiler
from kfp import kubernetes


@dsl.component(base_image="python:3.11-slim", packages_to_install=["mlflow==3.13.0"])
def train_model(
    workspace: str,
    model_name: str,
    learning_rate: float,
    epochs: int,
    run_id: str,
) -> dict:
    """Simulated training component that logs to MLflow as the calling user."""
    import mlflow   # MLFLOW_TRACKING_TOKEN is injected from a Secret (see the pipeline below)

    mlflow.set_tracking_uri("http://mlflow-tracking-server.kubeflow:5000")  # in-cluster Service, via the OAuth proxy
    mlflow.set_workspace(workspace)
    mlflow.set_experiment("kfp-training-experiment")

    metrics = {}
    with mlflow.start_run(run_name=f"run-{run_id}"):
        mlflow.log_param("model_name", model_name)
        mlflow.log_param("learning_rate", learning_rate)
        mlflow.log_param("epochs", epochs)
        for epoch in range(1, epochs + 1):
            loss = 2.0 * (0.95 ** epoch)
            accuracy = 1.0 - loss
            mlflow.log_metric("loss", loss, step=epoch)
            mlflow.log_metric("accuracy", accuracy, step=epoch)
            metrics = {"final_loss": loss, "final_accuracy": accuracy}

    print("logged run:", mlflow.last_active_run().info.run_id)
    return metrics


@dsl.pipeline(name="mlflow-training-pipeline", description="Train with MLflow tracking")
def training_pipeline(
    workspace: str = "team-a",
    model_name: str = "qwen3-0.6b",
    learning_rate: float = 2e-4,
    epochs: int = 10,
):
    task = train_model(
        workspace=workspace,
        model_name=model_name,
        learning_rate=learning_rate,
        epochs=epochs,
        # PIPELINE_JOB_ID_PLACEHOLDER resolves to the run's job id at runtime;
        # pass it in as an argument (a component cannot reference dsl.* itself).
        run_id=dsl.PIPELINE_JOB_ID_PLACEHOLDER,
    )
    # Inject the Dex id token from a Secret as MLFLOW_TRACKING_TOKEN.
    kubernetes.use_secret_as_env(
        task, secret_name="mlflow-token", secret_key_to_env={"token": "MLFLOW_TRACKING_TOKEN"}
    )


compiler.Compiler().compile(training_pipeline, "pipeline.yaml")

创建包含 Dex id token 的 mlflow-token Secret。按照 SDK 指南中的 authorization-code 流程,在无需浏览器的情况下生成 ID_TOKEN——请参阅从命令行获取令牌:

# ID_TOKEN: mint it with the curl/Python flow in the SDK guide (browser-free, current grants)
kubectl -n <pipeline-namespace> create secret generic mlflow-token --from-literal=token="$ID_TOKEN"
WARNING

id token 默认 24 小时后过期,因此在提交长时间运行的 Pipeline 之前,请刷新 mlflow-token Secret——或者在组件内部使用存储在 Secret 中的账户凭据生成令牌(请参阅 SDK 指南中的令牌流程),并使用 refresh token 续期,这样每次运行都会获得新令牌。

上传和运行

通过 KFP UI

  1. 转到 Kubeflow Dashboard → Pipelines → Upload Pipeline,然后选择 pipeline.yaml。
  2. 单击 Create Run,然后填写参数(工作区、模型名称、训练轮数)。
  3. 运行开始后,在 Alauda AI Platform → Tools → MLFlow 下检查 MLflow UI——运行所有者就是令牌所属用户。

通过 KFP SDK

from kfp.client import Client

client = Client(host="<MY-KFP-ENDPOINT>")
run = client.create_run_from_pipeline_package(
    "pipeline.yaml",
    arguments=dict(workspace="team-a", model_name="qwen3-0.6b", epochs=10),
)
print(f"Run ID: {run.run_id}")

在 Trainer v2 Pipeline 中使用 MLflow

如果使用 Kubeflow Trainer v2 进行微调,则框架的 MLflow 集成(例如 LLaMA-Factory 中的 report_to: mlflow)会以相同方式进行身份验证。Trainer v2 使用 apiVersion: trainer.kubeflow.org/v1alpha1、kind: TrainJob 以及 spec.runtimeRef + spec.trainer 结构。将其指向集群内 Service,并从 Secret 注入 id token:

apiVersion: trainer.kubeflow.org/v1alpha1
kind: TrainJob
metadata:
  name: mlflow-finetune
spec:
  runtimeRef:
    name: torch-distributed        # a TrainingRuntime / ClusterTrainingRuntime
  trainer:
    image: alaudadockerhub/fine_tune_with_llamafactory:v0.1.1
    env:
      - name: MLFLOW_TRACKING_URI
        value: "http://mlflow-tracking-server.kubeflow:5000"
      - name: MLFLOW_EXPERIMENT_NAME
        value: "trainer-v2-finetune"
      - name: MLFLOW_TRACKING_TOKEN
        valueFrom:
          secretKeyRef:
            name: mlflow-token       # a Secret holding a Dex id token
            key: token

有关完整的 Trainer v2 + MLflow 示例,请参阅使用 Workbench 微调 LLM。

有关将此集成与 MLflow Model Registry、TrustyAI LMEvalJob 以及每日 KFP Recurring Run 结合使用的更完整解决方案,请参阅使用 MLflow 和 TrustyAI 的每日微调 Pipeline。

最佳实践

在 MLflow 中使用 Pipeline Job ID

KFP v2 提供 dsl.PIPELINE_JOB_ID_PLACEHOLDER(v1 中的 dsl.RUN_ID_PLACEHOLDER 已移除)。它是 Pipeline 级别的占位符,因此应将其作为参数传递给组件——组件无法在自身主体中引用 dsl.*。在运行名称中使用接收到的字符串,以确保每次 Pipeline 执行的运行彼此区分。

将凭据保存在 Secret 中并刷新令牌

切勿将令牌或帐户凭据硬编码到 pipeline.yaml 中——编译后的 Pipeline 会被存储和共享。应从 Secret 注入这些凭据,并在 id token 过期前刷新它(或在组件内部生成)。

在运行中记录指标

每个指标都应属于一个 mlflow.start_run() 块。如果一个组件包含多个逻辑阶段,应为每个阶段打开一个运行,而不是在运行上下文之外记录指标。

用于生产环境的制品存储

兼容 S3 的代理存储允许 Pipeline 组件通过 tracking server 上传内容,而无需接收 S3 凭据。在记录制品或注册模型之前配置 artifacts.s3(请参阅 MLflow 安装 → 高可用性和存储)。

故障排除

症状检查
组件因 HTML/重定向(302)响应而失败OAuth proxy 拒绝了令牌。确认 spec.auth.oauth.skipJwtBearerTokens 为 true,且 MLFLOW_TRACKING_TOKEN 是有效的 Dex id token(请参阅 SDK 指南)。
401 UNAUTHENTICATEDMLFLOW_TRACKING_TOKEN 未设置、为空或已过期——刷新 mlflow-token Secret。
403 PERMISSION_DENIED令牌所属用户无权访问 workspace namespace。授予其 MLflow workspace 的访问权限(请参阅 MLflow Workspaces 和访问控制);此处不涉及 ServiceAccount。
运行显示在错误的所有者 / workspace 下所有者是令牌的身份;workspace 是 set_workspace()(否则为 server 默认值)。检查这两项。
MLflow 指标未显示在 KFP UI 中KFP 和 MLflow 是独立的系统。记录到 MLflow 的指标会显示在 MLflow UI(Alauda AI Platform → Tools → MLFlow)中,而不会显示在 KFP 运行输出中。