介绍 venvstacks：分层 Python 虚拟环境 | LM Studio 博客

在我们最近的LM Studio 0.3.4 版本中宣布支持 Apple MLX时，我们提到了一个用于创建“……一套可独立下载的 Python 应用程序环境”的 Python 工具。

今天，我们很高兴开源这个工具：介绍 venvstacks！[Github 仓库]

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

venvstacks 已上线 PyPi：$ pip install --user venvstacks

认识 `venvstacks`

Python 的机器学习和 AI 库很大。非常大。

—— 不是道格拉斯·亚当斯

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 子命令允许将构建的环境复制到同一系统上的不同位置，并应用与执行归档打包和解包步骤时应用的大多数相同过滤步骤（省略的细节与可复现构建相关，例如将最大文件修改时间限制为已知值）。

本地导出环境会生成与发布层归档文件大致相同的元数据，但是必然会省略与已发布归档文件特别相关的详细信息（例如其大小和预期内容哈希值）。

`venvstacks` 在 LM Studio 中

开源的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 上开发。

https://github.com/lmstudio-ai/venvstacks

如果您有合适的用例，为 venvstacks 开发贡献力量最简单的方法就是试用一下，然后告诉我们结果如何。您喜欢什么，不喜欢什么，什么完全坏了？

如果出现任何问题，请提交问题（如果该问题尚未报告）。如果您不确定某些行为是否为错误，或者只是想提供一般反馈而不是提交特定问题或建议，下面提到的 Discord 频道是直接与开发人员联系的最佳方式。“打包”类别在 https://discuss.python.org/ 上也是提供反馈的好地方。

我们还有很多关于如何改进 venvstacks 的想法可以改进的地方。

我们记录了许多这些想法，因为我们计划自己实施它们，但也有一些其他的想法，我们记录它们是因为我们认为它们很有趣，并且乐于看到它们被包含，但我们目前不需要它们。

有关其他信息，请参阅 venvstacks 的开发者文档。

在新的 #venvstacks 频道中讨论 venvstacks 的一般信息，该频道位于 Python 打包 Discord 服务器。

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

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

认识 venvstacks

使用 venvstacks 构建和发布 Python 环境