venvstacksの紹介: 階層型Pythonバーチャル環境

最近行ったLM Studio 0.3.4でのApple MLXのサポートを発表した際に、"... 独立してダウンロード可能なPythonアプリケーション環境の統合されたセット"を作成するためのPythonユーティリティをほのめかしました。

本日は、このユーティリティをオープンソース化いたします。 venvstacksをぜひお試しください! [Githubリポジトリ]

venvstacksは、LM StudioでPythonアプリケーションであるMLXエンジンを出荷することを可能にし、エンドユーザーにPythonの依存関係をインストールする必要がありません。

venvstacksはPyPiでライブされています:$ pip install --user venvstacks

`venvstacks`を見てみましょう

Pythonの機械学習およびAIライブラリは非常に大きいです。本当に大きいです。

— ダグラス・アダムスではありません

venvstacksは新しいvenvベースのPythonプロジェクトであり、Pythonのsitecustomize.py環境セットアップ機能を使用して3層の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 環境（基本実行時環境、または定義された実行時環境の 1 つに基づくレイヤー仮想環境）に変換する手順を実行します。環境が明示的にロックされていない場合、ビルド手順は必要に応じてロックします。

このコマンドは「ビルドパイプライン」コマンドでもあり、ロック、ビルド、公開を 1 ステップで実行できます（詳細についてはコマンドラインヘルプを参照してください）。

環境レイヤーアーカイブの公開

$ 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` in LM Studio

オープンソースの mlx-engine は、MLX フレームワークレイヤーと CPython 3.11 ベースランタイムレイヤー上で実行されるアプリケーションレイヤー環境の起動モジュールとして、LM Studio デスクトップアプリケーションにデプロイされています。

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 チャンネルで開発者に直接連絡するのが最良の方法です。`[object Object]` の "パッケージング" カテゴリも、フィードバックを提供する適所です。

他にも、さまざまな方法を思い付いています。venvstacks は改善点があるかもしれません。

それらのアイデアの多くは、自分たちで実装する予定なので記録しています。ただ、興味深いアイデアもあり、入ってきてもいいと思っていますが、すぐに必要なものではないため記録しているものもあります。

詳細については、venvstacks 開発者向けドキュメントを参照してください。

Python Packaging Discord Server の新しい#venvstacks チャンネルで venvstacks について詳しく話しましょう。

LM Studio Discord Server の#dev-chat チャンネルで LM Studio での mlx-engine と venvstacks の使用について詳しく話しましょう。

Mac / Windows / Linux 用の LM Studio は、https://lmstudio.dokyumento.jp/download からダウンロードできます。

venvstacksを見てみましょう

venvstacksを使用してPython環境を構築し、公開する