mlflow.models

mlflow.models 模块提供了一个 API，用于以不同下游工具可以理解的“风味”（flavors）保存机器学习模型。

内置的风味包括

有关详细信息，请参阅 MLflow 模型指南。

class mlflow.models.EvaluationArtifact(uri, content=None)[源代码]

Bases: object

包含工件 URI 和内容的模型评估工件。

property content: 工件的内容（表示形式各不相同）

property uri: str: 工件的 URI

class mlflow.models.EvaluationResult(metrics, artifacts, run_id=None)[源代码]

Bases: object

表示 mlflow.evaluate() API 调用的模型评估输出，包含标量指标和性能图等输出工件。

property artifacts: dict[str, 'mlflow.models.EvaluationArtifact']: 一个字典，将标准化工件名称（例如“roc_data”）映射到工件内容和位置信息

classmethod load(path)[源代码]: 从指定的本地文件系统路径加载评估结果

property metrics: dict[str, typing.Any]: 一个字典，将标量指标名称映射到标量指标值

property run_id: str: 已记录评估结果的 MLflow 运行的 ID。

save(path)[源代码]: 将评估结果写入指定的本地文件系统路径

property tables: dict[str, 'pd.DataFrame']: 一个字典，将标准化工件名称（例如“eval_results_table”）映射到相应的表内容（作为 pandas DataFrame）。

class mlflow.models.FlavorBackend(config, **kwargs)[源代码]

Bases: object

Flavor Backend 的抽象类。此类定义了 MLflow 模型风味的本地模型部署的 API 接口。

abstract build_image(model_uri, image_name, install_java=False, install_mlflow=False, mlflow_home=None, enable_mlserver=False, base_image=None)[源代码]

can_build_image()[源代码]

返回: 如果此风味具有为构建能够服务模型的 Docker 容器而定义的 build_image 方法，则返回 True，否则返回 False。

abstract can_score_model()[源代码]

检查此风味后端是否可以在当前环境中部署。

返回: 如果此风味后端可以在当前环境中应用，则返回 True。

abstract generate_dockerfile(model_uri, output_dir, install_java=False, install_mlflow=False, mlflow_home=None, enable_mlserver=False, base_image=None)[源代码]

abstract predict(model_uri, input_path, output_path, content_type)[源代码]

使用给定 URI 引用的已保存 MLflow 模型生成预测。输入和输出从文件或 stdin/stdout 读取和写入。

参数

model_uri – 指向要用于评分的 MLflow 模型的 URI。
input_path – 包含输入数据的文件路径。如果未指定，则从 stdin 读取数据。
output_path – 包含输出预测的文件路径。如果未指定，则写入 stdout。
content_type – 指定输入格式。可以是 {json, csv} 中的一个

prepare_env(model_uri, capture_output=False)[源代码]: 执行预测或服务模型所需的任何准备工作，例如下载依赖项或初始化 conda 环境。准备就绪后，调用 predict 或 serve 应该很快。

abstract serve(model_uri, port, host, timeout, enable_mlserver, synchronous=True, stdout=None, stderr=None)[源代码]

在本地服务指定的 MLflow 模型。

参数

model_uri – 指向要用于评分的 MLflow 模型的 URI。
port – 模型部署使用的端口。
host – 模型部署使用的主机。默认为 localhost。
timeout – 服务请求的超时时间（秒）。默认为 60。
enable_mlserver – 是使用 MLServer 还是本地评分服务器。
synchronous – 如果为 True，则等待服务器进程退出并返回 0，如果进程以非零返回码退出，则引发异常。如果为 False，则立即返回服务器进程 Popen 实例。
stdout – 重定向服务器 stdout
stderr – 重定向服务器 stderr

class mlflow.models.MetricThreshold(threshold=None, min_absolute_change=None, min_relative_change=None, greater_is_better=None)[源代码]

Bases: object

此类允许您为模型验证定义指标阈值。允许的阈值包括：threshold、min_absolute_change、min_relative_change。

参数

threshold –
(可选) 代表指标值阈值的数字。
- 如果指标是“越大越好”，则指标值必须 >= threshold 才能通过验证。
- 否则，指标值必须 <= threshold 才能通过验证。
min_absolute_change –
(可选) 代表候选模型与基准模型进行比较时需要达到的最小绝对变化量的正数。
- 如果指标是“越大越好”，则指标值必须 >= 基准模型指标值 + min_absolute_change 才能通过验证。
- 否则，指标值必须 <= 基准模型指标值 - min_absolute_change 才能通过验证。
min_relative_change –
(可选) 一个介于 0 和 1 之间的浮点数，代表候选模型与基准模型比较时需要达到的最小相对变化量（以基准模型指标值的百分比表示）。
- 如果指标是“越大越好”，则指标值必须 >= 基准模型指标值 * (1 + min_relative_change)
- 否则，指标值必须 <= 基准模型指标值 * (1 - min_relative_change)
- 请注意，如果基准模型的指标值为 0，则阈值将退化为执行简单的验证，即候选指标值优于基准指标值，如果“越大越好”，则指标值 >= 基准模型指标值 + 1e-10；如果“越小越好”，则指标值 <= 基准模型指标值 - 1e-10。
greater_is_better – 一个必需的布尔值，表示指标值越大越好。

property greater_is_better: 一个布尔值，表示指标值越大越好。

property min_absolute_change: 与基准模型比较模型时，所需的最小绝对变化量的值。

property min_relative_change: 与基准模型比较模型时，所需的最小相对变化量的浮点数值。

property threshold: 阈值的值。

class mlflow.models.Model(artifact_path=None, run_id=None, utc_time_created=None, flavors=None, signature=None, saved_input_example_info: Optional[dict[str, typing.Any]] = None, model_uuid: Optional[Union[str, Callable[[], str]]] = <function Model.<lambda>>, mlflow_version: str | None = '3.9.0', metadata: Optional[dict[str, typing.Any]] = None, model_size_bytes: Optional[int] = None, resources: Optional[Union[str, list[mlflow.models.resources.Resource]]] = None, env_vars: Optional[list[str]] = None, auth_policy: Optional[mlflow.models.auth_policy.AuthPolicy] = None, model_id: Optional[str] = None, prompts: Optional[list[str]] = None, **kwargs)[源代码]

Bases: object

一个可以支持多种模型风味的 MLflow 模型。提供用于实现新模型风味的 API。

add_flavor(name, **params) → mlflow.models.model.Model[源代码]: 添加一个条目，说明如何以给定格式服务模型。

property auth_policy: dict[str, dict[str, typing.Any]]

一个可选字典，包含服务模型所需的身份验证策略。

Getter: 检索服务模型所需的 auth_policy
Setter: 设置服务模型所需的 auth_policy
类型: Dict[str, dict]

property env_vars: list[str] | None

classmethod from_dict(model_dict) → mlflow.models.model.Model[源代码]: 从其 YAML 表示加载模型。

get_input_schema()[源代码]: 检索模型的输入 Schema（仅当模型保存时带有 Schema 定义时）。

get_model_info(logged_model: Optional[LoggedModel] = None) → mlflow.models.model.ModelInfo[源代码]: 创建一个 ModelInfo 实例，其中包含模型元数据。

get_output_schema()[源代码]: 检索模型的输出 Schema（仅当模型保存时带有 Schema 定义时）。

get_params_schema()[源代码]: 检索模型的参数 Schema（仅当模型保存时带有 Schema 定义时）。

get_serving_input(path: str) → str | None[源代码]

从模型目录加载服务输入示例。如果没有任何服务输入示例，则返回 None。

参数: path – 模型目录的路径。
返回: 服务输入示例，如果模型没有服务输入示例，则为 None。

get_tags_dict() → dict[str, typing.Any][源代码]

classmethod load(path) → mlflow.models.model.Model[源代码]

从其 YAML 表示加载模型。

参数: path – 本地文件系统路径或 URI，指向 Model 对象的 MLmodel YAML 文件表示或包含 MLmodel YAML 文件表示的目录。
返回: Model 的一个实例。

