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 运行（Run）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, 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, 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 环境。准备完成后，调用预测或服务应能快速响应。

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

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

参数

model_uri – 指向用于评分的 MLflow 模型的 URI。
port – 用于模型部署的端口。
host – 用于模型部署的主机。默认为 localhost。
timeout – 服务请求的超时时间（秒）。默认为 60。
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 –
（可选）表示指标值阈值的数字。
- 如果指标越大越好，则指标值必须 >= 阈值才能通过验证。
- 否则，指标值必须 <= 阈值才能通过验证。
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.14.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()[源码]: 当且仅当模型使用模式定义保存时，检索模型的输入模式。

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

get_output_schema()[源码]: 当且仅当模型使用模式定义保存时，检索模型的输出模式。

get_params_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 – 模型目录的路径。
返回: params (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

传递给模型并存储在 MLmodel 文件中的自定义元数据字典。

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

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

参数: 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, 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 字符串>, ‘outputs’: <json 字符串>, ‘params’: <json 字符串>” }
返回: 填充了字典数据的 ModelSignature。

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

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

输入和输出模式表示为 JSON 字符串。这是为了确保在嵌入 MLmodel yaml 文件时表示形式紧凑。

返回: 输入和输出模式表示为 JSON 字符串的字典表示形式。

class mlflow.models.Resource[源码]

基类：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)[源码]

基类：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)[源码]

给定一个已注册的 model_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, base_image=None)[源码]

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

重要提示

从 MLflow 2.10.1 开始，除非模型风格为 ["johnsnowlabs", "h2o", "spark"] 之一，否则使用 --model-uri 构建的 Docker 镜像 **不会安装 Java**，以提高性能。如果您需要为其他风格安装 Java（例如使用 SparkML 的自定义 Python 模型），请指定 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 版本将与调用此命令的版本相同。
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、字典 (name -> 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 生成模型摘要图和特征重要性图。
对于回归模型，默认评估器额外记录
- 指标：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。
对于二分类器，默认评估器额外记录
- 指标：true_negatives、false_positives、false_negatives、true_positives、recall、precision、f1_score、accuracy_score、example_count、log_loss、roc_auc、precision_recall_auc。
- 工件：提升曲线图、精确率-召回率图、ROC 图。
对于多分类器，默认评估器额外记录
- 指标：accuracy_score、example_count、f1_score_micro、f1_score_macro、log_loss
- 工件：“per_class_metrics” 的 CSV 文件（每类指标包括 true_negatives/false_positives/false_negatives/true_positives/recall/precision/roc_auc、precision_recall_auc）、精确率-召回率合并曲线图、ROC 合并曲线图。
对于问答模型，默认评估器记录
- 指标：exact_match、token_count、toxicity（需要 evaluate, torch）、flesch_kincaid_grade_level（需要 textstat）和 ari_grade_level。
- 工件：包含模型输入、输出、目标（如果提供了 targets 参数）以及表格格式的每行指标的 JSON 文件。
对于文本摘要模型，默认评估器记录
- 指标：token_count、ROUGE（需要安装 evaluate, nltk 和 rouge_score）、toxicity（需要 evaluate, torch, transformers）、ari_grade_level（需要 textstat）、flesch_kincaid_grade_level（需要 textstat）。
- 工件：包含模型输入、输出、目标（如果提供了 targets 参数）以及表格格式的每行指标的 JSON 文件。
对于文本模型，默认评估器记录
- 指标：token_count（词元计数）、toxicity（毒性，需要 evaluate, torch, transformers）、ari_grade_level（自动可读性指数，需要 textstat）、flesch_kincaid_grade_level（Flesch-Kincaid 年级水平，需要 textstat）。
- 工件：包含模型输入、输出、目标（如果提供了 targets 参数）以及表格格式的每行指标的 JSON 文件。
对于检索器模型，默认评估器会记录
- 指标：precision_at_k(k)、recall_at_k(k) 和 ndcg_at_k(k) - 所有指标的默认值均为 retriever_k = 3。
- 工件：一个包含模型输入、输出、目标以及表格形式的各行指标的 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 核解释器使用的核连接函数。可用值为“identity”和“logit”。默认值为“identity”。
- max_classes_for_multiclass_roc_pr：对于多分类任务，记录各类别 ROC 曲线和精确率-召回率（Precision-Recall）曲线的最大类别数。如果类别数超过配置的最大值，则不会记录这些曲线。
- 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) 时要使用的排名靠前的检索文档数量。默认值为 3。对于所有其他模型类型，此参数将被忽略。
评估数据集的局限性
- 对于分类任务，数据集标签用于推断总类别数。
- 对于二分类任务，负标签值必须为 0、-1 或 False，正标签值必须为 1 或 True。
指标/工件计算的局限性
- 对于分类任务，某些指标和工件的计算需要模型输出类概率。目前，对于 scikit-learn 模型，默认评估器会调用底层模型的 predict_proba 方法来获取概率。对于其他模型类型，默认评估器不会计算需要概率输出的指标/工件。
默认评估器记录模型可解释性见解的局限性
- SHAP 的 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 Deployments 端点的 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_names 使用 feature_{feature_index} 格式生成。如果 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 Figure。这将保存为图像工件。请注意，系统后台会以默认配置调用 matplotlib.pyplot.savefig。若需自定义，可使用所需配置保存图形并返回其文件路径，或通过 matplotlib.rcParams 中的环境变量定义自定义设置。

