Fortuna

PyPI - Status PyPI - Downloads PyPI - Version License Documentation Status

不确定性量化库

预测不确定性的正确估计在涉及关键决策的应用中至关重要。 不确定性可用于评估模型预测的可靠性,触发人为干预, 或决定模型是否可以在实际环境中安全部署。

Fortuna 提供了模型预测的校准不确定性估计,适用于分类和回归任务。 它设计得易于使用, 并旨在促进在生产系统中轻松估计不确定性。

快速开始

Fortuna 提供了三种不同的使用模式: 从不确定性估计从模型输出从 Flax 模型。 这些模式根据用户自身应用程序的约束条件为用户提供服务。 它们的流程如下图所示,每个流程都从其中一个绿色面板开始。

_images/pipeline.png

以下部分简要介绍了每种使用模式。 有关更多详细信息,请参阅使用模式

从不确定性估计

从不确定性估计开始具有最小的兼容性要求,并且这是与库交互的最快级别。 这种使用模式为分类和回归提供了保形预测方法。 这些方法在输入中接受不确定性估计, 并返回保留用户给定概率水平的严格预测集。 在一维回归任务中,保形集可以被视为置信区间或可信区间的校准版本。

请注意,如果您在输入中提供的不确定性估计不准确, 保形集可能会很大且无法使用。 因此,如果您的应用程序允许, 请考虑使用从模型输出从Flax模型的使用模式。

示例。 假设您想要校准具有覆盖误差 error 的可信区间, 每个区间对应不同的测试输入变量。 我们假设可信区间作为下限和上限的数组传递, 分别为 test_lower_boundstest_upper_bounds。 您还有为多个验证输入计算的可信区间的下限和上限, 分别为 val_lower_boundsval_upper_bounds。 相应的验证目标数组由 val_targets 表示。 以下代码生成 保形预测区间, 即您测试可信区间的校准版本。

from fortuna.conformal import QuantileConformalRegressor
conformal_intervals = QuantileConformalRegressor().conformal_interval(
      val_lower_bounds=val_lower_bounds, val_upper_bounds=val_upper_bounds,
      test_lower_bounds=test_lower_bounds, test_upper_bounds=test_upper_bounds,
      val_targets=val_targets, error=error)

从模型输出

从模型输出开始,假设您已经在某个框架中训练了一个模型,并且以numpy.ndarray格式为每个输入数据点提供模型输出到Fortuna。这种使用模式允许您校准模型输出,估计不确定性,计算指标并获得符合集。

From uncertainty estimates使用模式相比, 这种模式提供了更好的控制, 因为它可以确保不确定性估计已经适当校准。 然而,如果模型是用传统方法训练的, 模型(也称为认知)不确定性的量化可能较差。 为了缓解这个问题,请考虑From Flax models 使用模式。

示例。 假设你有校准和测试模型的输出, 分别是 calib_outputstest_outputs。 此外,你还有一些校准目标变量的数组 calib_targets。 以下代码提供了一个最小的分类示例,以获取校准的预测熵估计。

from fortuna.output_calib_model import OutputCalibClassifier
calib_model = OutputCalibClassifier()
status = calib_model.calibrate(calib_outputs=calib_outputs, calib_targets=calib_targets)
test_entropies = calib_model.predictive.entropy(outputs=test_outputs)

从Flax模型

从Flax模型开始,其兼容性要求比从不确定性估计从模型输出使用模式更高,因为它需要以Flax编写的深度学习模型。然而,它使您能够用可扩展的贝叶斯推理程序替换标准模型训练,这可能会显著改善预测不确定性的量化。

示例。 假设你有一个从输入到逻辑值的Flax分类深度学习模型 model,其输出维度由 output_dim 给出。此外,你有一些训练、验证和校准的TensorFlow数据加载器 train_data_loaderval_data_loadertest_data_loader。以下代码提供了一个最小的分类示例,以获得校准的概率估计。

from fortuna.data import DataLoader
train_data_loader = DataLoader.from_tensorflow_data_loader(train_data_loader)
calib_data_loader = DataLoader.from_tensorflow_data_loader(val_data_loader)
test_data_loader = DataLoader.from_tensorflow_data_loader(test_data_loader)

from fortuna.prob_model import ProbClassifier
prob_model = ProbClassifier(model=model)
status = prob_model.train(train_data_loader=train_data_loader, calib_data_loader=calib_data_loader)
test_means = prob_model.predictive.mean(inputs_loader=test_data_loader.to_inputs_loader())

安装

注意: 在安装Fortuna之前,您需要在您的虚拟环境中安装JAX

您可以通过输入以下命令来安装Fortuna

pip install aws-fortuna

或者,您可以使用Poetry构建包。 如果您选择这种方式,首先安装Poetry并将其添加到您的PATH中 (参见这里)。然后输入

poetry install

所有依赖项将以其所需版本安装。 如果您还想安装可选的Sphinx依赖项以构建文档, 请在上面的命令中添加标志-E docs。 最后,您可以通过输入poetry shell访问Poetry创建的虚拟环境, 或者使用run命令在虚拟环境中执行命令,例如poetry run python

许可证

本项目遵循Apache-2.0许可证。