quark-install

Quark のインストール

目的

別のスキル、Quark のチェックアウト、または事前生成されたワークフローの成果物に依存せずに、amd-quark をインストールまたは検証します。実際のハードウェアを検出し、PyTorch がそれに適合していることを確認したうえで、安全性を確保できる最小限の Quark インストールを選択し、承認を得て実行し、要求された機能を検証します。

前提条件

• GPU サポートは、選択した PyTorch ビルドと Quark ホイールによって異なります。実際のランタイム、ホストカーネルとドライバー、GPU アーキテクチャ（AMD の場合は gcnArchName の gfx...）を記録し、固定の ROCm バージョンや GPU ターゲットを想定せず、その環境との互換性を検証してください。
• コンテナーイメージは必要ありません。コンテナー内で実行する場合は、取得可能であればイメージ名またはダイジェストを記録し、GPU デバイスにアクセスできることを確認してください。
• QUARK_ACCELERATOR、PYTORCH_ROCM_ARCH、QUARK_BUILD_DISABLE_JIT_FALLBACK、HSA_OVERRIDE_GFX_VERSION、HIP_VISIBLE_DEVICES、CUDA_VISIBLE_DEVICES を確認し、その状態を維持してください。必要な変更は、確認済みのインストール計画に含めてください。PIP_EXTRA_INDEX_URL は、値に認証情報が含まれる可能性があるため、設定済みか未設定かだけを報告してください。

入力

• 変更する Python インタープリターまたは環境。既定ではアクティブなインタープリターを使用しますが、解決済みのパスを明示してください。
• 要求された Quark のソース：既存の環境、PyPI、AMD ネイティブホイールのインデックス、ローカルのホイール、またはローカルのソースディレクトリ。既定では汎用の PyPI ホイールを使用します。
• 任意のバージョン制約。
• コンピュートの用途：既定では GPU。CPU は、ユーザーが明示的に確認した場合に限ります。
• 必要な機能：Quark の基本的なインポート、Quark PyTorch カーネル、ONNX カスタムオペレーター、または quark-cli。

既存の環境やインストール結果の成果物は必須ではありません。ユーザーから提供されたホイールやソースディレクトリは入力であり、スキルの依存関係ではありません。

出力

必ず、処理が終了した時点でユーザーの作業ディレクトリに quark_install_result.json を書き込み、references/contracts/quark_install_result.schema.json に対して検証してください。

互換性フィールド status、quark_version、install_source、extras_installed、verification、failure_reason を保持してください。また、解決済みのインタープリター、インポートされた Quark モジュールのパス、PyTorch のバージョンとバックエンド、GPU が利用可能かどうか、CPU モードが明示的に確認されたかどうか、実行したコマンドの正確な内容、pip check の結果も記録してください。

• インストールと要求されたすべての検証に合格した場合に限り、status: "ok" を使用してください。
• 適切な既存インストールが検証できた場合、またはユーザーが変更を拒否した場合は、status: "skipped" を使用してください。
• インストールまたは検証に失敗した場合は、失敗したコマンドとエラーを正確に記録して、status: "failed" を使用してください。
• 要求されていない任意のチェックは null に設定してください。quark-cli --help が動作するという理由だけで、llm_ptq_deps: true と報告しないでください。

インストールルール

• Quark には Python 3.11、3.12、または 3.13 と、PyTorch 2.2 以降が必要です。

• amd-quark ランタイムホイールは PyTorch をインストールしません。Quark をインストールする前に、PyTorch を解決して検証してください。

• デフォルトは GPU です。CUDA/ROCm のビルドタグだけでは不十分です。GPU の準備が整っていることを確認するには、torch.cuda.is_available() が真であること、デバイス数が 1 以上であること、cuda 上でテンソル演算が正常に完了することが必要です（PyTorch では CUDA と ROCm の両方で、このデバイス表記が使用されます）。

• PyTorch が見つからない、CPU 専用である、バックエンドが一致しない、または GPU にアクセスできない場合は、停止して、対応する GPU ビルドをインストール／修正するか、CPU モードで続行するかを尋ねてください。CPU モードを黙ってインストールしたり、受け入れたりしてはいけません。

