在我们近期关于 LM Studio 0.3.4 中支持 Apple MLX 的公告中，我们提及了一种用于创建“一组集成的、可独立下载的 Python 应用程序环境”的 Python 工具。

今天，我们非常高兴地开源此工具：隆重推出 venvstacks！[Github 仓库]

venvstacks 使我们能够在不要求终端用户安装任何 Python 依赖项的情况下，将作为 Python 应用程序的 MLX 引擎打包在 LM Studio 中发布。

venvstacks 现已发布在 PyPi 上：$ pip install --user venvstacks

认识 `venvstacks`

Python 的机器学习和 AI 库非常庞大。真的是非常庞大。

— 并非出自道格拉斯·亚当斯

venvstacks 是一个全新的基于 venv 的 Python 项目，它利用 Python 的 sitecustomize.py 环境设置功能，将三层 Python 虚拟环境连接在一起：

“运行时 (Runtime)”层：包含特定 Python 解释器所需版本的环境
“框架 (Framework)”层：包含关键 Python 框架所需版本的环境
“应用程序 (Application)”层：包含可以直接启动的组件的环境

虽然这些层是分别存档和发布的，但它们的依赖项锁定是集成的。这使得应用程序层可以共享框架层中安装的依赖项，而框架层可以共享运行时层中安装的依赖项。

使用 `venvstacks` 构建和发布 Python 环境

定义环境堆栈

需要发布的环境层是在 venvstacks.toml 堆栈规范中定义的，每种类型的层定义都有一个单独的表数组。

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

[[runtimes]]
name = "cpython@3.11"
fully_versioned_name = "cpython@3.11.10"
requirements = [
    "numpy",
]

[[frameworks]]
name = "sklearn"
runtime = "cpython@3.11"
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 Package Index (PyPI) 获取，并可使用 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（如果该问题尚未被报告）。如果您不确定某种行为是否为 Bug，或者只是想提供一般性反馈而不是提交特定问题或建议，下文提到的 Discord 频道是与开发者直接联系的最佳方式。在 https://discuss.python.org/ 上的 “Packaging”类别也是提供反馈的合理场所。

我们已经有很多关于如何改进 venvstacks 的想法，它们记录在 GitHub Issue 中。

虽然我们记录了其中许多想法是因为我们计划亲自实现它们，但对于其他一些我们认为有趣并愿意接受包含的想法，我们目前并无迫切需求。

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

请在 Python Packaging Discord 服务器上的新 #venvstacks 频道中讨论 venvstacks 的相关话题。

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

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

认识 venvstacks

使用 venvstacks 构建和发布 Python 环境