安装 MLflow

在 Alauda AI Platform 2.9 中,MLflow 由 Alauda AI Platform 安装和管理。集群范围的 default AmlCluster 中的 mlflow 组件默认为 Unmanaged;将其设置为 Managed 后,Alauda AI Platform 会自动安装 MLflow Operator — 无需手动从 OperatorHub 安装 Operator。启用该组件只会安装 Operator;您仍需创建 MLflow 自定义资源来部署 tracking-server 堆栈,具体说明请参见创建 MLflow tracking server。

前提条件

  • 目标集群中已安装 Alauda AI Platform。operator 及其镜像以 linux/amd64 和 linux/arm64 两种形式提供。

  • 目标集群中可用 Operator Lifecycle Manager (OLM)(由平台提供)。

  • 一个 PostgreSQL 12 或更高版本的数据库,可从集群访问,并包含一个名为 mlflow 的数据库,用于存储 MLflow 元数据。请准备好主机、端口、用户名和密码,并在安装前创建该数据库:

    CREATE DATABASE mlflow;

    生产环境请使用高可用的 PostgreSQL 服务(请参见高可用性和存储)。

  • 对于生产环境的工件存储,需要在 SeaweedFS、MinIO、Ceph RGW 或 AWS S3 中已有一个兼容 S3 的存储桶。operator 可以代理工件访问,因此客户端无需对象存储凭据。Pod 内文件系统默认设置仅适用于冒烟测试。

  • 平台 OAuth / OIDC provider(由 Alauda AI Platform 提供)— tracking server 前端的 OAuth proxy 使用它实现单点登录。

  • 对于多租户,默认 workspace 命名空间必须已存在,并且必须在 tracking server 首次启动之前携带标签 mlflow-enabled=true。 否则服务器会因 Workspace '<name>' not found in the Kubernetes cluster 进入崩溃循环。

    kubectl create namespace finetune
    kubectl label namespace finetune mlflow-enabled=true

上架 Operator 软件包

从 Customer Portal / Marketplace 下载 MLflow Operator 捆绑包,然后按照上架软件包中的说明上传该软件包。

INFO

operator 捆绑包会在 CSV relatedImages 中记录每个运行时镜像(operator、MLflow tracking server 和 oauth2-proxy),因此 violet release 会将它们重新定位到平台 registry。这样一来,无需访问 build-harbor.alauda.cn / docker.io,即可在 air-gapped 集群上安装 operator。

启用 MLflow

在管理员视图中:

  1. 打开 Marketplace > OperatorHub。
  2. 选择目标集群并打开 Alauda AI Platform。
  3. 打开 All Instances 选项卡并编辑 default AmlCluster 实例。
  4. 将 spec.components.mlflow.managementState 设置为 Managed。
  5. 保存 AmlCluster 实例,并等待 MLflow Operator 就绪。

你可以在 AmlCluster YAML 中应用组件设置:

spec:
  components:
    mlflow:
      managementState: Managed

继续之前,请确认 operator 已就绪:

kubectl get amlcluster default

# the CSV reports Succeeded
kubectl get csv -n mlflow-operator | grep mlflow-operator

# the operator controller-manager pod is Running
kubectl get pods -n mlflow-operator

AmlCluster 应报告 Phase=Ready。启用该组件会安装 MLflow Operator;只有在你按照下文所述创建 MLflow 自定义资源后,才会部署 tracking server。

创建 MLflow tracking server

在你创建 MLflow 自定义资源(mlflow.alauda.io/v1alpha1)之前,operator 不会执行任何操作。你可以通过两种方式创建:

  • kubectl — 应用 MLflow 清单。
  • Alauda Console UI — 依次转到 Administrator → Marketplace → OperatorHub → MLflow Operator → All instances → Create。

两种方式创建的资源相同;请选择适合你工作流的方式。

方法 A — 使用 kubectl

设置数据库连接和多租户字段,然后应用:

apiVersion: mlflow.alauda.io/v1alpha1
kind: MLflow
metadata:
  name: mlflow
spec:
  # Namespace the tracking server is deployed into (chart-mandated: kubeflow).
  namespace: kubeflow

  # External PostgreSQL for MLflow metadata — the `mlflow` database must already exist.
  pgHost: postgresql.database.svc
  pgPort: 5432
  pgUsername: mlflow
  pgPassword: <db-password>

  # Multi-tenancy: map Kubernetes namespaces to MLflow workspaces.
  multitenancy:
    enabled: true
    defaultWorkspace: finetune                 # must exist and be labelled before first boot
    workspaceLabelSelector: mlflow-enabled=true

  # Run-artifact location (see High availability and storage below).
  artifacts:
    defaultArtifactRoot: /mlflow/artifacts
    # Recommended for production. The bucket and Secret must already exist.
    s3:
      enabled: true
      endpointUrl: https://object-storage.example.com
      bucket: mlflow
      prefix: production
      existingSecret: mlflow-s3-credentials
      accessKeyIdKey: AWS_ACCESS_KEY_ID
      secretAccessKeyKey: AWS_SECRET_ACCESS_KEY
      proxied: true

保存为 mlflow.yaml 并应用:

