Sacred

| *每个实验都是神圣的*
| *每个实验都很棒*
| *如果一个实验被浪费了*
| *上帝会非常生气*

|pypi| |py_versions| |license| |rtfd| |doi|

|build| |coverage| |code_quality| |black|

Sacred 是一款帮助你配置、组织、记录和复现实验的工具。它旨在处理围绕实际实验所需的所有繁琐的额外工作，以便：

• 跟踪实验的所有参数
• 轻松地以不同设置运行实验
• 将每次运行的配置保存到数据库中
• 复现你的结果

Sacred 通过以下主要机制实现这些目标：

• 配置作用域：一种非常方便的方式，允许在函数中使用局部变量来定义实验所使用的参数。
• 配置注入：你可以从任何函数访问配置中的所有参数，它们会按名称自动注入。
• 命令行界面：为每个实验提供一个功能强大的命令行界面，可用于更改参数并运行不同的变体。
• 观察者：Sacred 提供观察者，用于记录关于实验的各种信息，包括其依赖项、所使用的配置、运行机器以及结果等。这些信息可以保存到 MongoDB 中，便于日后访问。
• 自动种子设置有助于控制实验中的随机性，从而确保结果可重复。

示例

+------------------------------------------------+--------------------------------------------+ | 在鸢尾花数据集上训练 SVM 的脚本 | 相同的脚本作为 Sacred 实验 | +------------------------------------------------+--------------------------------------------+ | .. code:: python | .. code:: python | | | | | from numpy.random import permutation | from numpy.random import permutation | | from sklearn import svm, datasets | from sklearn import svm, datasets | | | from sacred import Experiment | | | ex = Experiment('iris_rbf_svm') | | | | | | @ex.config | | | def cfg(): | | C = 1.0 | C = 1.0 | | gamma = 0.7 | gamma = 0.7 | | | | | | @ex.automain | | | def run(C, gamma): | | iris = datasets.load_iris() | iris = datasets.load_iris() | | perm = permutation(iris.target.size) | per = permutation(iris.target.size) | | iris.data = iris.data[perm] | iris.data = iris.data[per] | | iris.target = iris.target[perm] | iris.target = iris.target[per] | | clf = svm.SVC(C=C, kernel='rbf', | clf = svm.SVC(C=C, kernel='rbf', | | gamma=gamma) | gamma=gamma) | | clf.fit(iris.data[:90], | clf.fit(iris.data[:90], | | iris.target[:90]) | iris.target[:90]) | | print(clf.score(iris.data[90:], | return clf.score(iris.data[90:], | | iris.target[90:])) | iris.target[90:]) | +------------------------------------------------+--------------------------------------------+

文档

文档托管在 ReadTheDocs <http://sacred.readthedocs.org/>_ 上。你也可以 向 Sacred Guru 提问 <https://gurubase.io/g/sacred>_，这是一个专注于 Sacred 的 AI 助手，可以回答你的问题。

安装

你可以直接从 Python 包索引使用 pip 安装：

pip install sacred

或者，如果你想手动安装，可以从 git 克隆当前版本并自行安装：

| git clone https://github.com/IDSIA/sacred.git | cd sacred | python setup.py install

你可能还需要安装 numpy 和 pymongo 包。它们是可选依赖项，但提供了许多有用的功能：

pip install numpy pymongo

测试

Sacred 的测试使用 pytest <http://pytest.org/latest/>_ 包。你可以在 Sacred 目录下运行 pytest 来执行测试：

pytest

此外，还有一个针对 tox <https://tox.readthedocs.io/en/latest/>_ 的配置文件，因此你可以自动为不同版本的 Python 运行测试：

tox

更新 pytest 版本 +++++++++++++++++++++

如果你更新或更改 pytest 版本，需要修改以下文件：

• dev-requirements.txt
• tox.ini
• test/test_utils.py
• setup.py

贡献

如果你发现了一个 bug、有一个功能请求，或者想讨论一些通用的问题，欢迎在 GitHub 仓库的议题页面 <https://github.com/IDSIA/sacred/issues>_ 上提交。如果你有关于 Sacred 使用的具体问题，请在 StackOverflow 上使用 python-sacred 标签 <https://stackoverflow.com/questions/tagged/python-sacred>_ 提问。我们非常重视文档工作。如果你发现有需要添加到文档的内容，请自行补充文档或告诉我们缺少什么。如果你在自己的项目中使用了 Sacred，并希望与他人分享代码，请将你的仓库添加到 使用 Sacred 的项目列表 <docs/projects_using_sacred.rst>_ 中。我们非常欢迎 Pull 请求！

