MLflow 客户端兼容性

版本历史

• 在极狐GitLab 15.11 中引入。
• 在极狐GitLab 17.8 中 GA。

MLflow 是一个流行的开源机器学习实验跟踪工具。极狐GitLab 的模型实验跟踪和模型仓库与 MLflow 客户端兼容。设置只需对现有代码进行最少更改。

启用 MLflow 客户端集成#

先决条件：

• 一个与极狐GitLab 兼容的 Python 客户端：
  • 推荐：极狐GitLab MLOps Python 客户端。
  • 另一个选项是 MLflow 客户端版本。MLflow 客户端与极狐GitLab 兼容。
• 一个具有开发者、维护者或所有者角色以及 api 范围的个人、项目或群组访问令牌。
• 项目 ID。要查找项目 ID：
  1. 在顶部栏中，选择 搜索或跳转到 并找到你的项目。
  2. 选择 设置 > 通用。

要从本地环境使用 MLflow 客户端兼容性：

1. 在运行代码的主机上设置跟踪 URI 和令牌环境变量。 这可以是你的本地环境、CI 流水线或远程主机。例如：

   shell
   export MLFLOW_TRACKING_URI="<your gitlab endpoint>/api/v4/projects/<your project id>/ml/mlflow"
   export MLFLOW_TRACKING_TOKEN="<your_access_token>"

2. 如果训练代码包含对 mlflow.set_tracking_uri() 的调用，请将其移除。

在模型仓库中，你可以通过选择右上角的垂直省略号 (

) 从溢出菜单中复制跟踪 URI。

模型实验#

运行训练代码时，可以使用 MLflow 客户端在极狐GitLab 上创建实验、运行、模型、模型版本、记录参数、指标、元数据和产物。

实验记录后，它们会列在 /<your project>/-/ml/experiments 下。

运行会被注册，并可以通过选择实验、模型或模型版本来探索。

创建实验#

python
1import mlflow
2
3# 创建一个新的实验
4experiment_id = mlflow.create_experiment(name="<your_experiment>")
5
6# 设置活动实验时，如果该实验不存在，也会创建一个新的实验。
7mlflow.set_experiment(experiment_name="<your_experiment>")

创建运行#

python
1import mlflow
2
3# 创建运行需要实验 ID 或活动实验
4mlflow.set_experiment(experiment_name="<your_experiment>")
5
6# 可以使用上下文管理器或不使用上下文管理器来创建运行
7with mlflow.start_run() as run:
8    print(run.info.run_id)
9    # 你的训练代码
10
11with mlflow.start_run():
12    # 你的训练代码

记录参数和指标#

python
1import mlflow
2
3mlflow.set_experiment(experiment_name="<your_experiment>")
4
5with mlflow.start_run():
6    # 参数键在运行范围内必须唯一
7    mlflow.log_param(key="param_1", value=1)
8
9    # 指标可以在整个运行过程中更新
10    mlflow.log_metric(key="metrics_1", value=1)
11    mlflow.log_metric(key="metrics_1", value=2)

记录产物#

python
1import mlflow
2
3mlflow.set_experiment(experiment_name="<your_experiment>")
4
5with mlflow.start_run():
6    # 纯文本文件可以使用 `log_text` 作为产物记录
7    mlflow.log_text('Hello, World!', artifact_file='hello.txt')
8
9    mlflow.log_artifact(
10        local_path='<local/path/to/file.txt>',
11        artifact_path='<optional relative path to log the artifact at>'
12    )

记录模型#

可以使用受支持的 MLflow 模型风格之一来记录模型。使用模型风格记录会记录元数据，从而更轻松地跨不同工具和环境管理、加载和部署模型。

