神圣

| *每个实验都是神圣的*
| *每个实验都是伟大的*
| *如果一个实验被浪费了*
| *上帝会非常恼火*

|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/>_。

安装

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

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、有功能请求或想讨论一些一般问题,欢迎开一个 issue <https://github.com/IDSIA/sacred/issues>。如果你有与Sacred使用相关的具体问题,请在 python-sacred标签 <https://stackoverflow.com/questions/tagged/python-sacred> 下在StackOverflow上提问。我们非常重视文档。 如果你发现应该包含在文档中的内容,请记录下来或让我们知道缺少什么。如果你在项目中使用Sacred并想与他人分享你的代码, 请将你的仓库放在 使用Sacred的项目 <docs/projects_using_sacred.rst>_ 列表中。 非常欢迎提交拉取请求!

前端

目前有三个Sacred创建的数据库条目的前端(据我所知)。 它们作为单独的项目在外部开发。

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

Omniboard是一个网络仪表板,有助于可视化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是一个基于网络的仪表板界面,用于访问存储在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实验,或者可以接受额外的设置/配置开销,请使用这个项目。

未来道具研究所 +++++++++++++++

未来道具研究所是一个机器学习仪表板,旨在使实验原型设计更容易。实验详情和结果被发送到数据库,这允许在实验完成后进行分析。服务器是FGLab,客户端是FGMachines。

与Sumatra类似,FGLab是一个外部工具,可以跟踪任何程序的运行。项目通过JSON模式配置,程序需要通过命令行选项接受这些配置。FGLab还通过在多台机器上分配运行来扮演基本调度程序的角色。

许可证

该项目根据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.