介绍 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 存档可能达到数千兆字节），因此打包和解压层存档可能需要大量时间。

为了避免在迭代层定义和启动模块详细信息时的开销，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/ 上的 “Packaging”类别也是提供反馈的合适场所。

我们对于如何改进 venvstacks 也已有很多想法。

虽然我们已经记录了其中许多想法，并计划亲自实现它们，但也有一些想法被记录下来是因为我们认为它们很有趣，并乐于看到它们被包含进来，但我们目前并没有立即实现它们的需求。

有关更多信息，请查阅 venvstacks 开发者文档。

在 Python Packaging Discord 服务器的新 #venvstacks 频道中讨论 venvstacks 的一般性问题。

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

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

认识 venvstacks

使用 venvstacks 构建和发布 Python 环境