xvc

一个快速且健壮的 MLOps 工具，用于管理数据和管道

⌛ 何时使用 xvc?

• 当你有一组需要备份/版本化的照片、音频、媒体或文档，但不想将大量数据复制到所有 Git 克隆中时。
• 当你管理大量非结构化数据，如图像、文档和音频文件时。
• 当你想对数据文件进行版本控制，并希望跨数据集跟踪版本时。
• 当你想将此数据存储在本地、SSH 可访问或兼容 S3 的云存储中时。
• 当你在此数据上创建数据管道并希望在数据、代码或其他依赖项更改时运行这些管道时。
• 当你想跟踪你正在工作的数据子集以及它们如何通过你的操作而变化时。
• 当你有作为依赖项使用的二进制工件，并希望有一个考虑 内容更改 而不是时间戳的 make 替代方案时。

✳️ xvc 是什么？

• (对于 x = 文件) 在 Git 上跟踪大型文件，将它们存储在云中，创建只读子集，仅在需要时检索它们。
• (对于 x = 管道) 定义并运行数据 -> 模型管道，其依赖项可能是文件、超参数、正则表达式搜索、任意 URL 等。

🔽 安装

您可以从 发布 页面获取 Linux、macOS 和 Windows 的二进制文件。解压缩并将文件复制到您的 $PATH。

如果您已安装 Rust，您还可以构建 xvc

$ cargo install xvc

如果您想使用 Python 控制台和 Jupyter 笔记本与 Xvc 一起使用，您也可以使用 pip 安装它

$ pip install xvc

请注意，pip 安装不会将 xvc 作为 shell 命令提供。有关使用详情，请参阅 xvc.py。

🏃🏾 Quicktart

Xvc 无缝地监视 Git 上的文件和目录。要开始，请在存储库中执行以下命令：

$ git init # if you're not already in a Git repository
Initialized empty Git repository in [CWD]/.git/

$ xvc init

此命令初始化 .xvc/ 目录，并添加一个 .xvcignore 文件，以指定您希望从 Xvc 中隐藏的路径。

包括您要跟踪的数据文件和目录

$ xvc file track my-data/ --as symlink

此命令计算数据的内容哈希（默认使用 BLAKE-3）并记录它们。更改将提交到 Git，并将文件复制到 .xvc/b3 中的内容地址目录。此外，还将创建对这些目录的只读符号链接。

根据您的用例，您可以指定不同的 recheck（检出）方法 用于文件和目录。如果您需要跟踪频繁更改的模型文件，可以将 recheck 方法设置为 --as copy（默认值）。

$ xvc file track my-models/ --as copy

配置云存储以共享您添加的文件。

$ xvc storage new s3 --name my-storage --region us-east-1 --bucket-name my-xvc-remote

您可以将文件发送到该存储。

$ xvc file send --to my-storage

当您（或其他人）稍后想要访问这些文件时，您可以克隆 Git 存储库，并从存储中获取文件。

$ git clone https://example.com/my-machine-learning-project
Cloning into 'my-machine-learning-project'...

$ cd my-machine-learning-project
$ xvc file bring my-data/ --from my-storage

这种方法确保在需要时可以方便地从共享存储访问文件。

在克隆后，您无需重新配置存储，但需要具有作为环境变量的有效凭据才能访问存储。Xvc 从不存储任何凭据。

如果您有依赖于数据或代码元素的命令，您可以配置一个管道。

对于此示例，我们将使用 一个 Python 脚本 生成具有随机名称和随机智商分数的数据集。

脚本使用 Faker 库，并且此库必须在您运行管道的位置可用。为了使其可重复，我们通过添加一个安装依赖的步骤来开始管道。

$ xvc pipeline step new --step-name install-deps --command 'python3 -m pip install --quiet --user -r requirements.txt'

我们将使此步骤依赖于 requirements.txt 文件，因此当文件更改时，它将使步骤运行。

$ xvc pipeline step dependency --step-name install-deps --file requirements.txt

Xvc 允许创建管道步骤之间的依赖关系。依赖步骤将等待依赖关系成功完成。