python
1import mlflow
2from sklearn.ensemble import RandomForestClassifier
3
4mlflow.set_experiment(experiment_name="<your_experiment>")
5
6with mlflow.start_run():
7    # 创建并训练一个简单模型
8    model = RandomForestClassifier(n_estimators=10, random_state=42)
9    model.fit(X_train, y_train)
10
11    # 使用 MLflow sklearn 模型风格记录模型
12    mlflow.sklearn.log_model(model, artifact_path="")

加载运行#

版本历史

• 在极狐GitLab 17.9 中引入。

你可以从极狐GitLab 模型仓库加载运行，例如进行预测。

python
1import mlflow
2import mlflow.pyfunc
3
4run_id = "<your_run_id>"
5download_path = "models"  # 下载到的本地文件夹
6
7mlflow.pyfunc.load_model(f"runs:/{run_id}/", dst_path=download_path)
8
9sample_input = [[1,0,3,4],[2,0,1,2]]
10model.predict(data=sample_input)

将运行关联到 CI/CD 作业#

版本历史

• 在极狐GitLab 16.1 中引入。
• 在极狐GitLab 17.1 中变更为测试版。

如果你的训练代码是从 CI/CD 作业运行的，极狐GitLab 可以使用该信息来增强运行元数据。要将运行关联到 CI/CD 作业：

1. 在项目 CI 变量中，包含以下变量：

   • MLFLOW_TRACKING_URI: "<your gitlab endpoint>/api/v4/projects/<your project id>/ml/mlflow"
   • MLFLOW_TRACKING_TOKEN: <your_access_token>

2. 在运行执行上下文中的训练代码里，添加以下代码片段：

   python
   1import os
   2import mlflow
   3
   4with mlflow.start_run(run_name=f"Run {index}"):
   5  # 你的训练代码
   6
   7  # 要包含的代码片段开始
   8  if os.getenv('GITLAB_CI'):
   9    mlflow.set_tag('gitlab.CI_JOB_ID', os.getenv('CI_JOB_ID'))
   10  # 要包含的代码片段结束

模型仓库#

你还可以使用 MLflow 客户端管理模型和模型版本。模型注册在 /<your project>/-/ml/models 下。

模型#

创建模型#

python
1from mlflow import MlflowClient
2
3client = MlflowClient()
4model_name = '<your_model_name>'
5description = 'Model description'
6model = client.create_registered_model(model_name, description=description)

注意

• create_registered_model 参数 tags 被忽略。
• name 在项目内必须唯一。
• name 不能是现有实验的名称。

获取模型#

python
from mlflow import MlflowClient

client = MlflowClient()
model_name = '<your_model_name>'
model = client.get_registered_model(model_name)

更新模型#

python
1from mlflow import MlflowClient
2
3client = MlflowClient()
4model_name = '<your_model_name>'
5description = 'New description'
6client.update_registered_model(model_name, description=description)

删除模型#

python
from mlflow import MlflowClient

client = MlflowClient()
model_name = '<your_model_name>'
client.delete_registered_model(model_name)

将运行记录到模型#

每个模型都有一个关联的实验，其名称相同，但带有 [model] 前缀。要将运行记录到模型，请使用传递正确名称的实验：

python
1from mlflow import MlflowClient
2
3client = MlflowClient()
4model_name = '<your_model_name>'
5exp = client.get_experiment_by_name(f"[model]{model_name}")
6run = client.create_run(exp.experiment_id)

模型版本#

创建模型版本#

python
1from mlflow import MlflowClient
2
3client = MlflowClient()
4model_name = '<your_model_name>'
5description = 'Model version description'
6model_version = client.create_model_version(model_name, source="", description=description)

如果未传递版本参数，它将从最新上传的版本自动递增。你可以在创建模型版本时通过传递标签来设置版本。版本必须遵循 SemVer 格式。

python
1from mlflow import MlflowClient
2
3client = MlflowClient()
4model_name = '<your_model_name>'
5version = '<your_version>'
6tags = { "gitlab.version": version }
7client.create_model_version(model_name, version, description=description, tags=tags)

注意