• GPU 用 PyTorch ビルドは、検出された CUDA/ROCm のサポートに一致する公式インデックスからのみインストールしてください。まず利用可能なバージョンを照会し、Python と互換性があり、torch>=2.2 を満たす安定版を選択して、正確なコマンドを提示し、承認を得てください。

  "<PYTHON>" -m pip index versions torch --index-url "https://download.pytorch.org/whl/<GPU_INDEX>"
  "<PYTHON>" -m pip install "torch==<VERSION>" --index-url "https://download.pytorch.org/whl/<GPU_INDEX>"
  

• CPU モードについて明示的な確認を得た後は、条件を指定しない PyPI インストールではなく、公式 CPU インデックスを使用してください。

  "<PYTHON>" -m pip install "torch==<VERSION>" --index-url "https://download.pytorch.org/whl/cpu"
  

• 汎用 PyPI ホイールが安全なデフォルトです。異なる PyTorch バックエンドに対応していますが、初回使用時に Quark カーネル／カスタムオペレーターをコンパイルするため、C++ コンパイラーと nvcc または hipcc が必要になる場合があります。

  "<PYTHON>" -m pip install "amd-quark"
  

• Quark の Torch インポートには現在 Transformers が必要ですが、基本の amd-quark ホイールでは依存関係として宣言されていない場合があります。カーネルの検証が要求されており、Transformers がない場合は、リリース／モデルとの互換性があるインストール内容を事前に提示して確認を得てください。より限定的な要件が判明していない限り、現時点での上限として "transformers<5.16" を使用してください。Transformers モジュールが見つからない場合は、コンパイラーの失敗ではなく、依存関係の失敗として扱ってください。

• ネイティブホイールの提供状況はリリースごとに変わります。ハードコードされた対応表や、単独の --extra-index-url から選択してはいけません。現在の PyTorch のメジャー／マイナー、CUDA/ROCm のメジャー／マイナー（または CPU）、CPython タグ、OS、アーキテクチャに、ファイル名／ローカルバージョンが完全に一致する、実際に確認した候補のみを使用してください。完全なバージョンを === で固定してください。

  "<PYTHON>" -m pip install "amd-quark===<FULL_VERSION_WITH_VARIANT>" --index-url "<AMD_INDEX_URL>" --extra-index-url "https://pypi.org/simple"
  

• ユーザーが提供したネイティブホイールにも、同じ ABI チェックを適用してください。py3-none-any ホイールは汎用です。信頼できるローカル入力の場合：

  "<PYTHON>" -m pip install "<ABSOLUTE_WHEEL_PATH>"
  "<PYTHON>" -m pip install --no-build-isolation "<ABSOLUTE_SOURCE_DIR>"
  

• ソース形式は、ディレクトリに pyproject.toml または setup.py があり、PyTorch がすでに検証済みで、ユーザーがそのソースの実行を明示的に信頼し、要求している場合にのみ使用してください。

• [cli] は要求された場合にのみ追加してください。その前に、インストール済みの onnxruntime* ディストリビューションとドライランの計画を確認してください。現在の CLI エクストラでは CPU 版の onnxruntime が追加される場合があります。onnxruntime-gpu と黙って組み合わせたり、--no-deps で依存関係を回避したりしてはいけません。

• ONNX Runtime のバリアント選択は、このスキルの対象外です。ONNX カスタムオペレーターが要求された場合は、既存のランタイムを検証して報告してください。ただし、CPU／GPU ディストリビューションを黙って選択または置換してはいけません。

• 常に同じ絶対パスの "<PYTHON>" -m pip を使用してください。修飾されていない pip や sudo pip は使用しないでください。

対話フロー

次の手順を順番に完了してください。

ステップ 1 — 環境を調査する

変更対象となる正確なインタープリターに <PYTHON> を解決してください。スペースを含むパスは引用符で囲んでください。読み取り専用のチェックを実行してください。

