quantized-export

量子化エクスポート

checkpoint-promotion が PROMOTE の判定を引き渡した後の最後の工程です。4段階のゲートを通過したチェックポイントでも、対象ランタイムに適した形式でエクスポートされ、エクスポート後も動作することが確認されるまではデプロイされません。REJECT の判定がこのスキルに到達することはありません — エクスポートは昇格済みのチェックポイントからのみ開始されます。

入力: 昇格済みチェックポイント（または LoRA アダプター）と、対象のデプロイ環境 — GPU クラス、配信スタック、および長コンテキスト／コード／数学ワークロードが対象範囲かどうか。 出力形式: 選択した形式でエクスポートされたアーティファクトと、エクスポート前後の 3〜5 件のゴールデン出力を比較するスモークテスト差分レポート。

フォーマットマップ

形式は習慣ではなく、ハードウェアとデプロイ形態で選んでください — 誤った選択はスループットの余力を無駄にするか、特定のワークロードでサイレントに壊れます（「ワークロード別の上書き」を参照）。

• FP8 は Hopper クラス以降の GPU におけるデフォルトです。 bf16 に近い品質を約半分のメモリで維持し、対象 GPU が対応していてエッジデバイスの制約がない場合は常に安全な第一候補です。
• **AWQ INT4 は FP8 ハードウェア対応より前の古い GPU を対象とします。**GPTQ は新規デプロイでは置き換え済みです — 新規エクスポートで手を伸ばさないでください。AWQ は同じビット幅でより優れた精度保持と、より広い現行ツーリングのサポートを持ちます。
• imatrix から構築した Q4_K_M 量子化の GGUF は、エッジ／llama.cpp 向けの形式です。 ローカルまたは CPU 隣接のデプロイに使用し、GPU 配信のスループット向けには使用しないでください — これはデータセンター GPU での tokens/sec ではなく、フットプリントを最適化します。
• NVFP4 は Blackwell の大規模デプロイ専用です — そして GB10 では明示的に NOT（非対応）です。 SM121（GB10）上の NVFP4 は FP8 より約 32% 遅く 動作します。これはカーネルが sm_121a でコンパイルされない限り、ハードウェアにネイティブな cvt.e2m1x2 パスが存在しないためです。GB10 を対象に NVFP4 を選ぶのはアップグレードではなくリグレッションです — そこでは代わりに FP8 を選んでください。
• マージ済みか LoRA のみかは、量子化形式とは別の軸です。 マージ済みエクスポートはアダプターをベース重みに折り込みます: アーティファクトは大きくなりますが、配信時にベースモデルへの依存がありません。LoRA のみはアダプターを分離したままにします: アーティファクトははるかに小さくなりますが、配信スタックはそれと並べてまったく同じベースモデルをロードする必要があります — ミスマッチまたは誤ったリビジョンのベースはサイレントに出力を変えます。アーティファクトのポータビリティがストレージより重要な場合はマージ済みを選び、ディスクフットプリントやマルチアダプター配信がより重要な場合は LoRA のみを選んでください。

具体的な選択例

よくあるシナリオ向けのルックアップテーブルとして読む、形式選択の核心的なトレードオフ:

対象	ワークロード	形式
データセンター GPU	汎用チャット	FP8
データセンター GPU	長コンテキスト／コード／数学	FP8 または W8A8 — INT4 は決して不可
旧世代 GPU	汎用	AWQ INT4
エッジデバイス／ラップトップ	llama.cpp 配信	GGUF Q4_K_M + imatrix
GB10	任意のワークロード	vLLM nightly 経由の FP8、またはローカルで llama.cpp 経由の GGUF — NVFP4 はスキップ

# quick decision snippet — see the table above for the full map
hopper_or_newer: fp8
older_gpu: awq-int4
edge_llama_cpp: gguf-q4_k_m+imatrix
gb10_any_workload: fp8-vllm-nightly   # never nvfp4 on GB10

ワークロード別のオーバーライド

上記のフォーマットマップはデフォルトであり、あらゆるワークロードに耐えるルールではありません。長いコンテキスト、コード、数学のワークロードは INT4 で破綻します — 量子化誤差は長いシーケンスやトークンレベルの精密な推論にわたって累積し、短く汎用的なプロンプトでは表面化しない形で影響を及ぼします。これら3つのワークロードクラスのいずれについても、FP8 または W8A8 のままにしてください。たとえ対象ハードウェアがコスト面で INT4 を正当化するように見えてもです。