前端

目前有三个我所知的 Sacred 数据库条目的前端界面，它们都是由外部独立开发的项目。

Omniboard <https://github.com/vivekratnavel/omniboard>_ +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ .. image:: docs/images/omniboard-table.png .. image:: docs/images/omniboard-metric-graphs.png

Omniboard 是一个 Web 仪表板，用于可视化 Sacred 收集的实验、指标和日志。Omniboard 使用 React、Node.js、Express 和 Bootstrap 构建。

Incense <https://github.com/JarnoRFB/incense>_ +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ .. image:: docs/images/incense-artifact.png .. image:: docs/images/incense-metric.png

Incense 是一个 Python 库，用于从 MongoDB 中检索存储的运行记录，并在 Jupyter 笔记本中交互式地展示指标和工件。

Sacredboard <https://github.com/chovanecm/sacredboard>_ +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ .. image:: docs/images/sacredboard.png

Sacredboard 是一个基于 Web 的仪表板界面，用于查看存储在 MongoDB 中的 Sacred 运行记录。

Neptune <https://neptune.ai/>_ +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ .. image:: docs/images/neptune-compare.png .. image:: docs/images/neptune-collaboration.png

Neptune 是一个面向 MLOps 的元数据存储平台，专为频繁进行实验的团队设计。它提供了一个统一的平台，允许您通过 Python 和 R 编程语言的 API 来记录、存储、展示、组织、比较和查询所有模型构建相关的元数据：

.. image:: docs/images/neptune-query-api.png

要将您的 Sacred 实验日志记录到 Neptune，您只需添加一个观察者即可：

.. code-block:: python

from neptune.new.integrations.sacred import NeptuneObserver
ex.observers.append(NeptuneObserver(api_token='<YOUR_API_TOKEN>',
                                    project='<YOUR_WORKSPACE/YOUR_PROJECT>'))

更多信息，请参阅 Neptune + Sacred 集成指南 <https://docs.neptune.ai/integrations-and-supported-tools/experiment-tracking/sacred>_。

SacredBrowser <https://github.com/michaelwand/SacredBrowser>_ +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ .. image:: docs/images/sacred_browser.png

SacredBrowser 是一个基于 PyQt4 的应用程序，用于浏览由 Sacred 实验创建的 MongoDB 条目。其功能包括自定义查询、结果排序、访问存储的源代码等。该工具无需安装，可以连接本地数据库或通过网络连接。

Prophet <https://github.com/Qwlouse/prophet>_ ++++++++++++++++++++++++++++++++++++++++++++++ Prophet 是一个早期的原型，用于查看由 Sacred 实验创建的 MongoDB 条目，但目前已停止维护。它需要您运行 RestHeart <http://restheart.org>_ 才能访问数据库。

相关项目

Sumatra <https://pythonhosted.org/Sumatra/>_ ++++++++++++++++++++++++++++++++++++++++++++++ | Sumatra 是一种用于管理和跟踪基于数值模拟和/或分析的项目的工具，旨在支持可重复的研究。 | 它可以被视为计算项目中的自动化电子实验记录本。

Sumatra 采用不同的方法，提供命令行工具来初始化项目并运行任意代码（而不仅仅是 Python）。它会将所有运行的信息记录到 SQL 数据库中，并提供一个友好的浏览器工具。与要运行的代码集成度较低，因此更容易应用于非 Python 实验。不过，这也意味着每个实验需要更多的设置，且配置需通过文件完成。如果您需要运行非 Python 实验，或者不介意额外的设置和配置开销，可以考虑使用该项目。

Future Gadget Laboratory <https://github.com/Kaixhin/FGLab>_ ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ | FGLab 是一个机器学习仪表板，旨在简化实验原型设计。实验的详细信息和结果会被发送到数据库，从而可以在实验完成后进行分析。服务器端是 FGLab，客户端则是 FGMachines。

与 Sumatra 类似，FGLab 是一个外部工具，可以跟踪来自任何程序的运行。项目通过 JSON 模式进行配置，程序需要通过命令行选项接受这些配置。FGLab 还充当一个基本的调度器，负责将运行分配到多台机器上。

许可证

本项目根据 MIT 许可证 <http://opensource.org/licenses/MIT>_ 发布。

引用 Sacred