其他对象将尝试使用默认协议进行序列化 (pickle)。

自定义工件的用法示例

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 风味以了解您的特定模型支持哪些键。如果未注明，则使用模型的默认模型配置（如有）。
inference_params – (可选) 在进行预测时传递给模型的推理参数字典，例如 {"max_tokens": 100}。这仅在 model 为 MLflow Deployments 端点 URI 时使用，例如 "endpoints:/my-chat"。
model_id – (可选) 评估结果（例如指标和追踪）将链接到的 MLflow LoggedModel 或模型版本的 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, uv_project_dir=None, uv_groups=None, uv_extras=None)[source]

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

如果检测到 uv 项目（包含 uv.lock 和 pyproject.toml），此函数将首先尝试通过 uv export 导出依赖项。如果成功，则返回这些要求。否则，将回退到通过在模型推理期间捕获导入的包来推断依赖项。

参数

model_uri – 模型 URI。
flavor – 模型风味名称。
fallback – 如果提供此参数，推理过程中出现的意外错误将被吞没并返回 fallback 的值。否则，将抛出错误。
timeout – 如果指定，推理操作将受超时限制（单位为秒）。
extra_env_vars – 传递给子进程的额外环境变量字典。默认为 None。
uv_project_dir – uv 项目目录的显式路径。提供时，会覆盖 MLFLOW_UV_AUTO_DETECT 环境变量并搜索指定目录而非当前工作目录 (cwd)。默认为 None（自动从当前工作目录检测）。
uv_groups – 导出需求时包含的可选 uv 依赖组列表。映射到 uv export --group <name>。
uv_extras – 导出需求时包含的可选 uv extras（可选依赖集）列表。映射到 uv export --extra <name>。

返回

推断出的 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 中定义的类型之一。它还包括推理的参数模式。如果用户数据包含不兼容的类型或未以列出的支持格式之一传递，此方法将抛出异常。

输入应为以下类型之一：

pandas.DataFrame
pandas.Series
{ name -> 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 方法在推理期间在模型上进行设置。

有效参数示例：

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

import mlflow

# For transformers models, pass input_example directly to
# log_model/save_model to automatically infer the signature:
mlflow.transformers.save_model(
    model,
    path=model_path,
    input_example=(data, params),
)

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() 了解支持的输入类型。

注意

如果此 API 因 input_data 中的错误而失败，请使用 mlflow.models.convert_input_example_to_serving_input 手动验证您的输入数据。
input_path – 包含输入数据的文件路径。如果提供此参数，‘input_data’ 必须为 None。
content_type – 输入数据的内容类型。可以是 {‘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[source]

当以代码形式记录模型时，此函数可用于设置要记录的模型对象。

参数

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')[source]

指定代理或生成式 AI 应用代码中检索器 Span 的返回模式。

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

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

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

参数

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)[source]

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

此过程涉及下载模型工件中的 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[source]

从模型的 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[source]

验证输入数据是否具有预期的模式。

参数

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])[source]

警告

mlflow.models.utils.validate_serving_input 自 3.13.0 版本起弃用。此方法将在未来版本中删除。请改用 mlflow.models.predict。

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

注意

此 API 已弃用。请改用 mlflow.models.predict()，它通过在与服务环境密切镜像的隔离环境（例如使用 env_manager="uv"）中运行预测来验证输入示例。

参数

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

返回

来自模型的预测结果。

class 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)[source]

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

property artifact_path: str

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

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

property creation_timestamp: int

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

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

property env_vars: list[str] | None

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

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

property flavors: dict[str, typing.Any]

一个字典，将风味名称映射到如何以该风味提供模型。

Getter: 获取已记录模型风味的映射，该映射定义了模型服务中使用的参数
类型: Dict[str, str]

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

{
    "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",
    },
}

property 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"

property metrics: list[Metric] | None

返回已记录模型的指标。

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

property mlflow_version: str

用于记录模型的 MLflow 版本

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

property model_id: str

已记录模型的模型 ID。

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

property model_uri: str

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

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

property model_uuid: str

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

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

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

property params: dict[str, str]

返回已记录模型的参数。

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

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

property registered_model_version: int | None

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

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

property run_id: str

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

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

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

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

Getter: 如果模型在记录时指定了输入示例，则获取该输入示例
类型: Optional[Dict[str, str]]

property signature

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

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

property tags: dict[str, str]

返回已记录模型的标签。

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

property utc_time_created: str

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

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