quark-torch-llm-ptq

Quark Torch PTQ

目的

PyTorch／Hugging Face の LLM について、モデルの特定から AMD Quark PTQ の確認までを行います。受付、計画、マニフェストの生成、実行、出力の検証を、自己完結した 1 つのワークフローとして実施します。

このスキルは、量子化済みモデルの作成までを対象とします。.onnx モデル入力は受け付けず、モデルのトレーニングやファインチューニング、Quark のパッケージ／ソースファイルの変更も行いません。

前提条件

• Python 3.11～3.13、アクセラレーターに対応した PyTorch 2.2 以降、amd-quark[cli]、および datasets。
• 必要な ROCm バージョンと GPU アーキテクチャは、PyTorch のビルドと選択した量子化方式によって異なります。実際のランタイム、GPU アーキテクチャ（AMD では gcnArchName の gfx...）、ホストカーネル、ドライバーを記録し、確定した計画がサポートされていることを確認してください。
• コンテナーイメージは不要です。コンテナー内で実行する場合は、利用可能であればイメージ名またはダイジェストを記録し、GPU デバイスにアクセスできることを確認してください。
• HIP_VISIBLE_DEVICES、CUDA_VISIBLE_DEVICES、HSA_OVERRIDE_GFX_VERSION、PYTORCH_ROCM_ARCH、PYTORCH_HIP_ALLOC_CONF を確認し、保持してください。デバイスの可視性、アーキテクチャ、またはメモリー割り当てに変更が必要な場合は、確定した計画に含めてください。

入力

• モデルのソース：Hugging Face のリポジトリー ID またはローカルのモデルディレクトリー。
• 出力ディレクトリー。
• 量子化の要件：希望する精度／方式、対象ハードウェア、精度の優先度、任意のキャリブレーション設定。
• 任意の環境情報：Python、PyTorch、アクセラレーター、利用可能なメモリー、インストール済みの amd-quark と Transformers のバージョン。

既存のワークフロー成果物を必須としないでください。このスキルのローカル参照に従い、ユーザーの作業ディレクトリー内にすべての成果物を作成してください。

• references/model-intake.md
• references/quant-plan.md
• references/environment.md
• references/troubleshooting.md

出力

実行前または実行中に、次の 3 つの成果物を作成してください。

1. references/contracts/model_analysis.schema.json に照らして検証した model_analysis.json。
2. references/contracts/quant_plan.schema.json に照らして検証した quant_plan.json。
3. references/contracts/run_manifest.schema.json に照らして検証した run_manifest.yaml。

量子化済みモデルとその設定／トークナイザーファイルは、確定した出力ディレクトリーの下に書き込みます。実際に生成されたファイルと最終ステータスをマニフェストに記録してください。

対話の流れ

以下の 4 つのステップを、必ず順番に完了してください。具体的な情報、成果物、コマンドを提示してください。各チェックポイントで停止し、ユーザーの応答を待ってください。

ステップ 1 — モデルの受付

1. モデルのソースがローカルかリモートかを確認します。ローカルの場合は絶対パスに解決し、ディレクトリーと config.json の存在を確認します。リモートの場合はリポジトリー ID をそのまま保持します。
2. references/model-intake.md に従います。設定のみを読み込み、受付中にモデルの重みを読み込まないでください。
3. model_type、アーキテクチャ／読み込み時のヒント、隠れ層の情報、マルチモーダルまたは MoE の兆候、デフォルトの除外項目、互換性のリスク、量子化可能な線形層の妥当な推定値を特定します。
4. スキーマに適合する model_analysis.json を作成し、その概要を提示します。

チェックポイント 1 — モデル分析の確認

モデル分析を確認または修正するよう、ユーザーに尋ねてください。

ユーザーが確認するまで、量子化の計画を立てないでください。

ステップ 2 — 量子化計画

1. references/quant-plan.md に従い、確認済みの分析結果とユーザーの優先事項を使用します。
2. 全体スキーム、任意の KV キャッシュスキーム、パターンごとのオーバーライド、除外項目、アルゴリズム、キャリブレーションデータを選択して説明します。
3. スキーム、アルゴリズム、モデルテンプレートのサポート状況は、バージョンによって異なるものとして扱います。選択内容の確認が必要な場合は、現在インストールされている Quark API または quark-cli torch-llm-ptq --help を使用してください。過去の選択肢数を当てにしないでください。
4. 判断表を示し、スキーマに準拠した quant_plan.json を作成して、承認されるまで requires_confirmation: true に設定します。

チェックポイント 2 — 量子化計画を確認する

計画全体の確認または修正をユーザーに求めます。

確認後、requires_confirmation を false に更新します。ユーザーが判断内容を変更した場合は、続行する前に計画を書き直して再検証します。

ステップ 3 — マニフェストと実行の確認

amd-quark[cli] によってインストールされたパブリックコマンド quark-cli torch-llm-ptq を使用します。その実装モジュールを直接インポートしたり、別の PTQ ランナーを見つけたり、コピー、生成、パッチ適用したりしないでください。

引数配列で安全に扱える、次と同等のコマンドを作成します。