kubectl apply -f mlflow.yaml
INFO

在当前版本中,operator 会从 kube-public/global-info ConfigMap 中解析特定于集群的值,包括 ingress/ALB 名称、集群名称和镜像 registry,因此通常无需设置 spec.global 和 spec.platformAddr。auth 设置(oauth2-proxy 配置)也有合理的默认值。Console 中的 Create 表单会预填一份完整示例(operator 的 alm-examples),你可以对其进行编辑;所有字段均记录在 operator 的 config/samples/mlflow_v1alpha1_mlflow.yaml 中。

方法 B — 使用 Alauda Console UI

  1. 在 Administrator 视图中,转到 Marketplace → OperatorHub。
  2. 从顶部的 Cluster 下拉菜单中选择目标集群。
  3. 打开已安装的 MLflow Operator。
  4. 切换到 All instances 选项卡并单击 Create(如果系统提示,请选择 MLflow)。
  5. 填写表单,或切换到 YAML 视图并粘贴方法 A 中的清单。设置 PostgreSQL 连接、多租户 workspace 字段,以及生产环境所需的 S3 工件存储字段。
  6. 单击 Create。

验证

验证跟踪服务器已在配置的命名空间(kubeflow)中完成协调:

# the operand exists
kubectl get mlflow

# the tracking-server Deployment is Available (two containers: the server + oauth2-proxy)
kubectl -n kubeflow get deploy mlflow-tracking-server

# its pod is Running
kubectl -n kubeflow get pods -l app.kubernetes.io/name=mlflow-tracking-server

然后打开 Alauda AI Platform → Tools → MLFlow。运行的所有者和可见工作区会反映你登录时使用的身份。

高可用性和存储

  • 数据库。 MLflow 会将所有实验/运行/注册表元数据存储在你配置的外部 PostgreSQL 中。生产环境请使用高可用的 PostgreSQL 服务;就元数据而言,跟踪服务器本身是无状态的。
  • 工件。 默认的 artifacts.defaultArtifactRoot: /mlflow/artifacts 是跟踪服务器 pod 本地的 emptyDir。它不具备持久性,外部客户端也无法可靠地使用服务器本地路径。从 v3.13.0 开始,请在用户记录工件或注册模型之前,为生产环境启用 artifacts.s3。使用默认的 proxied: true 时,跟踪服务器会存储 S3 凭据,客户端则通过经过身份验证的 MLflow 端点上传。
  • 副本。 默认部署为单副本。除非 release notes 另有说明,否则这并非多副本高可用部署。

在应用 MLflow 资源之前,请先在跟踪服务器命名空间中创建所引用的 Secret:

kubectl -n kubeflow create secret generic mlflow-s3-credentials \
  --from-literal=AWS_ACCESS_KEY_ID='<access-key>' \
  --from-literal=AWS_SECRET_ACCESS_KEY='<secret-key>'

存储桶必须已存在。对于 AWS S3,请将 endpointUrl 留空。对于兼容 S3 的服务,请将其设置为服务端点。必要时,还可以在 artifacts.s3 下设置 region、ignoreTls 和 prefix。

Bearer 令牌客户端

从 v3.13.0 开始,operator 默认启用 spec.auth.oauth.skipJwtBearerTokens: true,允许 MLflow Python SDK 通过 MLFLOW_TRACKING_TOKEN 使用 Dex id token 进行身份验证。如果现有安装覆盖了 OAuth 设置,请确认此字段仍处于启用状态。请参阅 SDK 指南中的验证令牌方法。浏览器会话 Cookie 方法仍可使用。

从 v3.10.x 升级到 v3.13.0

stable OLM channel 支持此升级。批准升级前,请备份 PostgreSQL 后端数据库和 S3 工件存储桶。跟踪服务器启动时会自动运行后端存储架构迁移。

升级后,请保留 spec.auth.kubernetes.authorizationMode: user_identity_token 和 spec.auth.oauth.skipJwtBearerTokens: true。这些默认值会保留文档所述的 Dex bearer token 流程。

故障排除

  • 如果缺少 MLFlow Tools 菜单项,请确认跟踪服务器命名空间中存在 aml-mlflow-menu-config ConfigMap,并且其标签为 aml.cpaas.io/centralMenuItem: "true"。
  • 如果服务器未启动且 pod 日志中出现 Workspace '<name>' not found,则 defaultWorkspace 命名空间不存在,或未标记为 mlflow-enabled=true。请创建并标记该命名空间,然后重启 pod。
  • 如果服务器因其他原因未启动,请确认 PostgreSQL 连接正常、mlflow 数据库存在,并且 spec.pg* 中的凭据正确。
  • 如果工件上传或模型注册失败,请确认 artifacts.s3.enabled 为 true,存储桶已存在,并且所引用的凭据 Secret 和密钥名称正确。
  • 如果无法看到某个工作区,请确认其命名空间与配置的 workspaceLabelSelector 匹配。
  • 如果请求被拒绝(403 PERMISSION_DENIED),请检查用户在该工作区命名空间中的 Kubernetes RoleBinding — 请参阅 MLflow 工作区和访问控制。