bo老师
开源仓库IDSIA/sacred4,367 Stars

Sacred

自动记录每次计算实验的配置、种子、依赖和结果，让实验可追溯、可复现。

适合每天跑大量实验变体、需要回溯每次运行用了什么参数和依赖的研究者。用装饰器标注实验入口，Sacred自动捕获环境和配置变更，存到文件或数据库。

bo老师判断：推荐

用途和边界相对清楚，可以先从小样本开始。

访问原仓库查看分享卡
...互动状态已更新

什么时候用

先判断任务是否合适

  • 每天跑几十次参数变体实验，需要一个系统记录每次运行的全貌
  • 论文修改阶段需要回溯某张图用的是哪次实验的哪个参数
  • 需要保证实验结果可复现——包括配置、种子、依赖和源码版本
  • 多个实验想在同一套参数基础上叠加变体，需要层级化配置管理

先准备什么

材料越清楚，结果越有用

  • •实验主函数及其参数，Sacred用装饰器@ex.automain标注入口
  • •实验用到的Python环境和包版本
  • •目标存储后端选择（默认文件，可切MongoDB/SQL/S3等）

它会怎样推进

从材料到可以检查的结果

  1. 01

    装饰实验函数

    用@ex.config定义默认参数，@ex.automain标注入口，captured函数自动注入配置

  2. 02

    运行实验

    命令行或程序化运行，支持with key=val覆盖参数、命名配置变体和队列模式

  3. 03

    自动采集

    运行期间自动收集源码、依赖版本、host信息、git状态和stdout输出

  4. 04

    持久化记录

    配置、种子、指标、结果写入文件或数据库，每次run有唯一ID

  5. 05

    查询实验

    用sacredboard、omniboard或incense跨run检索、对比和可视化实验记录

第一次这样开始

把仓库地址直接交给 AI

先让 AI 说明环境和风险，再完成最小安装验证。跑通以后，再把自己的真实材料放进去。

第一次直接复制

帮我安装这个库：https://github.com/IDSIA/sacred
安装前先告诉我需要什么环境，安装后帮我跑通一个最小示例。

结果出来后

先看这些检查点

  • 每run的config.json是否完整记录了这次运行的全部参数
  • run.json中的seed值是否唯一且可复现
  • 源码和依赖版本是否与预期一致（审稿前尤其要核对）
  • metrics.json的步数和值是否覆盖了整个训练过程

常见误区

这些判断仍由你负责

  • 不设置seed就运行——每次seed随机，导致实验不可复现
  • 以为Sacred会自动seed所有库——它只处理Python/NumPy/TF/PyTorch四个库
  • jsonpickle序列化把tuple变成list后，跨类型比较行为会改变
  • QueueObserver在外部服务中断时无最终失败声明，可能无限重试而研究者不知情

技术依据

查看能力拆解、验证范围与来源

能力地图5 项已拆解能力
  1. 01

    依赖与实验信息自动收集

    在不要求研究者手写任何"环境清单"的前提下，自动捕获"这次 run 用了哪些源码、哪些包、什么版本、在什么机器上、git 状态如何"。上游是被 import 的模块与运行进程，下游是 experimentinfo（sources/dependencies/repositories）与 hostinfo，随 run 持久化用于复现审计。这是 sacred"零开销可追溯"的关键支撑。

  2. 02

    实验信息序列化与前端查询

    把分散采集的 config/seed/依赖/host/输出/结果/info/artifacts 序列化成稳定结构（run.json 或 Mongo 文档），并提供跨 run 检索、对比与回读的途径。上游是 Run 对象与 observer 事件，下游是可被前端（sacredboard/omniboard/incense/TinyDbReader）查询与可视化的持久记录。这是 sacred"记录后能用"的出口：没有这一层，记录只是死数据。

  3. 03

    实验运行与观察者记录

    把一次实验执行从"启动→运行→停止"的完整生命周期，连同配置/种子/依赖/host/输出/结果/失败栈，结构化地记录到可插拔的后端。上游是 captured main function 的执行，下游是持久化的 run 记录（DB/文件/云/通知）。这是 sacred"记录每一次实验"目标的主载体，也是区别于"只跑代码不记上下文"的核心。

  4. 04

    配置捕获与注入

    把一次实验的"参数集"从硬编码常量升级成可记录、可覆盖、可注入、可校验的配置对象。上游是用户写的 Python 函数体 / dict / 配置文件，下游是一个被自动收集、按 dotted path 嵌套、注入到任意 captured function、随 run 一起持久化的 config dict。这是 sacred 最核心的能力：种子、依赖、host、结果都附在 config 之上。

能力主要输入主要输出人工检查

依赖与实验信息自动收集

源码已核对

  • 被 experiment 模块 import 的 Python 模块（用于 inspect 自动发现 source）。
  • 运行进程的已安装包（pkgresources 提取 name==version）。
  • experiment 所在的 git 仓库（url/commit/dirty）。
  • experimentinfo（随 startedevent/queuedevent 持久化）。
  • hostinfo（随 startedevent 持久化）。
  • 源码快照（FileStorageObserver 存 sources/，MongoObserver 存 GridFS）。
  • 哪些环境变量进 CAPTUREDENV 由研究者决定（避免泄露敏感值）。
  • auto-discovery 漏掉的源码/依赖需人工 addsourcefile/addpackagedependency。
  • additionalhostinfo 的自定义 gatherer 正确性由研究者负责。

实验信息序列化与前端查询