示例

from mlflow.models import Model

# Load the Model object from a local MLmodel file
model1 = Model.load("~/path/to/my/MLmodel")

# Load the Model object from a remote model directory
model2 = Model.load("s3://mybucket/path/to/my/model")

load_input_example(path: Optional[str] = None) → str | None[源代码]

加载与模型一起保存的输入示例。如果没有任何示例元数据（即模型保存时没有示例），则返回 None。如果存在模型元数据但缺少示例文件，则引发 FileNotFoundError。

参数: path – 模型或运行 URI，或指向 model 目录的路径。例如 models://<model_name>/<model_version>、runs:/<run_id>/<artifact_path> 或 /path/to/model
返回: 输入示例（NumPy ndarray、SciPy csc_matrix、SciPy csr_matrix、pandas DataFrame、dict）或 None（如果模型没有示例）。

load_input_example_params(path: str)[源代码]

加载与模型一起保存的输入示例的参数。如果输入示例中没有参数，则返回 None。

参数: path – 模型目录的路径。
返回: 参数 (dict) 或 None（如果模型没有参数）。

classmethod log(artifact_path, flavor, registered_model_name=None, await_registration_for=300, metadata=None, run_id=None, resources=None, auth_policy=None, prompts=None, name: Optional[str] = None, model_type: Optional[str] = None, params: Optional[dict[str, typing.Any]] = None, tags: Optional[dict[str, typing.Any]] = None, step: int = 0, model_id: Optional[str] = None, **kwargs) → mlflow.models.model.ModelInfo[源代码]

如果未激活运行，此方法将创建一个新的激活运行。

参数

artifact_path – Deprecated. Use name instead.
flavor – 用于保存模型的模块。该模块必须具有 save_model 函数，该函数将模型持久化为有效的 MLflow 模型。
registered_model_name – 如果提供，则在 registered_model_name 下创建一个模型版本，如果给定名称的注册模型不存在，也会创建该注册模型。
await_registration_for – 等待模型版本完成创建并处于 READY 状态的秒数。默认情况下，函数等待五分钟。指定 0 或 None 可跳过等待。
metadata – {{ metadata }}
run_id – 与此模型关联的运行 ID。
resources – {{ resources }}
auth_policy – {{ auth_policy }}
prompts – {{ prompts }}
name – 模型的名称。
model_type – {{ model_type }}
params – {{ params }}
tags – {{ tags }}
step – {{ step }}
model_id – {{ model_id }}
kwargs – 传递给模型风格的额外参数。

返回

一个包含已记录模型元数据的 ModelInfo 实例。

property metadata: dict[str, typing.Any] | None

添加到模型实例的自定义元数据字典。

Getter: 检索应用于模型实例的自定义元数据。
Setter: 将自定义键值对的字典设置为模型实例
类型: Optional[Dict[str, Any]]
返回: 定义的用户元数据字典（如果已定义）。

示例

# Create and log a model with metadata to the Model Registry
from sklearn import datasets
from sklearn.ensemble import RandomForestClassifier
import mlflow
from mlflow.models import infer_signature

with mlflow.start_run():
    iris = datasets.load_iris()
    clf = RandomForestClassifier()
    clf.fit(iris.data, iris.target)
    signature = infer_signature(iris.data, iris.target)
    mlflow.sklearn.log_model(
        clf,
        name="iris_rf",
        signature=signature,
        registered_model_name="model-with-metadata",
        metadata={"metadata_key": "metadata_value"},
    )

# model uri for the above model
model_uri = "models:/model-with-metadata/1"

# Load the model and access the custom metadata
model = mlflow.pyfunc.load_model(model_uri=model_uri)
assert model.metadata.metadata["metadata_key"] == "metadata_value"

property model_size_bytes: int | None

一个可选的整数，表示模型的字节大小

Getter: 检索模型保存时计算出的模型大小
Setter: 将模型大小设置为模型实例
类型: Optional[int]

property resources: dict[str, dict[mlflow.models.resources.ResourceType, list[dict[str, typing.Any]]]]

包含模型所需资源的字典。

Getter: 检索模型所需的资源
Setter: 设置模型所需的资源
类型: Dict[str, Dict[ResourceType, List[Dict]]]

save(path) → None[源代码]: 将模型写入本地 YAML 文件。

property saved_input_example_info: dict[str, typing.Any] | None: 包含已保存输入示例元数据的字典，例如 {"artifact_path": "input_example.json", "type": "dataframe", "pandas_orient": "split"}。

property signature

对模型对象的预期输入和输出的可选定义，使用字段名称和数据类型定义。签名支持基于列的输入和基于张量的输入以及输出。

Getter: 检索模型实例的签名（如果模型已保存签名定义）。
Setter: 将签名设置为模型实例。
类型: Optional[ModelSignature]

to_dict() → dict[str, typing.Any][源代码]: 将模型序列化为字典。

to_json() → str[源代码]: 将模型写入 json。

to_yaml(stream=None) → str[源代码]: 将模型写入 yaml 字符串。