K. Greff, A. Klein, M. Chovanec, F. Hutter, and J. Schmidhuber, ‘The Sacred Infrastructure for Computational Research’, in Proceedings of the 15th Python in Science Conference (SciPy 2017), Austin, Texas, 2017, pp. 49–56 <http://conference.scipy.org/proceedings/scipy2017/klaus_greff.html>_.

.. |pypi| image:: https://img.shields.io/pypi/v/sacred.svg :target: https://pypi.python.org/pypi/sacred :alt: 当前 PyPI 版本

.. |py_versions| image:: https://img.shields.io/pypi/pyversions/sacred.svg :target: https://pypi.python.org/pypi/sacred :alt: 支持的 Python 版本

.. |license| image:: https://img.shields.io/badge/license-MIT-blue.png :target: http://choosealicense.com/licenses/mit/ :alt: MIT 许可证

.. |rtfd| image:: https://readthedocs.org/projects/sacred/badge/?version=latest&style=flat :target: https://sacred.readthedocs.io/en/stable/ :alt: ReadTheDocs

.. |doi| image:: https://zenodo.org/badge/doi/10.5281/zenodo.16386.svg :target: http://dx.doi.org/10.5281/zenodo.16386 :alt: 本版本的 DOI

.. |build| image:: https://github.com/IDSIA/sacred/actions/workflows/test.yml/badge.svg :target: https://github.com/IDSIA/sacred/actions/workflows/test.yml/badge.svg :alt: Github Actions PyTest

.. |coverage| image:: https://coveralls.io/repos/IDSIA/sacred/badge.svg :target: https://coveralls.io/r/IDSIA/sacred :alt: 覆盖率报告

.. |code_quality| image:: https://scrutinizer-ci.com/g/IDSIA/sacred/badges/quality-score.png?b=master :target: https://scrutinizer-ci.com/g/IDSIA/sacred/ :alt: Code Scrutinizer 质量评分

.. |black| image:: https://img.shields.io/badge/code%20style-black-000000.svg :target: https://github.com/ambv/black :alt: 代码风格：Black

Sacred 快速上手指南

Sacred 是一个用于配置、组织、记录复现机器学习实验的 Python 工具。它能自动追踪实验参数、保存配置到数据库，并确保结果可复现。

环境准备

• 操作系统：Linux, macOS, Windows
• Python 版本：支持 Python 3.6+
• 前置依赖：
  • 基础功能无需额外依赖
  • 若需使用数据库存储（推荐）或数值计算功能，建议安装 pymongo 和 numpy

安装步骤

方式一：通过 pip 安装（推荐）

直接使用国内镜像源加速安装：

pip install sacred -i https://pypi.tuna.tsinghua.edu.cn/simple

若需使用 MongoDB 存储实验记录及数值处理功能：

pip install pymongo numpy -i https://pypi.tuna.tsinghua.edu.cn/simple

方式二：从源码安装

git clone https://github.com/IDSIA/sacred.git
cd sacred
python setup.py install

基本使用

以下是将普通脚本转换为 Sacred 实验的最小示例。对比展示了如何通过装饰器管理配置和注入参数。

1. 定义实验与配置

创建一个 Python 文件（例如 train.py），内容如下：

from sklearn import svm, datasets
from numpy.random import permutation
from sacred import Experiment

# 初始化实验
ex = Experiment('iris_rbf_svm')

# 定义配置作用域：局部变量即为实验参数
@ex.config
def cfg():
    C = 1.0
    gamma = 0.7

# 定义主运行函数：参数自动注入
@ex.automain
def run(C, gamma):
    iris = datasets.load_iris()
    perm = permutation(iris.target.size)
    iris.data = iris.data[perm]
    iris.target = iris.target[perm]
    
    clf = svm.SVC(C=C, kernel='rbf', gamma=gamma)
    clf.fit(iris.data[:90], iris.target[:90])
    
    return clf.score(iris.data[90:], iris.target[90:])

2. 运行实验

在终端中直接运行脚本，Sacred 会自动解析命令行参数并执行：

python train.py

3. 修改参数运行

无需修改代码，直接通过命令行覆盖配置参数：

# 修改 C 和 gamma 参数
python train.py with C=2.0 gamma=0.5

# 查看帮助信息
python train.py help

4. 进阶：保存结果到数据库

若要记录实验详情到 MongoDB，只需添加 Observer：

from sacred.observers import MongoObserver

# 确保已启动 MongoDB 服务
ex.observers.append(MongoObserver(url='localhost:27017'))

运行后，所有参数、依赖、日志和结果将自动存入数据库，便于后续复现和分析。