"<PYTHON>" -c "import platform, sys; print('executable:', sys.executable); print('prefix:', sys.prefix); print('python:', platform.python_version()); print('os:', platform.platform()); print('machine:', platform.machine())"
"<PYTHON>" -m pip --version
"<PYTHON>" -m pip show amd-quark torch
"<PYTHON>" -c "import torch; ok=torch.cuda.is_available(); n=torch.cuda.device_count(); print('torch:', torch.__version__); print('cuda:', torch.version.cuda); print('hip:', torch.version.hip); print('gpu_available:', ok); print('device_count:', n); print('device:', torch.cuda.get_device_name(0) if ok and n else None)"
nvidia-smi --query-gpu=name,driver_version --format=csv,noheader
rocm-smi --showproductname
hipcc --version

ホストで利用可能なハードウェアコマンドのみを実行してください。コマンドが見つからないことは証拠であり、ユーティリティをインストールしてよいという許可ではありません。ユニバーサルホイールが Quark カーネル／カスタムオペレーターをコンパイルする可能性があるため、初期確認中にオプションの Quark カーネル／カスタムオペレーターをインポートしないでください。

チェックポイント 1 — 計算モードを確認する

Python がサポート対象外、PyTorch が 2.2 未満、ハードウェアが不明確、PyTorch が CPU 専用、ビルド系列が検出されたハードウェアと一致しない、または GPU ビルドからデバイスにアクセスできない場合は、Quark のインストール計画を立てる前に停止してください。

次のように尋ねてください：「<EVIDENCE> が見つかりました。対応する GPU 用 PyTorch ビルドをインストール／修正しますか。それとも、明示的に CPU モードを希望しますか？」

明示的な回答なしに CPU モードで続行してはいけません。GPU モードが選択された場合は、公式インデックスを使用する正確な PyTorch コマンドを提示して承認を得てから、GPU 上で実際にテンソル演算が実行できることを確認して続行してください。

ステップ 2 — インストール方法を選択する

1. 適切なバージョンの Quark がすでにインストールされており、アップグレードや再インストールが要求されていない場合は、インストールをスキップして検証に進みます。
2. 明示的に要求され、検証済みのローカル wheel／ソースを優先します。
3. ネイティブ wheel は、候補と ABI を正確に検証した場合にのみ使用します。それ以外の場合は、ユニバーサル PyPI wheel を使用します。
4. 要求されたバージョン制約をパッケージ指定に追加します。たとえば、"amd-quark==<VERSION>" または "amd-quark[cli]==<VERSION>" です。
5. Transformers を含む、カーネルの使用に必要なすべてのパッケージ変更を、"<PYTHON>" -m pip install --dry-run "<PACKAGE_SPEC>" で事前確認します。dry-run がサポートされていない場合は、環境を変更せず、その制約を報告します。
6. インストール済みディストリビューションのメタデータを正式な情報として扱います。ソースツリーのバージョンや依存関係の制限が、別の公開リリースにも適用されるとは主張しないでください。

ステップ 3 — 変更内容を確認する

以下を提示します。

• 解決されたインタープリターと環境。
• 検出されたハードウェア、PyTorch ビルド、GPU ランタイムの結果、および確認済みの GPU／CPU モード。
• 選択した Quark のソース、およびネイティブ wheel の場合は、一致した ABI の各項目。
• dry-run で確認した依存関係の変更と、正確なコマンド。
• 検証によって C++／CUDA／HIP のコンパイルが発生する可能性があるかどうか。

「この正確なコマンドを実行してもよろしいですか？」と確認します。

CPU モードの承認とコマンドの実行には、どちらも明示的な承認が必要です。承認なしに、インストール、アップグレード、アンインストール、システムのパッケージマネージャーの呼び出し、またはオプションのコンポーネントのコンパイルを行わないでください。

ステップ 4 — インストールして検証する

承認後、確認済みのコマンドのみを実行します。必要な場合は先に PyTorch をインストール／修正し、Quark をインストールする前に、選択した計算モードを検証します。最初の失敗で停止し、出力全体を保持します。wheel をインストールした場合は、Quark のソースチェックアウト外の中立なディレクトリからインポート検証を実行し、インポートされたモジュールのパスが選択した環境内にあることを必須とします。ソース／editable インストールの場合は、確認済みのソースディレクトリに解決されることを必須とします。

基本チェックを実行します。

