访问官网
Github
Huggingface
文档
论文Fortuna #######
.. image:: https://img.shields.io/pypi/status/Fortuna :target: https://img.shields.io/pypi/status/Fortuna :alt: PyPI - 状态 .. image:: https://img.shields.io/pypi/dm/aws-fortuna :target: https://pypistats.org/packages/aws-fortuna :alt: PyPI - 下载量 .. image:: https://img.shields.io/pypi/v/aws-fortuna :target: https://img.shields.io/pypi/v/aws-fortuna :alt: PyPI - 版本 .. image:: https://img.shields.io/github/license/awslabs/Fortuna :target: https://github.com/awslabs/Fortuna/blob/main/LICENSE :alt: 许可证 .. image:: https://readthedocs.org/projects/aws-fortuna/badge/?version=latest :target: https://aws-fortuna.readthedocs.io :alt: 文档状态
不确定性量化库
在涉及关键决策的应用中,准确估计预测的不确定性至关重要。不确定性可用于评估模型预测的可靠性,触发人工干预,或决定模型是否可以安全部署在实际环境中。
Fortuna 是一个不确定性量化库,可以让用户轻松运行基准测试并将不确定性引入生产系统。Fortuna 提供了从任何框架编写的预训练模型开始的校准和一致性方法,并进一步支持从 Flax 编写的深度学习模型开始的多种贝叶斯推理方法。该语言的设计对不熟悉不确定性量化的从业者来说直观易用,同时具有高度的可配置性。
查看 文档 以获取快速入门、示例和参考。
使用模式
Fortuna 提供三种不同的使用模式: 从不确定性估计开始, 从模型输出开始 和 从 Flax 模型开始。 这些模式根据用户自身应用的限制条件来服务用户。 它们的流程如下图所示,每种模式都从一个绿色面板开始。
.. image:: https://github.com/awslabs/fortuna/raw/main/docs/source/_static/pipeline.png :target: https://github.com/awslabs/fortuna/raw/main/docs/source/_static/pipeline.png
从不确定性估计开始
从不确定性估计开始具有最低的兼容性要求,是与库交互最快捷的方式。 这种使用模式为分类和回归提供了一致性预测方法。 这些方法将不确定性估计作为输入, 并返回保持用户给定概率水平的严格预测集。 在一维回归任务中,一致性集可以被视为经过校准的置信区间或可信区间。
请注意,如果您提供的输入不确定性估计不准确, 一致性集可能会很大且无法使用。 因此,如果您的应用允许, 请考虑使用 从模型输出开始 和 从 Flax 模型开始 的使用模式。
示例假设您想要校准覆盖误差为 :code:error 的可信区间,
每个区间对应一个不同的测试输入变量。
我们假设可信区间以下界和上界数组的形式传入,
分别为 :code:test_lower_bounds 和 :code:test_upper_bounds。
您还有针对多个验证输入计算的可信区间的下界和上界,
分别为 :code:val_lower_bounds 和 :code:val_upper_bounds。
相应的验证目标数组记为 :code:val_targets。
以下代码生成 一致性预测区间,
即您的测试可信区间的校准版本。
.. code-block:: python
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)
从模型输出开始
从模型输出开始假设您已经在某个框架中训练了模型,
并以 :code:numpy.ndarray 格式为每个输入数据点提供模型输出到 Fortuna。
这种使用模式允许您校准模型输出,估计不确定性,
计算指标并获得一致性集。
与 从不确定性估计开始 的使用模式相比, 这种模式提供了更好的控制, 因为它可以确保不确定性估计已经过适当校准。 然而,如果模型是通过经典方法训练的, 所得到的模型(又称认知)不确定性量化可能不佳。 为了缓解这个问题,请考虑使用 从 Flax 模型开始 的使用模式。
示例
假设您有验证和测试模型输出,
分别为 :code:val_outputs 和 :code:test_outputs。
此外,您还有一些验证和目标变量数组,
分别为 :code:val_targets 和 :code:test_targets。
以下代码提供了一个最小化的分类示例,用于获取经校准的预测熵估计。
.. code-block:: python
from fortuna.output_calib_model import OutputCalibClassifier calib_model = OutputCalibClassifier() status = calib_model.calibrate(outputs=val_outputs, targets=val_targets) test_entropies = calib_model.predictive.entropy(outputs=test_outputs)
从 Flax 模型开始
从 Flax 模型开始比 从不确定性估计开始 和 从模型输出开始 的使用模式 有更高的兼容性要求, 因为它需要使用 Flax 编写的深度学习模型。 然而,它使您能够用可扩展的贝叶斯推理程序替代标准模型训练, 这可能会显著改善预测不确定性的量化。
示例假设您有一个从输入到 logits 的 Flax 分类深度学习模型 :code:model,其输出维度为 :code:output_dim。此外,
您有一些训练、验证和校准用的 TensorFlow 数据加载器,分别为 :code:train_data_loader、:code:val_data_loader
和 :code:test_data_loader。
以下代码提供了一个最小化的分类示例,用于获取经校准的概率估计。
.. code-block:: python
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
.. code-block::
pip install aws-fortuna
或者,您可以使用 Poetry 构建软件包。 如果您选择这种方式,首先安装 Poetry 并将其添加到 PATH 中 (参见 这里)。然后输入
.. code-block::
poetry install
所有依赖项将以所需版本安装。考虑在上述命令中添加以下标志:
- :code:
-E transformers如果您想使用来自 Hugging Face 的模型和数据集。 - :code:
-E sagemaker如果您想安装在 Amazon SageMaker 上运行 Fortuna 所需的依赖项。 - :code:
-E docs如果您想安装用于构建文档的 Sphinx 依赖项。 - :code:
-E notebooks如果您想使用 Jupyter notebooks。
最后,您可以通过输入 :code:poetry shell 访问 Poetry 创建的虚拟环境,
或使用 :code:run 命令在虚拟环境中执行命令,例如 :code:poetry run python。
示例
在 /examples 目录中可以找到多个使用示例。
Amazon SageMaker 集成
我们提供了一个简单的流程,允许您以最小的努力在 Amazon SageMaker 上运行 Fortuna。
-
创建一个 AWS 账户 - 这是免费的! 存储账户 ID 和您想要启动训练作业的区域。
-
首先,更新您的本地 AWS 凭证。 然后您需要构建并 将 Docker 镜像推送到 Amazon ECR 存储库。 这个 脚本 将帮助您完成这个过程 - 它需要您的 AWS 账户 ID 和区域。如果您需要在 Docker 镜像中包含其他软件包, 您应该考虑自定义 Dockerfile。 注意: 该脚本已在 M1 MacOS 上测试过。 不同的操作系统可能需要小的修改。
-
创建一个 S3 存储桶。 您将需要这个来存储从 Amazon Sagemaker 训练作业中得到的结果。
-
编写一个配置
yaml文件。这将包括您的 AWS 详细信息、您想在 Amazon SageMaker 上运行的入口点脚本的路径、要传递给脚本的参数、您想存储结果的 S3 存储桶的路径、要监控的指标等。 查看 这个文件 作为示例。 -
最后,给定 :code:
config_dir,即主配置目录的绝对路径, 和 :code:config_filename,即主配置文件的名称(不带 .yaml 扩展名), 进入 Python 并运行以下代码:
.. code-block:: python
from fortuna.sagemaker import run_training_job
run_training_job(config_dir=config_dir, config_filename=config_filename)
资料
引用 Fortuna
如需引用 Fortuna:
.. code-block::
@article{detommaso2023fortuna,
title={Fortuna: A Library for Uncertainty Quantification in Deep Learning},
author={Detommaso, Gianluca and Gasparin, Alberto and Donini, Michele and Seeger, Matthias and Wilson, Andrew Gordon and Archambeau, Cedric},
journal={arXiv preprint arXiv:2302.04019},
year={2023}
}
贡献
如果您希望为项目做出贡献,请参阅我们的 贡献指南。
许可证
本项目采用 Apache-2.0 许可证。 有关更多信息,请参阅 LICENSE。