现在我们创建一个步骤来运行脚本，并将 install-deps 步骤作为其依赖项。

$ xvc pipeline step new --step-name generate-data --command 'python3 generate_data.py'
$ xvc pipeline step dependency --step-name generate-data --step install-deps

在定义管道后，您可以运行它：

$ xvc pipeline run
[DONE] install-deps (python3 -m pip install --quiet --user -r requirements.txt)
[OUT] [generate-data] CSV file generated successfully.

[DONE] generate-data (python3 generate_data.py)

Xvc 允许许多类型的依赖关系，如 文件、由 globs 定义的文件和目录组、文件中的正则表达式搜索、文件中的行范围、在 YAML、JSON 或 TOML 文件中定义的超参数、HTTP URL、shell 命令输出 以及 其他步骤。

假设您只对那些名字前有 Dr. 的人的智商分数以及他们在我们创建的数据集中的差异感兴趣。让我们创建一个正则表达式搜索依赖项，以显示所有 医生 的智商分数。

$ xvc pipeline step new --step-name dr-iq --command 'echo "${XVC_ADDED_REGEX_ITEMS}" >> dr-iq-scores.csv '
$ xvc pipeline step dependency --step-name dr-iq --regex-items 'random_names_iq_scores.csv:/^Dr\..*'

第一行指定了一个命令，当运行时，会将 ${XVC_ADDED_REGEX_ITEMS} 环境变量写入 dr-iq-scores.csv 文件。第二行指定了依赖项，它也会在命令中设置 $[XVC_ADDED_REGEX_ITEMS] 环境变量。

一些依赖类型，如[正则表达式项]、[行项]和[glob项]，会在它们的命令中注入环境变量。例如，如果您指定了200万个文件，但只想在最后一次运行后运行脚本，您可以使用这些环境变量。

当您再次运行流水线时，将创建一个名为 dr-iq-scores.csv 的文件。请注意，由于 requirements.txt 没有改变，install-deps 步骤及其依赖的 generate-data 步骤没有运行。

$ xvc pipeline run
[DONE] dr-iq (echo "${XVC_ADDED_REGEX_ITEMS}" >> dr-iq-scores.csv )

$ cat dr-iq-scores.csv
Dr. Brian Shaffer,122
Dr. Brittany Chang,82
Dr. Mallory Payne MD,70
Dr. Sherry Leonard,93
Dr. Susan Swanson,81

我们使用此功能从文件中获取以 Dr. 开头的行，并将它们写入另一个文件。当文件更改时，例如将另一个与依赖正则表达式匹配的记录添加到 random_names_iq_scores.csv 文件，它也将被添加到 dr-iq-scores.csv 文件中。

$ zsh -cl 'echo "Dr. Albert Einstein,144" >> random_names_iq_scores.csv'

$ xvc pipeline run
[DONE] dr-iq (echo "${XVC_ADDED_REGEX_ITEMS}" >> dr-iq-scores.csv )

$ cat dr-iq-scores.csv
Dr. Brian Shaffer,122
Dr. Brittany Chang,82
Dr. Mallory Payne MD,70
Dr. Sherry Leonard,93
Dr. Susan Swanson,81
Dr. Albert Einstein,144

现在我们想添加另一个命令，从 dr-iq-scores.csv 中绘制一个漂亮的直方图。由于这个新步骤必须等待 dr-iq-scores.csv 文件准备就绪，我们将 dr-iq-scores.csv 定义为 dr-iq 步骤的 输出，并将该文件设置为对新 visualize 步骤的依赖。

$ xvc pipeline step output --step-name dr-iq --output-file dr-iq-scores.csv
$ xvc pipeline step new --step-name visualize --command 'python3 visualize.py'
$ xvc pipeline step dependency --step-name visualize --file dr-iq-scores.csv
$ xvc pipeline run
[ERROR] Step visualize finished UNSUCCESSFULLY with command python3 visualize.py

您可以将流水线导出为 Graphviz DOT 格式以转换为图像。

