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 开发做贡献的最简单方法就是尝试使用它，并告诉我们您的使用体验。您喜欢什么，不喜欢什么，哪些地方直接崩溃了？

如果任何地方确实崩溃了，请提交 issue（如果问题尚未报告）。如果您不确定某些行为是否是错误，或者只是想提供一般反馈而不是提交具体问题或建议，则下面提到的 Discord 频道是直接与开发人员联系的最佳方式。Python 论坛上的“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 环境