通过

将自定义 Python 库与模型服务配合使用

本文介绍如何在记录模型时，包括自定义库或来自专用镜像服务器的库，以便可以在 马赛克 AI 模型服务 的模型部署中使用它们。 在经过训练的 ML 模型准备好部署之后，创建 Azure Databricks 模型服务终结点之前，你应完成本指南中详述的步骤。

模型开发通常需要使用自定义 Python 库，其中包含用于预处理或后处理的函数、自定义模型定义和其他共享实用工具。 此外，许多企业安全团队建议使用专用 PyPi 镜像（例如 Nexus 或 Artifactory），以减少供应链攻击风险。 Azure Databricks 原生支持在 Azure Databricks 工作区中安装自定义库和来自私有镜像的库。

要求

  • MLflow 1.29 或更高版本

选项 1：使用专用包存储库

如果你的组织使用专用 PyPI 镜像（如 Nexus 或 Artifactory），请使用选项 1。 工作区管理员可以将其配置为工作区的默认包存储库。 生成模型环境时，模型服务会自动使用此工作区级配置。

若要设置专用包存储库，请参阅 “配置默认 Python 包存储库”。

配置后，继续 为模型提供服务。

选项 2：将自定义库打包为 wheel 文件

如果无法访问专用 PyPI 镜像服务器，或者您有任何包存储库中不可用的自定义库，请使用选项 2。 你可以将它们打包为 Python 滚轮文件，并在记录模型时包含这些文件。

步骤 1：上传依赖项文件

Databricks 建议将依赖项文件上传到 Unity Catalog Volumes。 或者，可以使用 Azure Databricks UI 将其上传到 Databricks 文件系统 (DBFS)。

要确保你的库可供笔记本使用，需要使用 %pip 安装它。 使用 %pip 在当前笔记本中安装库，并将依赖项下载到群集。

步骤 2：记录包含自定义库的模型

安装好库并将 Python wheel 文件上传到 Unity Catalog 卷或 DBFS 后，请在脚本中包含以下代码。 在 extra_pip_requirements 中，指定依赖项文件的路径。

mlflow.sklearn.log_model(model, "sklearn-model", extra_pip_requirements=["/volume/path/to/dependency.whl"])

对于 DBFS，请使用以下内容。

mlflow.sklearn.log_model(model, "sklearn-model", extra_pip_requirements=["/dbfs/path/to/dependency.whl"])

如果你有自定义库，则在配置日志记录时，必须指定与模型关联的所有自定义 Python 库。 可以在 log_model() 中使用 extra_pip_requirements 或 conda_env 参数执行此操作。

重要

如果在使用 DBFS，则在记录 / 时，请确保在 dbfs 路径之前加入一个正斜杠 extra_pip_requirements。 在Azure Databricks 上处理文件中了解更多有关 DBFS 路径的信息。

from mlflow.utils.environment import _mlflow_conda_env

mlflow.pyfunc.log_model(
    name="model",
    python_model=MyModel(),
    extra_pip_requirements=["/volumes/path/to/dependency"],
)

如果自定义库存储在卷或 DBFS 以外的某个位置，则可以使用code_paths参数指定其位置，并传入"code/<wheel-file-name>.whl"extra_pip_requirements参数。

mlflow.pyfunc.log_model(
    name="model",
    python_model=MyModel(),
    code_paths=["/path/to/dependency.whl"], # This will be logged as `code/dependency.whl`
    extra_pip_requirements=["code/dependency.whl"],
)

步骤 3：更新包含 Python wheel 文件的 MLflow 模型

MLflow 提供了 add_libraries_to_model() 实用工具来记录你的模型及其所有作为 Python wheel 文件预先打包的依赖项。 这会将自定义库与模型一起打包，此外还会打包指定为模型依赖项的所有其他库。 这可以保证模型使用的库正是可从训练环境访问的库。

在以下示例中，model_uri 使用语法 models:/<uc-model>/<model-version>引用 Unity 目录模型注册表。 若要引用工作区模型注册表（旧版），请使用 models:/<model-name>/<model-version>。

当你使用模型注册表 URI 时，此实用工具会在现有的已注册模型下生成一个新版本。

import mlflow.models.utils
mlflow.models.utils.add_libraries_to_model(<model-uri>)

提供你的模型

当模型注册表中提供了包含这些包的新模型版本时，你可以将此模型版本添加到模型服务的某个终结点。

排查包安装失败问题

如果模型部署在生成阶段失败，可以查看生成日志以确定包安装问题。

  1. 导航到 Databricks 工作区中的 “服务 ”页。
  2. 单击终结点名称以打开终结点详细信息。
  3. 单击“ 日志 ”选项卡。
  4. 从下拉菜单中选择失败的版本。
  5. 单击“ 生成日志”。

查看错误消息以识别问题。 如果使用专用包存储库，常见问题包括：

  • 缺少包：包在配置的存储库中不可用。 将所需的包添加到专用存储库。
  • 连接问题：模型服务无法访问包存储库。 验证网络连接和防火墙规则。
  • 身份验证失败：为存储库配置的凭据无效或已过期。 更新工作区配置中的机密。

解决问题后，创建新的部署或更新终结点以触发新构建。

  • Last updated on