📣 该项目目前未处于积极维护状态。如果您愿意参与维护，请告知我们。

---

Keepsake

机器学习的版本控制工具。

Keepsake 是一个 Python 库，可将文件和元数据（如超参数）上传至 Amazon S3 或 Google Cloud Storage。您可以通过命令行界面或 Jupyter 笔记本取回这些数据。

• 跟踪实验： 自动记录代码、超参数、训练数据、模型权重、指标以及 Python 依赖项——一切。
• 时光倒流： 如果需要复现结果或事后提交到 Git，您可以从任意检查点获取代码和权重。
• 为模型版本化： 模型权重存储在您自己的 Amazon S3 或 Google Cloud 存储桶中，因此非常容易将其部署到生产系统中。

工作原理

只需在您的训练代码中添加两行：

import torch
import keepsake

def train():
    # 保存训练代码和超参数
    experiment = keepsake.init(path=".", params={...})
    model = Model()

    for epoch in range(num_epochs):
        # ...

        torch.save(model, "model.pth")
        # 保存模型权重和指标
        experiment.checkpoint(path="model.pth", metrics={...})

随后，Keepsake 将开始跟踪所有内容：代码、超参数、训练数据、权重、指标、Python 依赖项等。

• 开源且由社区共建： 我们正努力汇聚机器学习社区的力量，共同构建这一基础性技术。
• 数据由您掌控： 所有数据都以普通文件的形式存储在您自己的 Amazon S3 或 Google Cloud Storage 中，无需运行任何服务器。
• 兼容各类框架： TensorFlow、PyTorch、scikit-learn、XGBoost 等，无论您使用哪种框架，它都只是保存文件和字典——您可以按自己习惯的方式导出数据。

功能特性

告别电子表格

您的所有实验都集中在一个地方，并支持筛选和排序。由于数据存储在 S3 上，您甚至可以查看在其他机器上运行的实验。

$ keepsake ls --filter "val_loss<0.2"
EXPERIMENT   HOST         STATUS    BEST CHECKPOINT
e510303      10.52.2.23   stopped   49668cb (val_loss=0.1484)
9e97e07      10.52.7.11   running   41f0c60 (val_loss=0.1989)

在笔记本中分析

不喜欢命令行？没问题。您可以在笔记本中检索、分析并绘制实验结果。这就像一个可编程的 TensorBoard。

对比实验

它会逐项比较差异，甚至包括依赖项的版本，以防最新版 TensorFlow 引入了某些异常行为。

$ keepsake diff 49668cb 41f0c60
Checkpoint:       49668cb     41f0c60
Experiment:       e510303     9e97e07

Params
learning_rate:    0.001       0.002

Python Packages
tensorflow:       2.3.0       2.3.1

Metrics
train_loss:       0.4626      0.8155
train_accuracy:   0.7909      0.7254
val_loss:         0.1484      0.1989
val_accuracy:     0.9607      0.9411

事后提交到 Git

如果您最终希望将代码存储在 Git 中，无需在每次运行时都提交。Keepsake 允许您回到调用 experiment.checkpoint() 的任意时间点，这样当您找到一个有效结果后，就可以一次性提交到 Git。

$ keepsake checkout f81069d
复制代码和权重到工作目录...

# 将代码提交到 Git
$ git commit -am "使用铰链损失"

在生产环境中加载模型

您可以使用 Keepsake 将模型部署到生产系统中，并关联其训练方式、训练者以及相关指标。

import keepsake
model = torch.load(keepsake.experiments.get("e45a203").best().open("model.pth"))

安装

pip install -U keepsake

开始使用

如果您更喜欢 训练脚本和命令行界面，请按照我们的教程了解 Keepsake 的工作原理：教程链接。

如果您更倾向于 在笔记本中操作，请访问我们的 Colab 笔记本教程：教程链接。

如果您想先了解 基本概念，可以阅读我们的指南：如何工作。

参与贡献

软件开发中普遍使用版本控制系统，但在机器学习领域却并不常见。

这是为什么呢？我们花了一年时间与机器学习社区的从业者交流，发现了以下几点：

• Git 不太适合机器学习： 它无法处理大文件，也无法存储像指标这样的键值型元数据，更无法在训练脚本中自动提交。虽然有一些解决方案，但更像是临时补救措施。
• 应该采用开源模式： 目前有许多专有解决方案，但如此基础性的工具应当由机器学习社区共建并服务于社区。
• 体积小巧、易于使用且可扩展： 我们发现许多人在尝试集成“AI 平台”时遇到了困难。我们希望打造一款专注于单一任务、同时又能与其他工具无缝结合的工具，从而满足您的需求。

