SambaStack Pef カスタムリソース - SambaNova ドキュメント

PEF (Processor Executable Format) は、1 つのモデル構成に対するコンパイル済みアーティファクトです。Pef リソースは、この実行ファイル 1 つを、モデルアーキテクチャ、バッチサイズ、最大シーケンス長など、サポート内容を記述するメタデータとともに登録します。どの PEF、シーケンスサイズ、バッチサイズを使用するかは ModelProfile が選択するため、バンドルやデプロイメントでは、個々の PEF ではなくプロファイルを参照します。Pef リソースを自分で作成するのは、SambaStack がまだサポートしていないモデルアーキテクチャを導入する場合のみです。 Pef リソースは apiVersion: sambanova.ai/v1alpha1 を使用します。

構造

apiVersion: sambanova.ai/v1alpha1
kind: Pef
metadata:
  name: llama-4-maverick-ss131072-bs1
spec:
  metadata:
    model_arch: llama-4-maverick
    batch_size: 1
    max_seq_length: 131072
    max_completion_tokens: 131072
    job_type: infer
    num_rdus: 16
    rdu_arch: SN40L-16
    task_name: mllama
    continuous_batching: false
    use_context_cache: false
    constrained_decoding: false
    is_spec_prefill: false
  versions:
    "1":
      source: gs://<SAMBASTACK_ARTIFACTS_BUCKET>/path/to/model.pef
      cached_path: gs://<SAMBASTACK_ARTIFACTS_BUCKET>/path/to/model.pef
      ckpt_sharing_uuid: c5f61b8d9a1f41ed02b7d5d6098f6abc
      pef_status: stable
      num_tokens_at_a_time: 20
      prefill_graphs:
      - 131072
      vision_embedding_pef: gs://<SAMBASTACK_ARTIFACTS_BUCKET>/path/to/vision.pef
      vision_embedding_pef_cached_path: gs://<SAMBASTACK_ARTIFACTS_BUCKET>/path/to/vision.pef
  owner: no-reply@sambanova.ai
  secretName: sambanova-artifact-reader

識別情報と形状

フィールド	必須	説明
`spec.metadata.model_arch`	はい	この PEF のアーキテクチャ。この PEF と互換性のあるチェックポイントを決定します。
`spec.metadata.batch_size`	はい	この PEF がコンパイルされた対象のバッチサイズ。
`spec.metadata.max_seq_length`	はい	この PEF がサポートする最大シーケンス長。
`spec.metadata.max_completion_tokens`	はい	この PEF がサポートする生成トークンの最大数。`max_seq_length` と等しい必要があります。
`spec.metadata.job_type`	いいえ	この PEF が推論用と学習用のどちらにコンパイルされたか。例: `infer`。
`spec.metadata.num_rdus`, `spec.metadata.rdu_arch`	いいえ	この PEF がコンパイルされた対象の RDU 数と RDU アーキテクチャ。例: `SN40L-16`。
`spec.metadata.task_name`	いいえ	この PEF が使用するアプリドライバー内のタスク。未設定の場合は、テキスト生成タスクがデフォルトになります。
`spec.metadata.mapping`, `spec.metadata.mixed_precision_mode`	いいえ	トレーサビリティのために記録されるコンパイル設定: 使用されたマッピングと、混合精度モード。
`spec.metadata.vocab_size`	いいえ	この PEF がコンパイルされた対象の語彙サイズ。
`spec.metadata.pef_version`	いいえ	この PEF のコンパイル時に対象とした PEF プロトコルのバージョン。

機能サポートフラグ

これらの値は、この PEF から構築されるプロファイルの features リストを決定します。

フィールド	必須	説明
`spec.metadata.continuous_batching`	いいえ	この PEF が連続バッチング (continuous batching) をサポートするかどうか。デフォルトは `false` です。
`spec.metadata.use_context_cache`	いいえ	この PEF が Prompt Caching (プロンプトキャッシング) をサポートし、使用するかどうか。デフォルトは `false` です。
`spec.metadata.constrained_decoding`	いいえ	この PEF が制約付きデコーディング (constrained decoding) をサポートするかどうか。デフォルトは `false` です。
`spec.metadata.is_spec_prefill`	いいえ	この PEF を投機的プリフィル (speculative prefill) のスペキュレーターとして使用できるかどうか。デフォルトは `false` です。
`spec.metadata.cache_batch_size`, `spec.metadata.decode_batch_size`	いいえ	連続バッチングで使用されるキャッシュバッチサイズとデコードバッチサイズ。
`spec.metadata.k`	いいえ	2 エキスパートのドラフト/ターゲット方式において、投機的デコーディングのターゲットモデルの PEF で使用される `k` 値。
`spec.metadata.mtp_weight_category`	いいえ	この PEF に融合されたマルチトークン予測 (multi-token prediction; MTP) ドラフターのコンパイル時の重みカテゴリ。例: `GEMMA4_MTP_WEIGHT`。単一 PEF 構成の MTP PEF にのみ設定します。そのドラフターの重みは、ロード時に別個のドラフターチェックポイントからオーバーレイされます。`k` とは別のものです。
`spec.metadata.dynamic_dims`	いいえ	この PEF で利用可能な動的次元。`batch_size` やシーケンス長の次元など。
`spec.metadata.vision_dynamic_dims`	いいえ	この PEF の Vision コンポーネントで利用可能な動的次元。マルチモーダルモデルで使用します。

バージョン