$ zsh -cl 'xvc pipeline dag | dot -opipeline.png'

您还可以将流水线导出为 JSON 并在您的编辑器中编辑。

$ xvc pipeline export --file my-pipeline.json

$ cat my-pipeline.json
{
  "name": "default",
  "steps": [
    {
      "command": "python3 -m pip install --quiet --user -r requirements.txt",
      "dependencies": [
        {
          "File": {
            "content_digest": {
              "algorithm": "Blake3",
              "digest": [
                43,
                86,
                244,
                111,
                13,
                243,
                28,
                110,
                140,
                213,
                105,
                20,
                239,
                62,
                73,
                75,
                13,
                146,
                82,
                17,
                148,
                152,
                66,
                86,
                154,
                230,
                154,
                246,
                213,
                214,
                40,
                119
              ]
            },
            "path": "requirements.txt",
            "xvc_metadata": {
              "file_type": "File",
              "modified": {
                "nanos_since_epoch": [..],
                "secs_since_epoch": [..]
              },
              "size": 14
            }
          }
        }
      ],
      "invalidate": "ByDependencies",
      "name": "install-deps",
      "outputs": []
    },
    {
      "command": "python3 generate_data.py",
      "dependencies": [
        {
          "Step": {
            "name": "install-deps"
          }
        }
      ],
      "invalidate": "ByDependencies",
      "name": "generate-data",
      "outputs": []
    },
    {
      "command": "echo /"${XVC_ADDED_REGEX_ITEMS}/" >> dr-iq-scores.csv ",
      "dependencies": [
        {
          "RegexItems": {
            "lines": [
              "Dr. Brian Shaffer,122",
              "Dr. Susan Swanson,81",
              "Dr. Brittany Chang,82",
              "Dr. Mallory Payne MD,70",
              "Dr. Sherry Leonard,93",
              "Dr. Albert Einstein,144"
            ],
            "path": "random_names_iq_scores.csv",
            "regex": "^Dr//..*",
            "xvc_metadata": {
              "file_type": "File",
              "modified": {
                "nanos_since_epoch": [..],
                "secs_since_epoch": [..]
              },
              "size": 19021
            }
          }
        }
      ],
      "invalidate": "ByDependencies",
      "name": "dr-iq",
      "outputs": [
        {
          "File": {
            "path": "dr-iq-scores.csv"
          }
        }
      ]
    },
    {
      "command": "python3 visualize.py",
      "dependencies": [
        {
          "File": {
            "content_digest": null,
            "path": "dr-iq-scores.csv",
            "xvc_metadata": null
          }
        }
      ],
      "invalidate": "ByDependencies",
      "name": "visualize",
      "outputs": []
    }
  ],
  "version": 1,
  "workdir": ""
}

您可以通过编辑文件来更改命令、添加新的依赖项等，并将其导入到 Xvc。

$ xvc pipeline import --file my-pipeline.json --overwrite

最后，如果您注意到命令太长难以输入，有一个 xvc aliases 命令会打印一组命令别名。您可以将输出源到您的 .zshrc 或 .bashrc，然后使用以下命令，例如，xvc pipelines run 变为 pvc run。

$ xvc aliases

alias xls='xvc file list'
alias pvc='xvc pipeline'
alias fvc='xvc file'
alias xvcf='xvc file'
alias xvcft='xvc file track'
alias xvcfl='xvc file list'
alias xvcfs='xvc file send'
alias xvcfb='xvc file bring'
alias xvcfh='xvc file hash'
alias xvcfco='xvc file checkout'
alias xvcfr='xvc file recheck'
alias xvcp='xvc pipeline'
alias xvcpr='xvc pipeline run'
alias xvcps='xvc pipeline step'
alias xvcpsn='xvc pipeline step new'
alias xvcpsd='xvc pipeline step dependency'
alias xvcpso='xvc pipeline step output'
alias xvcpi='xvc pipeline import'
alias xvcpe='xvc pipeline export'
alias xvcpl='xvc pipeline list'
alias xvcpn='xvc pipeline new'
alias xvcpu='xvc pipeline update'
alias xvcpd='xvc pipeline dag'
alias xvcs='xvc storage'
alias xvcsn='xvc storage new'
alias xvcsl='xvc storage list'
alias xvcsr='xvc storage remove'