quark-cli torch-llm-ptq \
  --model_dir "<MODEL_OR_ABSOLUTE_LOCAL_PATH>" \
  --output_dir "<ABSOLUTE_OUTPUT_PATH>" \
  --quant_scheme "<SCHEME>" \
  --num_calib_data "<N>" \
  --seq_len "<LENGTH>" \
  --device cuda \
  --no_trust_remote_code

確認済みのオプションのみを追加します。

• --dataset <NAME> と --batch_size <N> は、計画で CLI のデフォルトから変更した場合に使用します。
• 確認済みの KV キャッシュ量子化には --kv_cache_dtype <SCHEME> を使用します。
• オーバーライドごとに --layer_quant_scheme <PATTERN> <SCHEME> を 1 つ指定します。
• 必要な場合は --quant_algo <comma-separated-list> を指定します。
• テンプレートのデフォルトをオーバーライドする場合に限り、--exclude_layers <patterns...> を指定します。
• 制約を把握している場合は --multi_device を指定します。
• ユーザーがリモートモデルコードの実行を明示的に許可しない限り、--no_trust_remote_code を指定します。このフラグを省略すると、CLI はリモートコードを信頼します。
• 要求された範囲がモデル出力のみで厳密に終わる場合は、--skip_evaluation を指定します。
• CLI がサポートするデフォルト以外のデータセットで評価を行うよう要求された場合は、--evaluation_dataset <NAME> を指定します。

ローカルのモデルディレクトリと出力ディレクトリを絶対パスに解決し、ユーザーが指定したすべてのパスと値を引用符で囲みます。ROCm では、--device cuda は引き続き PyTorch のデバイス表記です。必要に応じて、GPU の割り当てには HIP_VISIBLE_DEVICES を使用します。amd-quark を提供するものと同じ Python 環境から quark-cli を解決します。

次の内容を含む run_manifest.yaml を作成します。

• workflow: quark-torch-ptq
• 入力パスと出力パス。
• 4 つすべてのチェックポイントの理由。
• model_analysis.json を生成する analyze ステップ。
• quant_plan.json を生成する plan ステップ。
• run_manifest.yaml を生成する generate ステップ。
• 正確なコマンドと想定される出力ディレクトリを含む run ステップ。

コマンドを提示する前に、references/environment.md を使用して環境を確認します。パッケージがない場合や、アクセラレーターに適合しない PyTorch ビルドがある場合は、この段階で明らかにし、実行の確認後まで持ち越さないでください。

コマンド全体、出力先、推定リソース要件、リモートコードの選択内容、想定される出力を提示します。

チェックポイント 3 — 実行を承認する

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

これが実行の承認段階です。「はい」「実行して」「実行」などの明示的な承認を得るまで、出力ディレクトリの作成、モデルウェイトのダウンロード、環境の変更、PTQ の実行を行わないでください。事前の計画確認は、実行の承認にはなりません。

ステップ 4 — 実行と検証

チェックポイント 3 で承認された後に限り、次を行います。

1. 必要に応じて出力ディレクトリを作成します。
2. 確認済みの正確な quark-cli コマンドを実行します。
3. 出力を監視します。失敗した場合は停止し、コマンド、終了ステータス、エラー全文、バージョン、リソースの状態を収集してから、references/troubleshooting.md を使用します。理由なく再試行しないでください。
4. 成功した場合は出力ディレクトリを確認し、実際のモデルシャード、設定ファイルとトークナイザーファイル、サイズ、形式、要求された指標を報告します。
5. 記録済みのコマンドは変更せず、確認できたステータスと出力を run_manifest.yaml に更新します。

チェックポイント 4 — 検証済みの結果を提示する

検証済みの結果を提示し、ユーザーに承認するか、範囲を限定した追加対応を依頼するか尋ねます。

終了ステータスだけで成功を主張してはいけません。想定したファイルが存在しない場合は、部分的な結果または失敗として報告し、診断情報を保持します。

復旧

• 成果物が見つからない、または無効な場合：対応するローカルの参照資料から再生成し、ローカルスキーマに照らして検証します。検証エラーを回避するためにフィールドをでっち上げてはいけません。
• インテークに不確実性がある場合：analysis_status を partial に設定し、リスクを記録して不足している情報を尋ねます。メタデータを埋めるだけの目的で重みを読み込んではいけません。
• 未対応のモデルタイプまたはスキームの場合：インストール済みの Quark に関する根拠を提示し、計画を変更するか確認します。インストール済みの CLI にパッチを当ててはいけません。
• OOM またはデバイスの障害が発生した場合：失敗したマニフェストを保持し、キャリブレーションサンプル数の削減、シーケンス長の短縮、複数デバイスでの実行など、最小限の計画変更を提案します。チェックポイント 2 に戻ります。
• 依存関係または互換性の問題が発生した場合：インストール済みのバージョンと必要なバージョンを正確に提示します。パッケージを変更する前に確認を得てから、新たに記録したコマンドを使用してチェックポイント 3 に戻ります。
• ユーザーが意図を変更した場合：影響を受ける最も早いチェックポイントに戻り、引き続き有効な成果物を保持します。実行確認を決して省略してはいけません。