源码已核对

  • Run 对象的 config/configmodifications/experimentinfo/hostinfo/info/metainfo/result/status/times/capturedout。
  • resource/artifact 文件。
  • metrics（run.logscalar 系列）。
  • 结构化 run 记录（文件/DB/云）。
  • metrics 时序数据。
  • 源码/artifact/resource 文件（去重存储）。
  • observer 与前端选择由研究者/团队决定。
  • info dict 内容（如 numpy 数组）序列化后的可读性需人工确认。
  • 跨版本数据兼容性需人工核对 format 字段。

实验运行与观察者记录

源码已核对

  • captured main function（@ex.automain/@ex.main）或 command（@ex.command）。
  • 已 finalize 的 config（含 seed）。
  • experimentinfo / hostinfo（createrun 时采集）。
  • 持久化 run 记录（DB/文件/云）：config/experiment/host/info/meta/result/status/times/capturedout/artifacts/resources。
  • 通知（Slack/Telegram/Neptune）：停止时消息。
  • 源码/资源/产物文件（去重存储）。
  • observer 选择与配置（DB 连接、认证、bucket）由研究者/运维决定。
  • QueueObserver 的无限重试需人工监控。
  • DEAD run 判定需人工看 heartbeattime 与 status。

配置捕获与注入

源码已核对

  • @ex.config 装饰的函数体（局部变量即配置项，可含动态计算与条件分支，无 return/yield）。
  • ex.addconfig({...}) 或 ex.addconfig(foo=42, bar='baz')（纯字典，必须 JSON 可序列化）。
  • 配置文件：ex.addconfig('conf.json'|'conf.yaml'|'conf.pickle')（YAML 需 PyYAML）。
  • 全局 config dict（随 run 持久化到 observer）。
  • configmodifications（added/modified/typechanged），用于 printconfig 与可复现审计。
  • 注入到所有 captured function 的参数值。
  • 配置项命名规范、named config 组织方式由研究者自定义（无内建约束）。
  • 类型变更告警需人工判断是否为有意行为。
  • config scope 内的复杂逻辑（条件、循环）可读性由研究者负责。

随机种子层级化管理

源码已核对

  • 自动生成的 root-seed（getseed 用 random.randint(1, int(1e9))）。
  • 用户指定：ex.run(configupdates={'seed': 123}) 或 CLI with seed=123。
  • 全局 PRNG 库可用性：numpy（可选）、tensorflow（检测 moduleincache）、pytorch（检测）。
  • config 中的 seed（持久化，复现关键）。
  • 全局 PRNG 状态（运行期）。
  • 每个 captured function 的独立 seed/rnd。
  • 第三方库随机性是否需手动 seed 由研究者判断。
  • cuDNN 等硬件级非确定性 sacred 无法控制，需研究者知晓。
  • 跨 numpy 版本复现时是否锁定 legacy API 需人工决定。

处理机制

  1. 01

    观察者事件生命周期

    解释 sacred 五类能力（配置捕获、种子、依赖采集、运行记录、序列化）的共同架构支柱：RunObserver 基类定义的事件合同 + priority 排序 + 首 observer 决定 id + Run 状态机驱动事件分发。这个横切结构决定了为什么 File/Mongo/TinyDB/SQL/S3/GCS/Slack/Telegram/Neptune 九类后端能共用同一套运行记录逻辑，以及为什么 run 记录、id、status、heartbeat、artifacts 在所有后端表现一致。

已核对范围

  • 静态确认 gathersourcesanddependencies 通过模块 inspect + pkgresources 自动发现源码与依赖（dependencies.py:726）
  • 静态确认 experimentinfo 含 name/basedir/sources/dependencies/repositories（ingredient.py getexperimentinfo）
  • 静态确认 collectrepositories 从 sources 提取 git url/commit/dirty
  • 静态确认 hostinfo 含 cpu/os/hostname/pythonversion/gpu/ENV，可扩展 hostinfogatherer
  • 静态确认 run.json/Mongo runs 文档字段合同（config/experiment/host/info/meta/result/status/times/capturedout/artifacts/resources）
  • 静态确认 FileStorageObserver 目录结构（runxxx/{config.json,cout.txt,info.json,run.json,metrics.json} + sources/ + resources/）
  • 静态确认 MongoObserver 三集合（runs/fs.files/fs.chunks）+ metrics 集合
  • 静态确认前端生态（sacredboard/omniboard/incense/TinyDbReader/Neptune）查询路径

仍待核对

  • 未运行验证 auto-discovery 在 95% 用例的覆盖率声明
  • 未验证 gpu 信息采集在不同硬件下的实际输出
  • 未验证 MODULEBLACKLIST 过滤的完整性
  • 未运行验证 Mongo 查询的 filter 语法覆盖范围
  • 未验证 TinyDbReader 三种检索（indices/expname/query）的实际行为
  • 未验证 jsonpickle 序列化对 numpy/pandas 对象的实际输出形态
  • 未运行验证 observer 端到端记录
  • 未验证 QueueObserver 在外部服务中断时的重试与最终失败边界

原仓库

IDSIA/sacred

读取版本

source-reviewed

许可

MIT

最近核对

内容 2026-07-11
Stars 2026-07-11

已完成源码核对

相关文章

科研之我见

AI 科研全流程怎么搭，我梳理出三个核心入口

每天开工先固定阶段入口、材料入口和验证入口，把庞大的科研全流程收缩成一段可执行、可检查的任务。

查看内容

具备相关能力的其他库

文献 · 验证

paper-qa

从本地论文和文档中检索证据并生成带精确引用的科研答案

查看内容

文献 · 分析 · 写作

grobid

把学术论文PDF解析成结构化TEI XML，提取元数据、全文结构和参考文献

查看内容

设计 · 分析 · 验证

CausalPy

用贝叶斯方法做准实验因果推断，含10+方法和稳健性诊断套件

查看内容