• このオーバーライドを MMLU や同種の広範な知識ベンチマークで検証しないでください — それらはこの失敗モードに負荷をかけません。実際のタスク評価で測定してください — eval-harness-first のゴールデンとグレーダーを、エクスポート済みアーティファクトを通して実行するのです — なぜなら長いコンテキスト、コード、数学における INT4 の劣化は、知識ベンチマークを動かすよりもずっと早い段階で、タスク固有の失敗（コンテキストの欠落、構文の破壊、算術エラー）として現れるからです。
• これら3つのワークロードクラスのいずれかで INT4 エクスポート後にタスク評価がリグレッションした場合、修正はフォーマットの切り替えであり、量子化レシピの再調整ではありません — 同じビット幅の AWQ と GPTQ のバリアントは、これらのワークロードにおいて同じ累積誤差の失敗モードを共有します。

スモークテスト

エクスポートのバグはファイルレベルではサイレントです — 不正な形式のエクスポートでも読み込み可能なアーティファクトは生成されるため、ファイルの存在確認は何も証明しません。スモークテストはすべてのエクスポートで必須であり、「動くはず」のフォーマットであっても例外はありません。

1. エクスポート済みアーティファクトを実際のターゲットランタイムに読み込みます — FP8/AWQ なら vLLM、GGUF なら llama.cpp です。本番環境で提供するフレームワークとは異なるフレームワークでの簡単な健全性確認の読み込みではいけません。
2. 3〜5 個のゴールデンプロンプトをそれを通して実行します — これらは eval-harness-first が管理する同じ eval/goldens.jsonl から取得してください。新たにその場で用意したセットからではありません。
3. 各出力を同じプロンプト、同じ決定論的サンプリング設定でのエクスポート前の生成結果と比較します — 貪欲法デコード（temperature 0）と固定シードを使用し、エクスポート前とエクスポート後の実行の間で永続化して再利用してください。名目上同一の設定というだけではいけません。ロスレスエクスポートの場合、バイト一致がゲートです — 差分があればそれはバグです。 ロッシー（量子化）エクスポートの場合、バイト一致は失敗することが想定されます。代わりにゲートとなるのはタスクグレーダーの判定一致です — references/export-commands.md のスモークテストスクリプトの骨子を参照してください。

これは手動チェックではなく、ゲートとして実行してください:

python smoke_test.py "$EXPORT_PATH" \
    eval/goldens.jsonl pre-export-outputs.jsonl
# non-zero exit on any pre/post mismatch

失敗のシグネチャ

クリーンな合否フラグではなく、エクスポートのバグが実際にどのように現れるか:

• テンプレートの不一致は、文字化けした出力や途切れのない連続した出力として現れます — エクスポートに焼き込まれたチャットテンプレートが、チェックポイントのトレーニングおよび評価に使用されたものと一致しないため、ターンの境界や特殊トークンが誤った位置に配置されます。
• lm_head に誤った量子化が適用されると、流暢に見えてもテンプレートから外れた、あるいは意味的に無意味な出力として現れます — ネットワークの残りの部分はきれいに量子化されたにもかかわらず、出力ヘッドが必要としていた精度を失ったのです。

このステップを省略したエクスポートを決して出荷しないでください — チェックポイントの PROMOTE 判定は、エクスポート前のチェックポイントが良好であることを示すものであり、エクスポートパイプラインについて何も示していません。最初のエクスポート後だけでなく、量子化メソッドやランタイムのバージョンが上がるたびに再実行してください。すべてのフォーマットの実行可能なコマンドシーケンスとスモークテストスクリプトの骨子: references/export-commands.md。

関連スキル

• checkpoint-promotion — このスキルにとって唯一の有効な 上流ソースです。PROMOTE の判定がないチェックポイントは エクスポートに到達しません。
• eval-harness-first — このスキルのスモークテストが 3〜5 個の プロンプトを取得する元となる eval/goldens.jsonl を所有し、 また Workload Overrides セクションが長文コンテキスト／コード／数学 の検証に要求するタスク評価も所有します。
• finetuning-method-selection — その references/model-catalog.md は、上記の Format Map から フォーマットを選ぶ前に、ハードウェアクラスの前提（ベースモデルが どの GPU 世代を対象とするか）を確認する場所です。

Spark ユーザー: GB10 では、llama.cpp 経由の GGUF が ローカル配信に適しており、vLLM のナイトリービルド経由の FP8 配信が もう一つの実績ある手段です — NVFP4 はそこでは避けるべき唯一の フォーマットです（上記の Format Map の例外を参照）。dgx-spark-ops プラグインをインストールしたら、Spark 固有の配信や熱に関する 質問はここで再検討するのではなく、そのスキルに委ねてください。