Kubeflow Pipeline + MLflow 集成

本指南介绍如何使用 MLflow Python client,将 Kubeflow Pipelines(KFP)组件中的参数、指标和模型记录到 Alauda AI 上的 MLflow。身份验证以及 workspace/RBAC 遵循 将 MLflow Python SDK 与身份验证和 RBAC 一起使用——每个组件都会使用用户身份令牌进行身份验证,服务器会以该用户身份记录 run。

适用范围

  • Alauda AI 2.5 及更高版本。
  • 已安装 Kubeflow Pipelines 和 MLflow 集群插件。
  • MLflow workspace 是一个标记为 mlflow-enabled=true 的 namespace。
  • 对于 bearer-token 方法,MLflow OAuth proxy 必须接受 Dex id token(--skip-jwt-bearer-tokens)——请参见 SDK 指南中的 Platform setup。无需进行全局认证更改,cookie 方法也完全不需要任何设置。

先决条件

  • kfp 和 kfp-kubernetes Python SDK(pip install kfp kfp-kubernetes)。
  • 可访问 KFP endpoint(请参见 使用 Kubeflow Pipelines)。
  • 适用于专用非个人账户的 Dex id token(普通平台登录,不是 Kubernetes ServiceAccount),通过 authorization-code flow 在无需浏览器的情况下获取(请参见 SDK 指南)。将其存储在 Kubernetes Secret 中,并注入到组件里。
  • 该账户可访问的 MLflow workspace(即 mlflow-enabled=true 的 namespace)。

组件如何访问 MLflow

pipeline 组件运行在 集群内部,因此它通过集群内 Service http://mlflow-tracking-server.kubeflow:5000 与 MLflow 通信(其前端是 OAuth proxy——组件不会直接使用 MLflow 容器端口)。它的身份验证方式与任何其他 MLflow client 完全相同:

  • MLFLOW_TRACKING_TOKEN — Dex id token;MLflow client 会将其作为 Authorization: Bearer … 发送。
  • mlflow.set_workspace(...) — 选择 workspace(X-MLFLOW-WORKSPACE)。

服务器会从令牌中读取身份,并以该用户身份记录 run。有关令牌如何获取以及授权如何工作的说明,请参见 SDK 指南。

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

该组件使用 MLflow client,并通过 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.10"])
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 flow,无需浏览器即可获取 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 指南中的 token flow),并使用 refresh token 续期,这样每次 run 都能获得新的令牌。

上传并运行

通过 KFP UI

  1. 进入 Kubeflow Dashboard → Pipelines → Upload Pipeline,并选择 pipeline.yaml。
  2. 单击 Create Run,然后填写参数(workspace、model name、epochs)。
  3. run 启动后,在 Alauda AI → Tools → MLFlow 中查看 MLflow UI——run 的所有者是该令牌对应的用户。

通过 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.*。请将接收到的字符串用于 run 名称,以便区分每次 pipeline 执行生成的 runs。

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

切勿将令牌或账户凭据硬编码到 pipeline.yaml 中——编译后的 pipelines 会被存储并共享。请从 Secret 中注入这些信息,并在 id token 过期前刷新它(或者在组件内部重新获取)。

在 run 内记录 metrics

每个 metric 都属于一个 mlflow.start_run() 块。如果某个组件包含多个逻辑阶段,应为每个阶段分别开启一个 run,而不要在 run context 外记录。

生产环境中的 artifact 存储

记录大型模型 artifact 需要持久化对象存储。请在 MLflow 设置中配置与 S3 兼容的存储(参见 MLflow 安装 → 高可用性和存储),以避免 artifact 上传触及 pod 磁盘限制。

故障排查

症状检查项
组件因 HTML/redirect(302)响应而失败OAuth proxy 拒绝了该令牌。请确认 proxy 已配置 --skip-jwt-bearer-tokens,并且 MLFLOW_TRACKING_TOKEN 是有效的 Dex id token(参见 SDK 指南)。
401 UNAUTHENTICATEDMLFLOW_TRACKING_TOKEN 未设置、为空或已过期——请刷新 mlflow-token Secret。
403 PERMISSION_DENIED令牌对应的用户没有该 workspace namespace 的访问权限。请为该用户授予 MLflow workspace 的访问权限(参见 Workspaces and access control);这里不涉及 ServiceAccount。
run 显示在错误的所有者 / workspace 下所有者取决于令牌身份;workspace 取决于 set_workspace()(否则使用服务器默认值)。请同时检查两者。
MLflow metrics 未出现在 KFP UI 中KFP 和 MLflow 是彼此独立的系统。记录到 MLflow 的 metrics 会显示在 MLflow UI(Alauda AI → Tools → MLFlow)中,而不会显示在 KFP run 输出中。