• 参数 run_id 被忽略。每个模型版本的行为类似于一个运行。尚不支持从运行创建模型版本。
• 参数 source 被忽略。极狐GitLab 将为模型版本文件创建一个软件包位置。
• 参数 run_link 被忽略。
• 参数 await_creation_for 被忽略。

更新模型#

python
1from mlflow import MlflowClient
2
3client = MlflowClient()
4model_name = '<your_model_name>'
5version = '<your_version>'
6description = 'New description'
7client.update_model_version(model_name, version, description=description)

获取模型版本#

python
1from mlflow import MlflowClient
2
3client = MlflowClient()
4model_name = '<your_model_name>'
5version = '<your_version>'
6client.get_model_version(model_name, version)

获取模型的最新版本#

python
from mlflow import MlflowClient

client = MlflowClient()
model_name = '<your_model_name>'
client.get_latest_versions(model_name)

注意

• 参数 stages 被忽略。
• 版本按最高语义版本排序。

加载模型版本#

python
1from mlflow import MlflowClient
2
3client = MlflowClient()
4model_name = '<your_model_name>'
5version = '<your_version'  # 例如：'1.0.0'
6
7# 或者搜索版本
8version = mlflow.search_registered_models(filter_string="name='{model_name}'")[0].latest_versions[0].version
9
10model = mlflow.pyfunc.load_model(f"models:/{model_name}/{latest_version}")
11
12# 或者加载最新版本
13model = mlflow.pyfunc.load_model(f"models:/{model_name}/latest")

将指标和参数记录到模型版本#

每个模型版本也是一个运行，允许用户记录参数和指标。运行 ID 可以在极狐GitLab 的模型版本页面找到，或使用 MLflow 客户端：

python
1from mlflow import MlflowClient
2
3client = MlflowClient()
4model_name = '<your_model_name>'
5version = '<your_version>'
6model_version = client.get_model_version(model_name, version)
7run_id = model_version.run_id
8
9# 你的训练代码
10
11client.log_metric(run_id, '<metric_name>', '<metric_value>')
12client.log_param(run_id, '<param_name>', '<param_value>')
13client.log_batch(run_id, metric_list, param_list, tag_list)

因为每个文件有 5 GB 的大小限制，你必须对较大的模型进行分区。

将产物记录到模型版本#

极狐GitLab 创建一个软件包，MLflow 客户端可以使用它来上传文件。

python
1from mlflow import MlflowClient
2
3client = MlflowClient()
4model_name = '<your_model_name>'
5version = '<your_version>'
6model_version = client.get_model_version(model_name, version)
7run_id = model_version.run_id
8
9# 你的训练代码
10
11client.log_artifact(run_id, '<local/path/to/file.txt>', artifact_path="")
12client.log_figure(run_id, figure, artifact_file="my_plot.png")
13client.log_dict(run_id, my_dict, artifact_file="my_dict.json")
14client.log_image(run_id, image, artifact_file="image.png")

产物随后将在 https/<your project>/-/ml/models/<model_id>/versions/<version_id> 下可用。

将模型版本链接到 CI/CD 作业#

与运行类似，也可以将模型版本链接到 CI/CD 作业：

python
1import os
2from mlflow import MlflowClient
3
4client = MlflowClient()
5model_name = '<your_model_name>'
6version = '<your_version>'
7model_version = client.get_model_version(model_name, version)
8run_id = model_version.run_id
9
10# 你的训练代码
11
12if os.getenv('GITLAB_CI'):
13    client.set_tag(model_version.run_id, 'gitlab.CI_JOB_ID', os.getenv('CI_JOB_ID'))

支持的 MLflow 客户端方法和注意事项#

极狐GitLab 支持 MLflow 客户端的以下方法。更多信息可以在 MLflow 文档中找到。以下方法的 MlflowClient 对应方法也受支持，并具有相同的注意事项。

其他 MlflowClient 方法：