请为任何其他您希望包含的依赖类型创建问题或讨论。

我计划在时间允许的情况下添加 数据标签和注释跟踪、实验跟踪、模型跟踪）、加密缓存、通过 Web 界面控制所有命令的服务器等。

请访问 docs.xvc.dev 查阅文档。

🤟 感谢

xvc 立足于以下（巨大的）crates

• trycmd 用于运行此文件中的所有示例命令，并在每次 Pull Request 中提供 参考和如何操作文档。它确保文档始终是最新的，并且显示的命令按描述工作。我们通过编写文档并实现它们来开始开发，多亏了 trycmd。

• serde 允许所有数据结构都存储在文本文件中。特别感谢 xvc-ecs 使用一行代码序列化 ECS 中的组件。

• 得益于 crossbeam 和 rayon，Xvc 可以并行使用管道和并行迭代器处理文件。

• 得益于 strum，Xvc 广泛使用枚举，并将几乎所有内容从字符串转换为有类型的值。

• Xvc 拥有一个深度 CLI，具有子命令的子命令（例如 xvc storage new s3），所有这些命令都几乎无错误地工作，多亏了 clap。

• Xvc 使用 rust-s3 连接到 S3 和兼容的存储服务。它利用优秀的 tokio 进行快速的异步 Rust。这些云存储功能可以通过 Rust 条件编译关闭。

• 如果没有 Rust crypto crate 中实现的 BLAKE3、BLAKE2、SHA-2 和 SHA-3，Xvc 就不能如此快速地检测文件更改。

• 非常感谢一些小型且构建良好的 crates，如用于文件系统和 glob 处理的 reflink、relative-path、path-absolutize、glob。

• 感谢 sad_machine 为我提供了 State Machine 实现，我在 xvc pipeline run 中使用了它。由 State Machines 组成的 DAG 可以并行运行管道步骤，同时清晰地分离过程状态。

• 感谢 thiserror 和 anyhow 使错误处理变得轻松。这两个 crates 让我感到，我在处理错误时为人类做出了贡献。

• Xvc 被分割成许多 crates，并得益于 cargo workspaces 的组织。

最大的感谢要献给 Rust 设计师、开发者和贡献者。虽然我不能自认为专家来欣赏所有这些，但它是一个出色的语言和环境来工作。

🚁 支持

• 您可以使用 讨论 来提问。我会尽我所能回答。谢谢。
• 我并不定期关注任何其他网站。您也可以通过 [email protected] 联系我

👐 贡献

• 星标此仓库。我对每个星标都感到非常高兴，并向您表示最美好的祝愿。这是您为我花费两秒钟时间的一种确定的胜利。谢谢。
• 使用 xvc。告诉我它是如何为您工作的，阅读 文档，报告错误，讨论功能。
• 请注意，我不接受大型代码PR。请在发送PR之前，先提交一个issue来讨论您的想法，并编写/修改参考页面。我很乐意讨论并帮助您实现您的想法。此外，由于我可能以其他许可证提供代码，因此可能需要将版权转让给我。

📜 许可证

Xvc遵循GNU GPL 3.0 许可证。如果您想在项目中使用此代码并采用其他许可证，请与我联系。

🌦️ 未来与维护

我每天都在使用Xvc，并且对此感到满意。通过任意服务器和云提供商跟踪所有我的文件是我一直需要的。只要我继续使用，我就很高兴对其进行改进和维护。

鉴于我过去两年一直在纯粹的技术快乐中从事这项工作，您可以期待我会继续在这方面投入更多的工作。

⚠️ 免责声明

此软件新鲜且雄心勃勃。尽管我在接近现实世界的条件下使用并测试了它，但它并没有经过时间的考验。《Xvc可能会吞噬您的文件并将它们吞入永恒的虚空！》请进行备份。