class mlflow.models.ModelConfig(*, development_config: Optional[Union[str, dict[str, typing.Any]] = None)[源代码]

Bases: object

ModelConfig 用于代码中以读取 YAML 配置文件或字典。

参数: development_config – YAML 配置文件或包含配置的字典的路径。如果未提供配置，则会引发错误

模型代码中的示例用法

from mlflow.models import ModelConfig

# Load the configuration from a dictionary
config = ModelConfig(development_config={"key1": "value1"})
print(config.get("key1"))

模型配置的 yaml 文件

key1: value1
another_key:
    - value2
    - value3

模型代码中的示例 yaml 用法

from mlflow.models import ModelConfig

# Load the configuration from a file
config = ModelConfig(development_config="config.yaml")
print(config.get("key1"))

当在模型文件中本地调用 ModelConfig 时，可以传入 development_config，它将用作模型的配置。

记录模型为代码时的 ModelConfig 示例：agent.py

import mlflow
from mlflow.models import ModelConfig

config = ModelConfig(development_config={"key1": "value1"})

class TestModel(mlflow.pyfunc.PythonModel):
    def predict(self, context, model_input, params=None):
        return config.get("key1")

mlflow.models.set_model(TestModel())

但是，当记录模型时，此 development_config 配置文件将被覆盖。当记录模型时未传入 model_config 时，尝试使用 ModelConfig 加载模型时将引发错误。注意：记录模型时不使用 development_config。

记录模型时使用 agent.py 的示例：deploy.py

model_config = {"key1": "value2"}
with mlflow.start_run():
    model_info = mlflow.pyfunc.log_model(
        name="model", python_model="agent.py", model_config=model_config
    )

loaded_model = mlflow.pyfunc.load_model(model_info.model_uri)

# This will print "value2" as the model_config passed in while logging the model
print(loaded_model.predict(None))

get(key)[源代码]: 获取配置中顶级参数的值。

to_dict()[源代码]: 将配置返回为字典。

class mlflow.models.ModelSignature(inputs: Optional[Union[mlflow.types.schema.Schema, Any]] = None, outputs: Optional[Union[mlflow.types.schema.Schema, Any]] = None, params: Optional[mlflow.types.schema.ParamSchema] = None)[源代码]

Bases: object

ModelSignature 指定模型输入的模式、输出和参数。

ModelSignature 可以从训练数据集中推断出来，使用模型预测和推理的参数，或者通过手动传入输入和输出 Schema，以及参数 ParamSchema 来构建。

classmethod from_dict(signature_dict: dict[str, typing.Any])[源代码]

从字典表示中反序列化。

参数: signature_dict – 模型签名的字典表示。预期的字典格式：{‘inputs’: <json string>, ‘outputs’: <json string>, ‘params’: <json string>” }
返回: 使用字典中的数据填充 ModelSignature。

to_dict() → dict[str, typing.Any][源代码]

序列化为“可 JSON 化”的字典。

输入和输出模式表示为 json 字符串。这样，当嵌入到 MLmodel yaml 文件中时，表示是紧凑的。

返回: 带有表示为 json 字符串的输入和输出模式的字典表示。

class mlflow.models.Resource[源代码]

Bases: abc.ABC

定义模型所需的资源的基类。

参数

type (ResourceType) – 资源类型。
target_uri (str) – 托管这些资源的 URI。

abstract classmethod from_dict(data: dict[str, str])[源代码]: 将字典转换为 Resource。子类必须实现此方法。

abstract property target_uri: str: 托管资源的 URI（必须由子类定义）。

abstract to_dict()[源代码]: 将资源转换为字典。子类必须实现此方法。

abstract property type: mlflow.models.resources.ResourceType: 资源类型（必须由子类定义）。

class mlflow.models.ResourceType(value)[源代码]

Bases: enum.Enum

枚举，用于定义服务模型所需的资源类型。

APP = 'app'

FUNCTION = 'function'

GENIE_SPACE = 'genie_space'

LAKEBASE = 'lakebase'

SERVING_ENDPOINT = 'serving_endpoint'

SQL_WAREHOUSE = 'sql_warehouse'

TABLE = 'table'

UC_CONNECTION = 'uc_connection'

VECTOR_SEARCH_INDEX = 'vector_search_index'

mlflow.models.add_libraries_to_model(model_uri, run_id=None, registered_model_name=None)[源代码]

给定一个注册的模型 URI（例如 models:/<model_name>/<model_version>），此实用程序将模型及其所有必需的模型库重新记录回模型注册表。必需的模型库与模型一起作为模型工件存储。此外，模型的支持文件（例如 conda.yaml、requirements.txt）将修改为使用添加的库。

默认情况下，此实用程序将在 model_uri 指定的同一注册模型下创建一个新的模型版本。可以通过指定 registered_model_name 参数来覆盖此行为。

参数

model_uri – 模型注册表中的注册模型 URI，格式为 models:/<model_name>/<model_version/stage/latest>
run_id – 记录带有库的模型的运行 ID。如果为 None，则模型及其库将记录到由 model_uri 指定的模型版本的源运行中；如果模型版本没有源运行，则创建一个新的运行。
registered_model_name – 新的模型版本（带库的模型）将在输入的 registered_model_name 下注册。如果为 None，则在新版本记录到模型注册表中的现有模型中。

注意

此实用程序仅对已注册到模型注册表中的模型起作用。

注意

库仅与其添加所在的平台兼容。不支持跨平台库。

示例

# Create and log a model to the Model Registry
import pandas as pd
from sklearn import datasets
from sklearn.ensemble import RandomForestClassifier
import mlflow
import mlflow.sklearn
from mlflow.models import infer_signature

with mlflow.start_run():
    iris = datasets.load_iris()
    iris_train = pd.DataFrame(iris.data, columns=iris.feature_names)
    clf = RandomForestClassifier(max_depth=7, random_state=0)
    clf.fit(iris_train, iris.target)
    signature = infer_signature(iris_train, clf.predict(iris_train))
    mlflow.sklearn.log_model(
        clf,
        name="iris_rf",
        signature=signature,
        registered_model_name="model-with-libs",
    )

# model uri for the above model
model_uri = "models:/model-with-libs/1"

# Import utility
from mlflow.models.utils import add_libraries_to_model

# Log libraries to the original run of the model
add_libraries_to_model(model_uri)

# Log libraries to some run_id
existing_run_id = "21df94e6bdef4631a9d9cb56f211767f"
add_libraries_to_model(model_uri, run_id=existing_run_id)

# Log libraries to a new run
with mlflow.start_run():
    add_libraries_to_model(model_uri)

# Log libraries to a new registered model named 'new-model'
with mlflow.start_run():
    add_libraries_to_model(model_uri, registered_model_name="new-model")

mlflow.models.build_docker(model_uri=None, name='mlflow-pyfunc', env_manager='virtualenv', mlflow_home=None, install_java=False, install_mlflow=False, enable_mlserver=False, base_image=None)[源代码]

构建一个 Docker 镜像，其默认入口点使用 python_function 风格在端口 8080 上提供 MLflow 模型。容器服务由 model_uri 引用的模型（如果指定）。如果未指定 model_uri，则必须将 MLflow 模型目录作为卷挂载到容器中的 /opt/ml/model 目录。

重要提示

自 MLflow 2.10.1 起，使用 --model-uri 构建的 Docker 镜像 不安装 Java 以提高性能，除非模型风格是 ["johnsnowlabs", "h2o" "spark"] 之一。如果您需要为其他风格（例如使用 SparkML 的自定义 Python 模型）安装 Java，请指定 install-java=True 以强制安装 Java。在早期版本中，Java 始终安装到镜像中。

警告

如果未指定 model_uri，则生成的映像不支持使用 RFunc 服务器提供模型。

注意：默认情况下，容器将启动 nginx 和 uvicorn 进程。如果您不需要启动 nginx 进程（例如，当您将容器部署到 Google Cloud Run 时），可以通过 DISABLE_NGINX 环境变量禁用它

docker run -p 5001:8080 -e DISABLE_NGINX=true "my-image-name"

有关 'python_function' 风格的更多信息，请参阅 https://www.mlflow.org/docs/latest/python_api/mlflow.pyfunc.html。

参数

model_uri – 模型的 URI。本地路径、'runs:/' URI 或远程存储 URI（例如 's3://' URI）。有关支持的用于模型工件的远程 URI 的更多信息，请参阅 https://mlflow.org.cn/docs/latest/tracking.html#artifact-stores
name – 要构建的 Docker 镜像的名称。默认为 'mlflow-pyfunc'。
env_manager – 如果指定，则使用指定的环境管理器为 MLmodel 创建环境。支持以下值：（1）virtualenv（默认）：使用 virtualenv 和 pyenv 进行 Python 版本管理（2）conda：使用 conda（3）local：使用本地环境而不创建新环境。
mlflow_home – MLflow 项目的本地克隆路径。仅用于开发。
install_java – 如果指定，则在镜像中安装 Java。默认为 False，以减少镜像大小和构建时间。需要 Java 的模型风格会自动启用此设置，例如 Spark 风格。（此参数仅在 MLflow 2.10.1 及更高版本中可用。在早期版本中，Java 始终安装到镜像中。）
install_mlflow – 如果指定并且存在要激活的 conda 或 virtualenv 环境，则在激活后将 mlflow 安装到环境中。安装的 mlflow 版本将与调用此命令时使用的版本相同。
enable_mlserver – 如果指定，则镜像将使用 Seldon MLserver 作为后端构建。
base_image – Docker 镜像的基础镜像。如果未指定，默认镜像为 UBUNTU_BASE_IMAGE = "ubuntu:22.04" 或 PYTHON_SLIM_BASE_IMAGE = "python:{version}-slim" 注意：如果使用自定义镜像，不保证镜像能正常工作。您可能会发现基于 ubuntu 镜像构建的兼容性更好。此外，您必须安装 Java 和 virtualenv 才能使镜像正常工作。

mlflow.models.convert_input_example_to_serving_input(input_example) → str | None[源代码]

用于将模型的输入示例转换为可用于评分服务器中模型推理的提供输入示例的辅助函数。

参数: input_example – 模型输入示例。支持的类型是 pandas.DataFrame、numpy.ndarray、字典（名称 -> numpy.ndarray）、列表、标量和具有 json 可序列化值的字典。
返回: 作为 json 字符串的提供输入示例

mlflow.models.evaluate(model=None, data=None, *, model_type=None, targets=None, predictions=None, dataset_path=None, feature_names=None, evaluators=None, evaluator_config=None, extra_metrics=None, custom_artifacts=None, env_manager='local', model_config=None, inference_params=None, model_id=None, _called_from_genai_evaluate=False)[源代码]

在给定数据和选定指标上评估模型性能。

此函数使用指定的 evaluators 在给定数据集上评估 PyFunc 模型或自定义可调用对象，并将结果指标和产物记录到 MLflow 跟踪服务器。用户也可以跳过设置 model 并直接在 data 中提供模型输出来进行评估。有关详细信息，请阅读模型评估文档。

默认评估器行为

默认评估器（可通过 evaluators="default" 或 evaluators=None 调用）支持下表中列出的模型类型。对于每种预定义模型类型，默认评估器都会在选定的一组指标上评估您的模型，并生成如绘图等产物。请在下面查找更多详细信息。
对于 "regressor" 和 "classifier" 这两种模型类型，默认评估器都会使用 SHAP 生成模型摘要图和特征重要性图。
对于回归模型，默认评估器还会记录
- 指标 (metrics): example_count, mean_absolute_error, mean_squared_error, root_mean_squared_error, sum_on_target, mean_on_target, r2_score, max_error, mean_absolute_percentage_error。
对于二元分类器，默认评估器还会记录
- 指标 (metrics): true_negatives, false_positives, false_negatives, true_positives, recall, precision, f1_score, accuracy_score, example_count, log_loss, roc_auc, precision_recall_auc。
- 产物 (artifacts): lift curve plot, precision-recall plot, ROC plot。
对于多类别分类器，默认评估器还会记录
- 指标 (metrics): accuracy_score, example_count, f1_score_micro, f1_score_macro, log_loss
- 产物 (artifacts): 一个 CSV 文件用于 “per_class_metrics”（每类指标包括 true_negatives/false_positives/false_negatives/true_positives/recall/precision/roc_auc, precision_recall_auc），合并的精确率-召回率曲线图，合并的 ROC 曲线图。
对于问答模型，默认评估器记录
- 指标 (metrics): exact_match, token_count, toxicity (需要安装 evaluate, torch, flesch_kincaid_grade_level (需要安装 textstat) 和 ari_grade_level。
- 产物 (artifacts): 一个 JSON 文件，其中包含模型的输入、输出、目标（如果提供了 targets 参数）以及每行的指标，以表格形式呈现。
对于文本摘要模型，默认评估器记录
- 指标 (metrics): token_count, ROUGE (需要安装 evaluate, nltk 和 rouge_score), toxicity (需要 evaluate, torch, transformers), ari_grade_level (需要 textstat), flesch_kincaid_grade_level (需要 textstat)。
- 产物 (artifacts): 一个 JSON 文件，其中包含模型的输入、输出、目标（如果提供了 targets 参数）以及每行的指标，以表格形式呈现。
对于文本模型，默认评估器记录
- 指标 (metrics): token_count, toxicity (需要 evaluate, torch, transformers), ari_grade_level (需要 textstat), flesch_kincaid_grade_level (需要 textstat)。
- 产物 (artifacts): 一个 JSON 文件，其中包含模型的输入、输出、目标（如果提供了 targets 参数）以及每行的指标，以表格形式呈现。
对于检索模型，默认评估器记录
- 指标 (metrics): precision_at_k(k), recall_at_k(k) 和 ndcg_at_k(k) - 它们都有一个默认值 retriever_k = 3。
- 产物 (artifacts): 一个 JSON 文件，其中包含模型的输入、输出、目标和每行的指标，以表格形式呈现。
对于 sklearn 模型，默认评估器还会记录通过 model.score 方法计算出的模型评估标准（例如分类器的平均准确率）。
上述指标/产物被记录到活动的 MLflow 运行中。如果不存在活动的运行，将创建一个新的 MLflow 运行来记录这些指标和产物。
此外，有关指定数据集的信息——哈希值、名称（如果指定）、路径（如果指定）以及评估它的模型的 UUID——将被记录到 mlflow.datasets 标签中。
默认评估器可用的 evaluator_config 选项包括
- log_model_explainability: 一个布尔值，指定是否记录模型可解释性洞察，默认值为 True。
- log_explainer: 如果为 True，将用于计算模型可解释性的解释器记录为模型。
  默认值为 False。
- explainability_algorithm: 一个字符串，用于指定模型可解释性的 SHAP 解释器算法。支持的算法包括：'exact', 'permutation', 'partition', 'kernel'。如果未设置，则使用具有“auto”算法的 shap.Explainer，该算法根据模型选择最佳解释器。
- explainability_nsamples: 用于计算模型可解释性洞察的样本行数。默认值为 2000。
- explainability_kernel_link: shap kernel 解释器使用的核链接函数。可用值有 "identity" 和 "logit"。默认值为 "identity"。
- max_classes_for_multiclass_roc_pr: 对于多类别分类任务，记录每类 ROC 曲线和精确率-召回率曲线的最大类别数。如果类别数大于配置的最大值，则不记录这些曲线。
- metric_prefix: 一个可选的前缀，用于添加到评估过程中产生的每个指标和产物的名称之前。
- log_metrics_with_dataset_info: 一个布尔值，指定在评估期间记录到 MLflow Tracking 的每个指标的名称中是否包含有关评估数据集的信息，默认值为 True。
- pos_label: 如果指定，则在为二元分类模型计算分类指标（如精确率、召回率、f1 等）时使用的正标签。对于多类别分类和回归模型，此参数将被忽略。
- average: 在为多类别分类模型计算分类指标（如精确率、召回率、f1 等）时使用的平均方法（默认值：'weighted'）。对于二元分类和回归模型，此参数将被忽略。
- sample_weights: 应用于每个样本以计算模型性能指标的权重。
- col_mapping: 一个字典，将输入数据集或输出预测中的列名映射到调用评估函数时使用的列名。
- retriever_k: 当 model_type="retriever" 时使用的参数，表示用于计算内置指标 precision_at_k(k), recall_at_k(k) 和 ndcg_at_k(k) 的前 k 个检索到的文档数。默认值为 3。对于所有其他模型类型，此参数将被忽略。
评估数据集的局限性
- 对于分类任务，数据集标签用于推断类总数。
- 对于二元分类任务，负标签值必须是 0 或 -1 或 False，正标签值必须是 1 或 True。
指标/产物计算的局限性
- 对于分类任务，一些指标和产物计算要求模型输出类别概率。目前，对于 scikit-learn 模型，默认评估器调用底层模型的 predict_proba 方法以获取概率。对于其他模型类型，默认评估器不计算需要概率输出的指标/产物。
默认评估器记录模型可解释性洞察的局限性
- shap.Explainer 的 auto 算法对线性模型使用 Linear 解释器，对树模型使用 Tree 解释器。由于 SHAP 的 Linear 和 Tree 解释器不支持多类别分类，默认评估器会退而求其次，对多类别分类任务使用 Exact 或 Permutation 解释器。
- 目前不支持为 PySpark 模型记录模型可解释性洞察。
- 评估数据集的标签值必须是数字或布尔值，所有特征值必须是数字，并且每个特征列只能包含标量值。
启用环境恢复时的限制
- 当为被评估模型启用环境恢复时（即指定了非本地 env_manager），模型将作为客户端加载，该客户端在具有安装了模型训练时间依赖项的独立 Python 环境中调用 MLflow 模型评分服务器进程。因此，模型的 predict_proba 方法（用于概率输出）或 score 方法（计算 sklearn 模型的评估标准）将变得不可访问，默认评估器不会计算需要这些方法的指标或产物。
- 由于模型是 MLflow 模型服务器进程，SHAP 解释的计算速度较慢。因此，当指定非本地 env_manager 时，模型可解释性默认禁用，除非 evaluator_config 选项 log_model_explainability 被明确设置为 True。

参数

model –
可选。如果指定，它应该是以下之一
- 一个 pyfunc 模型实例
- 引用 pyfunc 模型的 URI
- 引用 MLflow 部署端点的 URI，例如 "endpoints:/my-chat"
- 一个可调用函数：此函数应能接收模型输入并返回预测结果。它应遵循 predict 方法的签名。这是一个有效函数的示例
```
model = mlflow.pyfunc.load_model(model_uri)


def fn(model_input):
    return model.predict(model_input)
```
如果省略，则表示将使用静态数据集而不是模型进行评估。在这种情况下，data 参数必须是包含模型输出的 Pandas DataFrame 或 mlflow PandasDataset，并且 predictions 参数必须是 data 中包含模型输出的列的名称。
data –
以下之一
- 一个 numpy 数组或评估特征列表，不包括标签。
- 一个包含评估特征、标签以及可选模型输出的 Pandas DataFrame。
  模型输出在未指定模型时是必需的。如果未指定 feature_names 参数，则除标签列和预测列外的所有列都被视为特征列。否则，只有存在于 feature_names 中的列名才被视为特征列。
- 一个包含评估特征和标签的 Spark DataFrame。如果
  未指定 feature_names 参数，则除标签列外的所有列都被视为特征列。否则，只有存在于 feature_names 中的列名才被视为特征列。Spark DataFrame 中只有前 10000 行将被用作评估数据。
- 一个 mlflow.data.dataset.Dataset 实例，包含评估
  特征、标签以及可选的模型输出。模型输出仅支持与 PandasDataset 一起使用。在未指定模型时需要模型输出，并且应通过 PandasDataset 的 predictions 属性指定。
model_type –
（可选）描述模型类型的字符串。默认评估器支持以下模型类型
- 'classifier'
- 'regressor'
- 'question-answering'
- 'text-summarization'
- 'text'
- 'retriever'
如果没有指定 model_type，则必须通过 extra_metrics 参数提供要计算的指标列表。

注意

'question-answering', 'text-summarization', 'text' 和 'retriever' 处于实验阶段，未来版本中可能会更改或删除。
targets – 如果 data 是 numpy 数组或列表，则为评估标签的 numpy 数组或列表。如果 data 是 DataFrame，则是 data 中包含评估标签的列的字符串名称。对于分类器和回归模型是必需的，但对于问答、文本摘要和文本模型是可选的。如果 data 是定义了目标的 mlflow.data.dataset.Dataset，则 targets 是可选的。

predictions –

可选。包含模型输出的列的名称。

当 model 被指定且输出多列时，predictions 可用于指定将用于存储模型输出进行评估的列的名称。
当未指定 model 且 data 是 pandas dataframe 时，predictions 可用于指定 data 中包含模型输出的列的名称。

predictions 的用法示例

# Evaluate a model that outputs multiple columns
data = pd.DataFrame({"question": ["foo"]})


def model(inputs):
    return pd.DataFrame({"answer": ["bar"], "source": ["baz"]})


results = evaluate(
    model=model,
    data=data,
    predictions="answer",
    # other arguments if needed
)

# Evaluate a static dataset
data = pd.DataFrame({"question": ["foo"], "answer": ["bar"], "source": ["baz"]})
results = evaluate(
    data=data,
    predictions="answer",
    # other arguments if needed
)

dataset_path – （可选）数据存储的路径。不得包含双引号 (")。如果指定，该路径将记录到 mlflow.datasets 标签中，以用于血缘跟踪。
feature_names – （可选）一个列表。如果 data 参数是 numpy 数组或列表，feature_names 是每个特征的特征名称列表。如果 feature_names=None，则使用格式 feature_{feature_index} 生成 feature_names。如果 data 参数是 Pandas DataFrame 或 Spark DataFrame，feature_names 是 DataFrame 中特征列名称的列表。如果 feature_names=None，则除标签列和预测列外的所有列都被视为特征列。
evaluators – 用于模型评估的评估器名称，或评估器名称列表。如果未指定，则使用所有有能力评估指定数据集的指定模型的评估器。默认评估器可以通过名称 "default" 来引用。要查看所有可用的评估器，请调用 mlflow.models.list_evaluators()。
evaluator_config – 要提供给评估器的附加配置字典。如果指定了多个评估器，每个配置应作为嵌套字典提供，其键是评估器名称。

extra_metrics –

（可选）EvaluationMetric 对象的列表。这些指标是相对于预定义的 model_type 的默认指标额外计算的，并且设置 model_type=None 将只计算 extra_metrics 中指定的指标。有关内置指标以及如何定义额外指标的更多信息，请参阅 mlflow.metrics 模块。

extra_metrics 的用法示例

import mlflow
import numpy as np


def root_mean_squared_error(eval_df, _builtin_metrics):
    return np.sqrt((np.abs(eval_df["prediction"] - eval_df["target"]) ** 2).mean())


rmse_metric = mlflow.models.make_metric(
    eval_fn=root_mean_squared_error,
    greater_is_better=False,
)
mlflow.evaluate(..., extra_metrics=[rmse_metric])

custom_artifacts –

（可选）自定义产物函数的列表，具有以下签名

def custom_artifact(
    eval_df: Union[pandas.Dataframe, pyspark.sql.DataFrame],
    builtin_metrics: Dict[str, float],
    artifacts_dir: str,
) -> Dict[str, Any]:
    """
    Args:
        eval_df:
            A Pandas or Spark DataFrame containing ``prediction`` and ``target``
            column.  The ``prediction`` column contains the predictions made by the
            model.  The ``target`` column contains the corresponding labels to the
            predictions made on that row.
        builtin_metrics:
            A dictionary containing the metrics calculated by the default evaluator.
            The keys are the names of the metrics and the values are the scalar
            values of the metrics. Refer to the DefaultEvaluator behavior section
            for what metrics will be returned based on the type of model (i.e.
            classifier or regressor).
        artifacts_dir:
            A temporary directory path that can be used by the custom artifacts
            function to temporarily store produced artifacts. The directory will be
            deleted after the artifacts are logged.

    Returns:
        A dictionary that maps artifact names to artifact objects
        (e.g. a Matplotlib Figure) or to artifact paths within ``artifacts_dir``.
    """
    ...

产物可以表示的对象类型

表示产物文件路径的字符串 URI。MLflow 将根据文件扩展名推断产物的类型。

JSON 对象的字符串表示形式。这将保存为 .json 产物。

Pandas DataFrame。这将解析为 CSV 产物。

Numpy 数组。这将保存为 .npy 产物。

Matplotlib 图形。这将保存为图像产物。请注意，后台调用了 matplotlib.pyplot.savefig，并使用默认配置。要进行自定义，请使用所需的配置保存图形并返回其文件路径，或在 matplotlib.rcParams 中通过环境变量定义自定义设置。

其他对象将尝试使用默认协议进行 pickling。

custom_artifacts 的用法示例

import mlflow
import matplotlib.pyplot as plt


def scatter_plot(eval_df, builtin_metrics, artifacts_dir):
    plt.scatter(eval_df["prediction"], eval_df["target"])
    plt.xlabel("Targets")
    plt.ylabel("Predictions")
    plt.title("Targets vs. Predictions")
    plt.savefig(os.path.join(artifacts_dir, "example.png"))
    plt.close()
    return {"pred_target_scatter": os.path.join(artifacts_dir, "example.png")}


def pred_sample(eval_df, _builtin_metrics, _artifacts_dir):
    return {"pred_sample": pred_sample.head(10)}


mlflow.evaluate(..., custom_artifacts=[scatter_plot, pred_sample])

env_manager –
指定一个环境管理器，用于在隔离的 Python 环境中加载候选 model 并恢复其依赖项。默认值为 local，支持以下值
- virtualenv: (推荐) 使用 virtualenv 恢复用于训练模型的 python 环境。
- conda: 使用 Conda 恢复训练模型时使用的软件环境。
- local: 使用当前 Python 环境进行模型推理，这可能与训练模型时使用的环境不同，并可能导致错误或无效的预测。
model_config – 用于 pyfunc 加载模型的模型配置。检查模型的 pyfunc flavor 以了解您的特定模型支持哪些键。如果未指定，则使用模型的默认模型配置（如果存在）。
inference_params – （可选）在进行预测时传递给模型的推理参数字典，例如 {"max_tokens": 100}。这仅在 model 是 MLflow 部署端点 URI（例如 "endpoints:/my-chat"）时使用。
model_id – （可选）MLflow LoggedModel 或模型版本的 ID，评估结果（例如指标和跟踪）将链接到此 ID。如果未指定 model_id 但指定了 model，则将使用来自 model 的 ID。
_called_from_genai_evaluate – （可选）仅供内部使用。

返回

一个 mlflow.models.EvaluationResult 实例，其中包含使用给定数据集评估模型的指标。

mlflow.models.get_model_info(model_uri: str) → mlflow.models.model.ModelInfo[source]

获取指定模型的元数据，例如其输入/输出签名。

参数

model_uri –

MLflow 模型在 URI 格式中的位置。例如：

/Users/me/path/to/local/model
relative/path/to/local/model
s3://my_bucket/path/to/model
runs:/<mlflow_run_id>/run-relative/path/to/model
models:/<model_name>/<model_version>
models:/<model_name>/<stage>
mlflow-artifacts:/path/to/model

For more information about supported URI schemes, see Referencing Artifacts.

返回

一个包含已记录模型元数据的 ModelInfo 实例。

get_model_info 的用法示例

import mlflow.models
import mlflow.sklearn
from sklearn.ensemble import RandomForestRegressor

with mlflow.start_run() as run:
    params = {"n_estimators": 3, "random_state": 42}
    X = [[0, 1]]
    y = [1]
    signature = mlflow.models.infer_signature(X, y)
    rfr = RandomForestRegressor(**params).fit(X, y)
    mlflow.log_params(params)
    mlflow.sklearn.log_model(rfr, name="sklearn-model", signature=signature)

model_uri = f"runs:/{run.info.run_id}/sklearn-model"
# Get model info with model_uri
model_info = mlflow.models.get_model_info(model_uri)
# Get model signature directly
model_signature = model_info.signature
assert model_signature == signature

mlflow.models.infer_pip_requirements(model_uri, flavor, fallback=None, timeout=None, extra_env_vars=None)[source]

通过创建子进程并在其中加载模型来推断指定模型的 pip 依赖项，以确定导入了哪些包。

参数

model_uri – 模型的 URI。
flavor – 模型的 flavor 名称。
fallback – 如果提供，则会吞噬推理过程中发生的意外错误，并返回 fallback 的值。否则，将引发错误。
timeout – 如果指定，则推理操作将受超时（以秒为单位）的限制。
extra_env_vars – 要传递给子进程的额外环境变量的字典。默认为 None。

返回

推断的 pip 依赖项列表（例如 ["scikit-learn==0.24.2", ...]）。

mlflow.models.infer_signature(model_input: Any = None, model_output: MlflowInferableDataset = None, params: dict[str, typing.Any] | None = None) → mlflow.models.signature.ModelSignature[source]

根据训练数据（输入）、模型预测（输出）和参数（用于推理）推断 MLflow 模型签名。

签名将模型输入和输出表示为数据框，其中（可选地）指定了命名的列和数据类型，数据类型是 mlflow.types.DataType 中定义的一种类型。它还包括用于推理的参数 schema。如果用户数据包含不兼容的类型或未以下面列出的支持格式之一传递，此方法将引发异常。

输入应是以下之一

pandas.DataFrame
pandas.Series
字典 { 名称 -> numpy.ndarray}
numpy.ndarray
pyspark.sql.DataFrame
scipy.sparse.csr_matrix
scipy.sparse.csc_matrix
字典/JSON 可转换类型的字典列表

元素类型应可映射到 mlflow.types.DataType 之一。

对于 pyspark.sql.DataFrame 输入，DateType 和 TimestampType 类型的列都推断为 datetime 类型，该类型在推理时强制转换为 TimestampType。

参数

model_input – 模型的有效输入。例如（训练数据集的子集）。
model_output – 有效的模型输出。例如，模型对（训练数据集的子集）的预测结果。

params –

用于推理的有效参数。它应该是一个参数字典，可以在推理时通过将 params 传递给 pyfunc predict 方法来设置模型上的参数。

有效参数的一个示例

from mlflow.models import infer_signature
from mlflow.transformers import generate_signature_output

# Define parameters for inference
params = {
    "num_beams": 5,
    "max_length": 30,
    "do_sample": True,
    "remove_invalid_values": True,
}

# Infer the signature including parameters
signature = infer_signature(
    data,
    generate_signature_output(model, data),
    params=params,
)

# Saving model with model signature
mlflow.transformers.save_model(
    model,
    path=model_path,
    signature=signature,
)

pyfunc_loaded = mlflow.pyfunc.load_model(model_path)

# Passing params to `predict` function directly
result = pyfunc_loaded.predict(data, params=params)

返回

ModelSignature

mlflow.models.list_evaluators()[source]: 返回所有可用评估器的名称列表。

mlflow.models.make_metric(*, eval_fn, greater_is_better, name=None, long_name=None, version=None, metric_details=None, metric_metadata=None, genai_metric_args=None)[source]

一个工厂函数，用于创建 EvaluationMetric 对象。

参数

eval_fn –

一个计算指标的函数，具有以下签名

def eval_fn(
    predictions: pandas.Series,
    targets: pandas.Series,
    metrics: Dict[str, MetricValue],
    **kwargs,
) -> Union[float, MetricValue]:
    """
    Args:
        predictions: A pandas Series containing the predictions made by the model.
        targets: (Optional) A pandas Series containing the corresponding labels
            for the predictions made on that input.
        metrics: (Optional) A dictionary containing the metrics calculated by the
            default evaluator.  The keys are the names of the metrics and the values
            are the metric values.  To access the MetricValue for the metrics
            calculated by the system, make sure to specify the type hint for this
            parameter as Dict[str, MetricValue].  Refer to the DefaultEvaluator
            behavior section for what metrics will be returned based on the type of
            model (i.e. classifier or regressor).  kwargs: Includes a list of args
            that are used to compute the metric. These args could information coming
            from input data, model outputs or parameters specified in the
            `evaluator_config` argument of the `mlflow.evaluate` API.
        kwargs: Includes a list of args that are used to compute the metric. These
            args could be information coming from input data, model outputs,
            other metrics, or parameters specified in the `evaluator_config`
            argument of the `mlflow.evaluate` API.

    Returns: MetricValue with per-row scores, per-row justifications, and aggregate
        results.
    """
    ...

greater_is_better – 度量值越大越好的布尔值。
name – 指标的名称。如果 eval_fn 是 lambda 函数或 eval_fn.__name__ 属性不可用，则必须指定此参数。
long_name – （可选）指标的完整名称。例如，"mse" 的 "mean_squared_error"。
version – （可选）指标版本。例如 v1。
metric_details – （可选）指标及其计算方法的描述。
metric_metadata – （可选）包含指标元数据的字典。
genai_metric_args – （可选）一个字典，包含用户在调用 make_genai_metric 或 make_genai_metric_from_prompt 时指定的参数。这些参数被持久化，以便我们稍后可以反序列化相同的指标对象。

另请参阅

mlflow.models.EvaluationMetric
mlflow.evaluate()

mlflow.models.predict(model_uri, input_data=None, input_path=None, content_type='json', output_path=None, env_manager='virtualenv', install_mlflow=False, pip_requirements_override=None, extra_envs=None)[source]

使用已保存的 MLflow 模型以 json 格式生成预测。有关此函数接受的输入数据格式的信息，请参阅以下文档：https://www.mlflow.org/docs/latest/models.html#built-in-deployment-tools。

注意

为了在调试目的下增加详细程度（以便检查处理瞬态依赖项时的完整依赖项解析器操作），请考虑设置以下环境变量

# For virtualenv
export PIP_VERBOSE=1

# For uv
export RUST_LOG=uv=debug

另请参阅

参数

model_uri – 模型的 URI。本地路径、本地或远程 URI，例如 runs:/, s3://。
input_data –
用于预测的输入数据。必须是 PyFunc 模型的有效输入。有关此函数支持的输入类型，请参阅 mlflow.pyfunc.PyFuncModel.predict()。

注意

如果由于 input_data 中的错误导致此 API 失败，请使用 mlflow.models.convert_input_example_to_serving_input 手动验证您的输入数据。
input_path – 包含输入数据的文件路径。如果提供了此参数，则 ‘input_data’ 必须为 None。
content_type – 输入数据的 MIME 类型。可以是 {‘json’, ‘csv’} 中的一个。
output_path – 用于输出结果的 JSON 文件。如果未提供，则输出到 stdout。
env_manager –
指定一种为 MLmodel 推理创建环境的方法
- ”virtualenv” (默认)：使用 virtualenv（以及 pyenv 用于 Python 版本管理）
- ”uv”：使用 uv
- ”local”：使用本地环境
- ”conda”：使用 conda
install_mlflow – 如果指定并且存在要激活的 conda 或 virtualenv 环境，则在激活后将 mlflow 安装到环境中。安装的 mlflow 版本将与调用此命令时使用的版本相同。
pip_requirements_override –
如果指定，则将指定的 Python 依赖项安装到模型推理环境中。当您想添加额外依赖项或尝试日志记录模型中定义的依赖项的不同版本时，这特别有用。

提示

在验证 pip 依赖项覆盖按预期工作后，您可以使用 mlflow.models.update_model_requirements API 更新已记录模型的依赖项，而无需重新记录它。请注意，注册的模型是不可变的，因此您需要使用更新后的模型为注册的模型注册一个新版本。
extra_envs –
如果指定，一个包含额外环境变量的字典将被传递给模型推理环境。这对于测试模型正常运行所需的哪些环境变量很有用。默认情况下，会传递当前 os.environ 中存在的环境变量，并且此参数可用于覆盖它们。

注意

如果您的模型依赖项包括预发布版本，例如 mlflow==3.2.0rc0 并且您将 uv 用作环境管理器，请在 extra_envs 中将 UV_PRERELEASE 环境变量设置为 “allow”，以允许安装预发布版本。例如 extra_envs={“UV_PRERELEASE”: “allow”}。

注意

此参数仅在 env_manager 设置为 “virtualenv”、“conda” 或 “uv” 时受支持。

代码示例

import mlflow

run_id = "..."

mlflow.models.predict(
    model_uri=f"runs:/{run_id}/model",
    input_data={"x": 1, "y": 2},
    content_type="json",
)

# Run prediction with "uv" as the environment manager
mlflow.models.predict(
    model_uri=f"runs:/{run_id}/model",
    input_data={"x": 1, "y": 2},
    env_manager="uv",
)

# Run prediction with additional pip dependencies and extra environment variables
mlflow.models.predict(
    model_uri=f"runs:/{run_id}/model",
    input_data={"x": 1, "y": 2},
    content_type="json",
    pip_requirements_override=["scikit-learn==0.23.2"],
    extra_envs={"OPENAI_API_KEY": "some_value"},
)

# Run prediction with output_path
mlflow.models.predict(
    model_uri=f"runs:/{run_id}/model",
    input_data={"x": 1, "y": 2},
    env_manager="uv",
    output_path="output.json",
)

# Run prediction with pre-release versions
mlflow.models.predict(
    model_uri=f"runs:/{run_id}/model",
    input_data={"x": 1, "y": 2},
    env_manager="uv",
    extra_envs={"UV_PRERELEASE": "allow"},
)

mlflow.models.set_model(model) → None[源代码]

在将模型记录为代码时，此函数可用于设置要记录的模型对象。

参数

model –

要记录的模型对象。支持的模型类型有

一个 Python 函数或可调用对象。
一个 Langchain 模型或 Langchain 模型的路径。
一个 Llama Index 模型或 Llama Index 模型的路径。

mlflow.models.set_retriever_schema(*, primary_key: str, text_column: str, doc_uri: Optional[str] = None, other_columns: Optional[list[str]] = None, name: str | None = 'retriever')[源代码]

在您的代理或生成式 AI 应用代码中指定检索器跨度的返回架构。

自 3.3.2 版本起弃用：此函数已被弃用，将在未来版本中删除。

注意：MLflow 建议您的检索器返回 https://mlflow.org.cn/docs/latest/genai/data-model/traces/#retriever-spans 中描述的默认 MLflow 检索器输出架构，在这种情况下您无需调用 set_retriever_schema。读取 MLflow 跟踪并查找检索器跨度的 API（例如 MLflow 评估）将自动检测与 MLflow 默认检索器架构匹配的检索器跨度。

如果您的检索器未返回默认的 MLflow 检索器输出架构，请调用此 API 以指定每个检索到的文档中哪些字段对应于页面内容、文档 URI、文档 ID 等。这使得下游功能（如 MLflow 评估）能够正确识别这些字段。请注意，set_retriever_schema 假设您的检索器跨度返回一个对象列表。

参数

primary_key – 检索器或向量索引的主键。
text_column – 用于嵌入的文本列的名称。
doc_uri – 包含文档 URI 的列的名称。
other_columns – 向量索引的其他列的列表，这些列需要在跟踪日志记录期间检索。
name – 检索器工具或向量存储索引的名称。

示例

from mlflow.models import set_retriever_schema

# The following call sets the schema for a custom retriever that retrieves content from
# MLflow documentation, with an output schema like:
# [
#     {
#         'document_id': '9a8292da3a9d4005a988bf0bfdd0024c',
#         'chunk_text': 'MLflow is an open-source platform, purpose-built to assist...',
#         'doc_uri': 'https://mlflow.org.cn/docs/latest/index.html',
#         'title': 'MLflow: A Tool for Managing the Machine Learning Lifecycle'
#     },
#     {
#         'document_id': '7537fe93c97f4fdb9867412e9c1f9e5b',
#         'chunk_text': 'A great way to get started with MLflow is...',
#         'doc_uri': 'https://mlflow.org.cn/docs/latest/getting-started/',
#         'title': 'Getting Started with MLflow'
#     },
# ...
# ]
set_retriever_schema(
    primary_key="chunk_id",
    text_column="chunk_text",
    doc_uri="doc_uri",
    other_columns=["title"],
    name="my_custom_retriever",
)

mlflow.models.set_signature(model_uri: str, signature: mlflow.models.signature.ModelSignature)[源代码]

为指定的模型工件设置模型签名。

该过程涉及下载模型工件中的 MLmodel 文件（如果它不是本地的）、更新其模型签名，然后覆盖现有 MLmodel 文件。如果模型工件关联的工件存储库不允许覆盖，此函数将失败。

此外，由于模型注册表工件是只读的，因此使用 models:/ URI 方案表示的模型注册表工件与此 API 不兼容。要在模型版本上设置签名，请首先加载源模型工件。然后，使用加载的模型工件和相应的签名生成一个新的模型版本。有关在模型版本上设置签名的更多信息，请参阅此文档部分。

参数

model_uri –
MLflow 模型在 URI 格式中的位置。例如：
- /Users/me/path/to/local/model
- relative/path/to/local/model
- s3://my_bucket/path/to/model
- runs:/<mlflow_run_id>/run-relative/path/to/model
- mlflow-artifacts:/path/to/model
- models:/<model_id>
For more information about supported URI schemes, see Referencing Artifacts.

请注意，使用 models:/<name>/<version> 方案的模型 URI 不受支持。
signature – 要设置在模型上的 ModelSignature。

示例

import mlflow
from mlflow.models import set_signature, infer_signature

# load model from run artifacts
run_id = "96771d893a5e46159d9f3b49bf9013e2"
artifact_path = "models"
model_uri = f"runs:/{run_id}/{artifact_path}"
model = mlflow.pyfunc.load_model(model_uri)

# determine model signature
test_df = ...
predictions = model.predict(test_df)
signature = infer_signature(test_df, predictions)

# set the signature for the logged model
set_signature(model_uri, signature)

mlflow.models.update_model_requirements(model_uri: str, operation: Literal['add', 'remove'], requirement_list: list[str]) → None[源代码]

向模型的 conda.yaml 和 requirements.txt 文件添加或删除要求。

该过程涉及从模型工件下载这两个文件（如果它们不是本地的），使用指定的依赖项更新它们，然后覆盖现有文件。如果模型工件关联的工件存储库不允许覆盖，此函数将失败。

请注意，模型注册表 URI（即 models:/ 形式的 URI）不受支持，因为模型注册表中的工件旨在为只读。

如果要添加依赖项，函数将覆盖任何现有的重叠依赖项，否则会将新依赖项追加到现有列表中。

如果要删除依赖项，函数将忽略任何版本说明符，并删除所有指定的包名称。任何在现有文件中找不到的依赖项都将被忽略。

参数

model_uri –
MLflow 模型在 URI 格式中的位置。例如：
- /Users/me/path/to/local/model
- relative/path/to/local/model
- s3://my_bucket/path/to/model
- runs:/<mlflow_run_id>/run-relative/path/to/model
- mlflow-artifacts:/path/to/model
For more information about supported URI schemes, see Referencing Artifacts.
operation – 要执行的操作。必须是 “add” 或 “remove” 之一。
requirement_list – 要添加到模型中或从模型中删除的依赖项列表。例如：[“numpy==1.20.3”, “pandas>=1.3.3”]

mlflow.models.validate_schema(data: Union[pandas.core.frame.DataFrame, pandas.core.series.Series, numpy.ndarray, scipy.sparse._csc.csc_matrix, scipy.sparse._csr.csr_matrix, List[Any], Dict[str, Any], datetime.datetime, bool, bytes, float, int, str, pyspark.sql.dataframe.DataFrame], expected_schema: mlflow.types.schema.Schema) → None[源代码]

验证输入数据是否具有预期的架构。

参数

data –
要验证的输入数据。支持的类型有
- pandas.DataFrame
- pandas.Series
- numpy.ndarray
- scipy.sparse.csc_matrix
- scipy.sparse.csr_matrix
- List[Any]
- Dict[str, Any]
- str
expected_schema – 输入数据的预期架构。

引发

mlflow.exceptions.MlflowException – 当输入数据与架构不匹配时。

validate_schema 的用法示例

import mlflow.models

# Suppose you've already got a model_uri
model_info = mlflow.models.get_model_info(model_uri)
# Get model signature directly
model_signature = model_info.signature
# validate schema
mlflow.models.validate_schema(input_data, model_signature.inputs)

mlflow.models.validate_serving_input(model_uri: str, serving_input: str | dict[str, typing.Any])[源代码]

在提供模型进行服务之前，用于验证模型是否可以被服务以及提供的输入是否有效的帮助函数。

参数

model_uri – 要服务的模型的 URI。
serving_input – 要验证的输入数据。应为字典或 JSON 字符串。

返回

模型的预测结果。

类 mlflow.models.model.ModelInfo(artifact_path: str, flavors: dict[str, typing.Any], model_uri: str, model_uuid: str, run_id: str, saved_input_example_info: dict[str, typing.Any] | None, signature, utc_time_created: str, mlflow_version: str, metadata: Optional[dict[str, typing.Any]] = None, registered_model_version: Optional[int] = None, env_vars: Optional[list[str]] = None, prompts: Optional[list[str]] = None, logged_model: Optional[LoggedModel] = None)[源代码]

已记录的 MLflow 模型的元数据。

属性 artifact_path: str

识别已记录模型的运行相对路径。

Getter: 检索已记录模型的相对路径。
类型: str

属性 creation_timestamp: int

返回已记录模型的创建时间戳。

Getter: 已记录模型的创建时间戳

属性 env_vars: list[str] | None

模型日志记录过程中使用的环境变量。

Getter: 获取模型日志记录过程中使用的环境变量。
类型: Optional[List[str]]

属性 flavors: dict[str, typing.Any]

一个字典，将已记录模型的 flavor 名称映射到如何以该 flavor 提供模型服务。

Getter: 获取定义了模型服务参数的已记录模型的 flavor 映射
类型: Dict[str, str]

scikit-learn 已记录模型的示例 flavor 映射

{
    "python_function": {
        "model_path": "model.pkl",
        "loader_module": "mlflow.sklearn",
        "python_version": "3.8.10",
        "env": "conda.yaml",
    },
    "sklearn": {
        "pickled_model": "model.pkl",
        "sklearn_version": "0.24.1",
        "serialization_format": "cloudpickle",
    },
}

属性 metadata: dict[str, typing.Any] | None

添加到模型的用户定义元数据。

Getter: 获取模型的用户定义元数据
类型: Optional[Dict[str, Any]]

模型元数据用法示例

# Create and log a model with metadata to the Model Registry

from sklearn import datasets
from sklearn.ensemble import RandomForestClassifier
import mlflow
from mlflow.models import infer_signature

with mlflow.start_run():
    iris = datasets.load_iris()
    clf = RandomForestClassifier()
    clf.fit(iris.data, iris.target)
    signature = infer_signature(iris.data, iris.target)
    mlflow.sklearn.log_model(
        clf,
        name="iris_rf",
        signature=signature,
        registered_model_name="model-with-metadata",
        metadata={"metadata_key": "metadata_value"},
    )

# model uri for the above model
model_uri = "models:/model-with-metadata/1"

# Load the model and access the custom metadata from its ModelInfo object
model = mlflow.pyfunc.load_model(model_uri=model_uri)
assert model.metadata.get_model_info().metadata["metadata_key"] == "metadata_value"

# Load the ModelInfo and access the custom metadata
model_info = mlflow.models.get_model_info(model_uri=model_uri)
assert model_info.metadata["metadata_key"] == "metadata_value"

属性 metrics: list[Metric] | None

返回已记录模型的指标。

Getter: 检索已记录模型的指标

属性 mlflow_version: str

记录模型时使用的 MLflow 版本

Getter: 获取模型记录时安装的 MLflow 版本
类型: str

属性 model_id: str

已记录模型的模型 ID。

Getter: 获取已记录模型的模型 ID

属性 model_uri: str

已记录模型的 model_uri，格式为 'runs:/<run_id>/<artifact_path>'。

Getter: 从 URI runs:/<run_id> 路径封装获取已记录模型的 URI 路径
类型: str

属性 model_uuid: str

已记录模型的 model_uuid，例如 '39ca11813cfc46b09ab83972740b80ca'。

Getter: [旧版] 获取已记录模型的 model_uuid (run_id)
类型: str

属性 name: str: 返回已记录模型的名称。

属性 params: dict[str, str]

返回已记录模型的参数。

Getter: 检索已记录模型的参数

属性 prompts: list[str] | None: 与模型关联的提示 URI 列表。

属性 registered_model_version: int | None

如果模型已注册，则是注册的模型版本。

Getter: 获取注册的模型版本（如果模型已在模型注册表中注册）。
Setter: 设置注册的模型版本。
类型: Optional[int]

属性 run_id: str

与已记录模型关联的 run_id，例如 '8ede7df408dd42ed9fc39019ef7df309'

Getter: 获取已记录模型的 run_id 标识符
类型: str

属性 saved_input_example_info: dict[str, typing.Any] | None

包含已保存输入示例元数据的字典，例如 {"artifact_path": "input_example.json", "type": "dataframe", "pandas_orient": "split"}。

Getter: 获取模型记录期间指定的输入示例
类型: Optional[Dict[str, str]]

属性 signature

描述模型输入和输出的 ModelSignature。

Getter: 获取模型签名（如果已定义）
类型: Optional[ModelSignature]

属性 tags: dict[str, str]

返回已记录模型的标签。

Getter: 检索已记录模型的标签

属性 utc_time_created: str

创建已记录模型的 UTC 时间，例如 '2022-01-12 05:17:31.634689'。

Getter: 获取模型记录时的 UTC 格式时间戳
类型: str