介绍 venvstacks:分层 Python 虚拟环境

在我们最近发布的 LM Studio 0.3.4 中支持 Apple MLX 中,我们提到了一个 Python 工具,用于创建“……集成的一组可独立下载的 Python 应用程序环境”。

今天,我们很高兴能开源这个工具:隆重推出 venvstacks![Github 仓库]

venvstacks 使我们能够在 LM Studio 中交付我们的 MLX 引擎(一个 Python 应用程序),而无需最终用户安装任何 Python 依赖项。

venvstacks on pypi

venvstacks 已在 PyPi 上线:$ pip install --user venvstacks


认识 venvstacks

用于 Python 的机器学习和人工智能库非常庞大。真的非常庞大。

— 非道格拉斯·亚当斯

venvstacks 是一个基于 venv 的新 Python 项目,它使用 Python 的 sitecustomize.py 环境设置功能,将三层 Python 虚拟环境链接在一起。

  • “运行时”层:包含特定 Python 解释器所需版本的环境
  • “框架”层:包含关键 Python 框架所需版本的环境
  • “应用程序”层:包含直接启动的组件的环境

虽然这些层是单独存档和发布的,但它们的依赖锁定是集成的,允许应用程序层共享框架层中安装的依赖项,并且框架层共享运行时层中安装的依赖项。

使用 venvstacks 构建和发布 Python 环境

定义环境堆栈

要发布的环境层在 venvstacks.toml 堆栈规范中定义,每种层定义都有一个独立的表数组。

例如,以下规范定义了一对应用程序,它们使用 scikit-learn 作为共享框架层,并在运行时层中预安装了 numpy,所有这些都在受控的 Python 3.11 基本运行时中运行。

[[runtimes]]
name = "[email protected]"
fully_versioned_name = "[email protected]"
requirements = [
    "numpy",
]

[[frameworks]]
name = "sklearn"
runtime = "[email protected]"
requirements = [
    "scikit-learn",
]

[[applications]]
name = "classification-demo"
launch_module = "launch_modules/sklearn_classification.py"
frameworks = ["sklearn"]
requirements = [
    "scikit-learn",
]

[[applications]]
name = "clustering-demo"
launch_module = "launch_modules/sklearn_clustering.py"
frameworks = ["sklearn"]
requirements = [
    "scikit-learn",
]

锁定环境堆栈

$ venvstacks lock sklearn_demo/venvstacks.toml

“lock”子命令获取规范中定义的层要求,并使用它们对所有环境堆栈进行完整的解析,以确保不同层可以单独发布,但在部署到目标系统时仍能按预期工作。锁定机制的定义方式是,只有给定层在较低层中使用的模块的更改会影响它们,而不是较高层需要为较低层的“每个”更改而重新构建。

构建环境堆栈

$ venvstacks build sklearn_demo/venvstacks.toml

“build”子命令执行将层规范及其锁定要求转换为可用的 Python 环境的步骤(可以是基本运行时环境,也可以是基于已定义运行时环境之一的分层虚拟环境)。如果环境尚未明确锁定,则构建步骤将根据需要锁定它们。

此命令也是一个“构建管道”命令,允许一步完成锁定、构建和发布(详细信息请参阅命令行帮助)。

发布环境层归档

$ venvstacks publish --tag-outputs --output-dir demo_artifacts sklearn_demo/venvstacks.toml

一旦环境成功构建,publish 命令允许将每个层转换为一个单独的可重现的二进制存档,适合传输到另一个系统,解压,并使用解压后的环境运行包含的应用程序(只需要一个小的安装后步骤,使用内置于构建层存档中的 Python 脚本,以在目标系统上的部署位置正确地将已部署的环境相互重新链接)。

有关层定义和已发布工件的元数据与已发布存档一起发布(在给定示例中发布到 demo_artifacts/__venvstacks__/)。此元数据捕获输入详细信息(例如锁定要求和包含的启动模块的哈希)和输出详细信息(例如构建层存档的确切大小和确切哈希)。

本地导出环境堆栈

$ venvstacks local-export --output-dir demo_export sklearn_demo/venvstacks.toml

鉴于即使考虑使用 venvstacks 也意味着某些层档案可能体积庞大(例如,一个完全构建的 PyTorch 档案重量可达数 GB),打包和解包层档案可能需要大量时间。

为了避免在迭代层定义和启动模块详细信息时出现这种开销,local-export 子命令允许将构建的环境复制到同一系统上的不同位置,并应用了与执行档案打包和解包步骤时相同的大部分过滤步骤(遗漏的详细信息与可重现构建相关,例如将最大文件修改时间限制为已知值)。

本地导出环境会生成与发布层存档类似的大部分元数据,但与已发布存档特别相关的详细信息(例如其大小和预期内容哈希)必然会被省略。

LM Studio 中的 venvstacks

开源的 mlx-engine 作为应用程序层环境中的启动模块部署在 LM Studio 桌面应用程序中,该环境声明了所需的运行时包依赖项,运行在 MLX 框架层和 CPython 3.11 基本运行时层之上。

然后,venvstacks 的使用允许 LM Studio 引入额外的基于 MLX 的功能,而无需重复 MLX 框架层,以及额外的基于 Python 的功能,而无需重复 Python 运行时层。

随着时间的推移,并行分发多个应用程序、框架甚至基本运行时层的能力,使得可以优雅地迁移到较新的组件版本,而不会对 LM Studio 用户造成任何干扰。

亲自试用 venvstacks

venvstacks 的初始版本可从 Python 包索引获取,并且可以使用 pipx(以及类似工具)进行安装。

$ pipx install venvstacks

有关更多用法信息,请查阅 venvstacks 项目文档和命令行帮助。

$ venvstacks --help

 Usage: venvstacks [OPTIONS] COMMAND [ARGS]...

 Lock, build, and publish Python virtual environment stacks.

╭─ Options ───────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                     │
╰─────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ──────────────────────────────────────────────────────────────────────╮
│ build          Build (/lock/publish) Python virtual environment stacks.         │
│ local-export   Export layer environments for Python virtual environment stacks. │
│ lock           Lock layer requirements for Python virtual environment stacks.   │
│ publish        Publish layer archives for Python virtual environment stacks.    │
╰─────────────────────────────────────────────────────────────────────────────────╯

贡献 venvstacks 的开发

venvstacks 采用 MIT 许可证,并在 GitHub 上开发

如果您有合适的用例,贡献 venvstacks 开发的最简单方法就是试用它,并告诉我们结果如何。您喜欢什么,不喜欢什么,以及哪些地方完全崩溃了?

如果出现任何问题,请提交问题(如果问题尚未报告)。如果您不确定某个行为是否是错误,或者只想提供一般反馈而不是提交具体问题或建议,下面提到的 Discord 频道是与开发人员直接联系的最佳方式。https://discuss.python.org/ 上的“打包”类别也是提供反馈的合理场所。

我们已经有很多关于如何改进 venvstacks 的想法。

虽然我们已经记录了许多这些想法,因为我们计划自己实现它们,但也有一些其他想法,我们记录它们是因为我们认为它们很有趣,并且愿意看到它们被包含进来,但目前没有立即的需求。

有关更多信息,请参阅 venvstacks 开发者文档


Python Packaging Discord 服务器上的新 #venvstacks 频道中讨论 venvstacks

LM Studio Discord 服务器上的 #dev-chat 频道中讨论在 LM Studio 中使用 mlx-enginevenvstacks

https://lm-studio.cn/download 下载适用于 Mac / Windows / Linux 的 LM Studio。