我们认为，机器学习社区确实需要一套优秀的版本控制系统。然而，版本控制系统的实现较为复杂，要让这一愿景成为现实，离不开您的帮助。

您是否曾编写过一些 Shell 脚本来自行搭建类似系统？或者您对提高机器学习的可重复性这一问题感兴趣吗？

以下是几种您可以参与的方式：

• 加入我们的 Discord 社区，与我们和其他贡献者交流。
• 在我们的公开路线图上分享您对版本控制系统的期望。
• 尝试解决我们标记为“寻求帮助”的问题。

贡献与开发环境

请参阅我们的贡献指南。

Keepsake 快速上手指南

Keepsake 是一个专为机器学习设计的版本控制工具。它能自动追踪代码、超参数、训练数据、模型权重、指标及 Python 依赖，并将所有数据上传至你自有的 Amazon S3 或 Google Cloud Storage 存储桶中，无需额外搭建服务器。

注意：本项目目前处于非活跃维护状态。如需协助维护，可前往官方 GitHub 页面联系团队。

环境准备

在开始之前，请确保满足以下条件：

• 操作系统：支持 Linux、macOS 或 Windows。
• Python 版本：建议 Python 3.6 及以上。
• 云存储账户：你需要拥有 Amazon S3 或 Google Cloud Storage (GCS) 的访问凭证（Access Key/Secret Key 或服务账号密钥），用于存储实验数据。
• 前置依赖：根据你的深度学习框架安装相应库（如 torch, tensorflow, scikit-learn 等）。Keepsake 本身不限制框架。

安装步骤

使用 pip 进行安装。国内用户若遇到下载速度慢的问题，推荐使用清华或阿里镜像源。

# 使用默认源安装
pip install -U keepsake

# 或使用国内镜像加速（推荐）
pip install -U keepsake -i https://pypi.tuna.tsinghua.edu.cn/simple

安装完成后，你需要配置云存储凭证。通常通过设置环境变量或配置文件完成（具体参照云服务商文档），例如配置 AWS 凭证：

export AWS_ACCESS_KEY_ID=your_access_key
export AWS_SECRET_ACCESS_KEY=your_secret_key
export KEEPSAKE_BUCKET_NAME=your-bucket-name

基本使用

只需在现有的训练脚本中添加两行核心代码，即可开启全自动追踪。

1. 修改训练代码

在你的训练脚本（如 train.py）中引入 keepsake，初始化实验并记录检查点。

import torch
import keepsake

def train():
    # 初始化实验：自动保存当前目录代码和超参数
    # params 字典中放入你的超参数
    experiment = keepsake.init(path=".", params={"learning_rate": 0.001, "batch_size": 32})
    
    model = Model()

    for epoch in range(num_epochs):
        # ... 执行训练逻辑 ...
        
        # 保存模型权重
        torch.save(model, "model.pth")
        
        # 记录检查点：上传模型文件并记录当前指标
        experiment.checkpoint(path="model.pth", metrics={"val_loss": 0.1484, "val_accuracy": 0.96})

运行该脚本后，Keepsake 会自动将代码快照、依赖列表、超参数、模型文件及指标上传至你配置的云存储桶。

2. 查看与分析实验

训练完成后，你可以使用命令行工具查看和管理实验。

列出实验并筛选结果： 查看验证损失小于 0.2 的实验：

$ keepsake ls --filter "val_loss<0.2"
EXPERIMENT   HOST         STATUS    BEST CHECKPOINT
e510303      10.52.2.23   stopped   49668cb (val_loss=0.1484)
9e97e07      10.52.7.11   running   41f0c60 (val_loss=0.1989)

对比实验差异： 比较两个检查点的超参数、依赖版本及指标差异：

$ keepsake diff 49668cb 41f0c60
Checkpoint:       49668cb     41f0c60
Experiment:       e510303     9e97e07

Params
learning_rate:    0.001       0.002

Python Packages
tensorflow:       2.3.0       2.3.1

Metrics
train_loss:       0.4626      0.8155
val_loss:         0.1484      0.1989

3. 恢复代码与部署

回溯代码到 Git： 如果你找到了效果好的实验，可以将当时的代码和权重恢复到本地，再提交到 Git：

$ keepsake checkout f81069d
Copying code and weights to working directory...

# 此时工作目录已恢复至该检查点状态，可执行 git 提交
$ git commit -am "Use hinge loss"

在生产环境中加载模型： 直接通过代码加载最佳模型用于推理：

import keepsake
# 获取指定实验的最佳检查点并加载模型文件
model = torch.load(keepsake.experiments.get("e45a203").best().open("model.pth"))