"<PYTHON>" -m pip check
"<PYTHON>" -c "from importlib.metadata import version; import quark, torch; print('amd-quark:', version('amd-quark')); print('quark:', quark.__version__); print('quark_file:', quark.__file__); print('torch:', torch.__version__); print('cuda:', torch.version.cuda); print('hip:', torch.version.hip)"

GPU モードでは、実際の演算を必須とします。

"<PYTHON>" -c "import torch; assert torch.version.cuda or torch.version.hip, 'CPU-only PyTorch build'; assert torch.cuda.is_available(), 'GPU runtime unavailable'; assert torch.cuda.device_count() > 0, 'No visible GPU'; x=torch.ones(1024, device='cuda'); y=(x*x).sum(); torch.cuda.synchronize(); print(torch.cuda.get_device_name(0), y.item())"

Quark カーネルが要求されている場合は、拡張機能が読み込まれたことをアサートします。ユニバーサル wheel では最初のコマンドを使用します。ネイティブ wheel では、パッケージに含まれる拡張機能が有効であることを証明するため、JIT フォールバックを無効にします。

"<PYTHON>" -c "import quark.torch.kernel; from quark.torch.kernel.hw_emulation import extensions; assert extensions.kernel_ext is not None; print('Quark kernel OK')"
"<PYTHON>" -c "import os; os.environ['QUARK_BUILD_DISABLE_JIT_FALLBACK']='1'; import quark.torch.kernel; from quark.torch.kernel.hw_emulation import extensions; assert extensions.kernel_ext is not None; print('Native Quark kernel OK')"

要求されたその他のチェックのみを実行します。

"<PYTHON>" -m quark.experimental.cli.main -h
"<PYTHON>" -c "import onnxruntime as ort; from quark.onnx.operators.custom_ops import get_library_path; p=get_library_path('CPU'); so=ort.SessionOptions(); so.register_custom_ops_library(p); print('Quark ONNX custom ops OK:', p)"

カーネルのコマンドを両方とも実行しないでください。基本インストール、GPU ランタイム、オプション機能はそれぞれ分けて報告します。quark_install_result.json を作成して検証します。インストールの終了コードやビルドタグだけを根拠に、成功したと主張しないでください。

復旧

• CPU のみ、または GPU が利用できない場合： GPU をデフォルトのままにし、ハードウェア／ビルド／実行時の根拠を示したうえで、GPU 版 PyTorch を修復するか、CPU を明示的に承認するかを確認してください。黙って CPU に切り替えないでください。
• 完全に一致するネイティブホイールがない場合： 一致しない ABI の要素をすべて示し、ユニバーサルホイールを提案して、再度承認を求めてください。
• コンパイラーエラー： ユニバーサルホイールのカーネル／カスタム演算子のチェックには、C++ コンパイラーに加えて nvcc または hipcc が必要になる場合があります。不足しているツールを報告し、システムを変更する前に承認を得てください。
• Transformers がない場合： Transformers が存在しないと、拡張機能の読み込み後に Quark Torch のインポートが失敗する場合があります。正確な ModuleNotFoundError を示し、互換性のある Transformers のインストール内容を事前に提示してから、再試行の承認を求めてください。
• CLI／ONNX Runtime の競合： インストール済みまたはインストール予定の onnxruntime* ディストリビューションをすべて示してください。別環境の使用、または明示的に改訂した計画を優先してください。--no-deps で競合を隠してはいけません。
• 依存関係またはインポートの失敗： pip check、失敗したコマンドの正確な内容、バージョン、完全なエラーをそのまま保持してください。強制的なダウングレードより、新しい環境を優先してください。
• 誤った環境、またはソースによる名前のシャドーイング： sys.executable、pip --version、ディストリビューションのバージョン、quark.__file__ を比較してください。中立的なディレクトリから、絶対パスで指定した単一のインタープリターを使って、ホイールの検証を再実行してください。
• ネットワーク／インデックスのエラー： URL とエラーを正確に保持してください。確認なしにインデックスを切り替えたり、繰り返し再試行したりしないでください。
• サポート対象外の Python： 新しい Python 3.13 環境を提案し、承認後にステップ 1 からやり直してください。