spec.versions 配下の各キーはバージョン文字列で、その値が PEF の 1 つのビルドを記述します。

フィールド	必須	説明
`spec.versions.<version>.source`	はい	この PEF バージョンのダウンロード元の場所。
`spec.versions.<version>.cached_path`	はい	Legalizer データベースにキャッシュされている、この PEF へのパス。パス置換はこの値には影響しません。
`spec.versions.<version>.ckpt_sharing_uuid`	はい	チェックポイント共有の関係を定義する識別子。同じ識別子を持つ PEF はチェックポイントを共有できます。
`spec.versions.<version>.pef_status`	はい	この PEF バージョンのライフサイクルステータス。デフォルトは `preview` です。PEF とチェックポイントのライフサイクルステータスをご参照ください。
`spec.versions.<version>.prefill_graphs`	いいえ	このバージョンにコンパイル時に組み込まれた離散的なプリフィル長。`metadata.dynamic_dims` と組み合わせて、このバージョンがゲートウェイのバッチングキューのルーティング向けに通知するプロンプトサイズの計算に使用され、プロファイル上では `promptBatchingBuckets` として現れます。導出できない場合は未設定のままになります。
`spec.versions.<version>.num_tokens_at_a_time`	いいえ	この PEF の呼び出し 1 回あたりに生成されるトークン数。
`spec.versions.<version>.copy_pef`	いいえ	コピー PEF のソースパス。
`spec.versions.<version>.vision_embedding_pef`, `spec.versions.<version>.vision_embedding_pef_cached_path`	いいえ	対になる Vision 埋め込み PEF のソースパスとキャッシュパス。マルチモーダルモデルで使用します。
`spec.versions.<version>.pef_name_override`, `spec.versions.<version>.copy_pef_name_override`, `spec.versions.<version>.vision_embedding_pef_name_override`	いいえ	後方互換性のために残されている名前オーバーライド。

所有者とアクセス

フィールド	必須	説明
`spec.owner`	はい	この PEF の所有者。
`spec.secretName`	はい	アーティファクトのダウンロードに必要な単一の Secret の名前。

spec.metadata.seq_lengths は現在は存在しません。PEF がサービングするシーケンス長は、metadata.max_seq_length に metadata.dynamic_dims とバージョンの prefill_graphs を組み合わせて導出されるようになりました。

PEF とチェックポイントのライフサイクルステータス

SambaStack は、サポートライフサイクルを示すために、PEF CR のバージョンには pef_status フィールドを、モデル CR のチェックポイントバージョンには checkpoint_status フィールドを割り当てます。これらのステータスを理解しておくと、PEF やチェックポイントのバージョンを選択する際に、十分な情報に基づいた判断ができます。 PEF・チェックポイントバージョンのステータス値 PEF CR の各バージョンエントリには pef_status フィールドが含まれます。モデル CR のチェックポイントバージョンでは checkpoint_status を使用します。どちらも同じ値のセットを共有します。

ステータス	説明
`preview`	十分なテストとサポートが行われていない状態です。信頼性やパフォーマンスに未知の問題がある可能性や、機能が限定されている可能性があります (例: Function calling の部分的なサポート)。本番ワークロードには推奨されません。
`stable`	完全にサポートされ、テストされている状態です。
`deprecated`	信頼性またはパフォーマンスに既知の問題がある状態です。安定版バージョンへの移行を可能にするため、限定的な移行期間 (提供終了の告知から最長 3 か月) の間は引き続き利用できます。
`removed`	使用できなくなった状態です。バージョンエントリはトレーサビリティと監査性のために PEF CR またはモデル CR に保持されますが、パスがすでに存在しない可能性があり、参照するとデプロイが失敗する原因になります。

これらの値は個々のアーティファクトバージョンを対象としたものであり、モデルそのものを対象としたものではありません。PEF が deprecated とマークされていても、そのモデルが提供終了予定というわけではありません。モデルレベルのライフサイクルステージと、モデルが Retired (提供終了) になる前に受け取る通知については、SambaStack モデルライフサイクルをご参照ください。

ステータス付きの PEF CR バージョンの例

versions:
  '1':
    source: gs://ext-sambastack-artifacts-prod-0/path/to/pef_v1.pef
    pef_status: deprecated
  '2':
    source: gs://ext-sambastack-artifacts-prod-0/path/to/pef_v2.pef
    pef_status: stable

バージョンのステータスを確認するには、kubectl describe pef <pef-name> または kubectl describe model <model-name> を実行し、Versions セクションの pef_status または checkpoint_status フィールドを確認してください。

参考情報

ModelProfile

1 つのモデルアーキテクチャについて、機能互換性のある PEF をグループ化します

モデルとバンドルのデプロイ

PEF、プロファイル、モデル、バンドル、デプロイメントの関係

はじめに

サービス管理

ハードウェア管理

リファレンスアーキテクチャ

リソース

PEF

構造

識別情報と形状

機能サポートフラグ

バージョン

所有者とアクセス

PEF とチェックポイントのライフサイクルステータス

参考情報

ModelProfile

モデルとバンドルのデプロイ

​構造

​識別情報と形状

​機能サポートフラグ

​バージョン

​所有者とアクセス

​PEF とチェックポイントのライフサイクルステータス

​参考情報

ModelProfile

モデルとバンドルのデプロイ

構造

識別情報と形状

機能サポートフラグ

バージョン

所有者とアクセス

PEF とチェックポイントのライフサイクルステータス

参考情報