> ## Documentation Index > Fetch the complete documentation index at: https://docs.sambanova.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # カスタムチェックポイントのデプロイ SambaStack では、独自のカスタムチェックポイントやファインチューニング済みのチェックポイントを、[標準提供モデルのデプロイ](https://docs.sambanova.ai/docs/ja/v1.2.0/sambastack/service-administration/model-deployment/deploying-model-bundles.md)と同じ方法で推論用にデプロイできます。必要なのは、チェックポイントをプラットフォームで使用できるように準備するためのいくつかの追加ステップだけです。準備とデプロイが完了すれば、カスタムチェックポイントは SambaStack にデプロイする他のチェックポイントとまったく同じように動作します。 ## 概要 カスタムチェックポイントのデプロイは、大きく分けて次の 4 つの作業で構成されます。 1. [チェックポイント変換ツール](https://docs.sambanova.ai/docs/ja/v1.2.0/sambastack/service-administration/model-deployment/checkpoint-conversion-tool.md)を使用して、**チェックポイントを SambaNova 互換形式に変換**する。 2. SambaNova から提供されたサービスアカウントに読み取り権限を付与したプライベートな Google Cloud Storage バケットに**変換済みチェックポイントをアップロード**する。または、クラスターから読み取り可能な NFS 上に配置する。 3. モデルマニフェスト (Model Manifest) を作成して**チェックポイントを登録**する。 4. パスと名前を指定して、**デプロイ用の Bundle でチェックポイントを参照**する。 > [!NOTE] > > このワークフローを開始する前に、チェックポイントの変換プロセスを完了しておいてください。手順は[チェックポイント変換ツール](https://docs.sambanova.ai/docs/ja/v1.2.0/sambastack/service-administration/model-deployment/checkpoint-conversion-tool.md)のページをご参照ください。 ## 前提条件 カスタムチェックポイントをデプロイする前に、以下を準備してください。 * SambaNova 互換形式に変換済みのチェックポイント ([チェックポイント変換ツール](https://docs.sambanova.ai/docs/ja/v1.2.0/sambastack/service-administration/model-deployment/checkpoint-conversion-tool.md)を参照) * NFS マウント済みのストレージ、または Google Cloud Storage (GCS) バケットへのアクセス * SambaNova から提供されたサービスアカウントの JSON ファイル * SambaStack クラスターにアクセスできるように構成された `kubectl` * Bundle と Bundle Template を含む、[モデルデプロイ](https://docs.sambanova.ai/docs/ja/v1.2.0/sambastack/service-administration/model-deployment/deploying-model-bundles.md)の概念の理解 ## カスタムチェックポイントの対応モデル カスタムチェックポイントのデプロイは、SambaStack の拡大を続けるベースモデル群でサポートされています。カスタムチェックポイントに対応するモデルは、[対応モデルとバンドル](https://docs.sambanova.ai/docs/ja/v1.2.0/sambastack/service-administration/model-deployment/supported-models-and-bundles.md)の表でご確認ください。 ## カスタムチェックポイントのデプロイ手順 ### 1. チェックポイントの変換 カスタムチェックポイントやファインチューニング済みのチェックポイントは、デプロイする前に、SambaNova の SN40L ハードウェアに最適化された形式に変換する必要があります。SambaNova は、ローカルで実行できる Docker コンテナとして**チェックポイント変換ツール**を提供しています。このツールは変換済みチェックポイントのアーティファクトを生成し、それを SambaStack にアップロードして推論用にデプロイできます。 まず、チェックポイント変換ツールのドキュメントの[**ダウンロードとセットアップ**](https://docs.sambanova.ai/docs/ja/v1.2.0/sambastack/service-administration/model-deployment/checkpoint-conversion-tool.md#ダウンロードとセットアップ)セクションの手順に従ってください。変換ツールのコンテナをダウンロードし、お使いの SambaStack インスタンスとモデルメタデータを同期すればセットアップは完了です。 セットアップ後、チェックポイント変換ツールのドキュメントの[**チェックポイントの変換と検証**](https://docs.sambanova.ai/docs/ja/v1.2.0/sambastack/service-administration/model-deployment/checkpoint-conversion-tool.md#チェックポイントの変換と検証)セクションに記載された手順で、カスタムチェックポイントを SambaNova 互換形式に変換します。 ### 2. GCS バケットの権限設定 > [!NOTE] > > **クラスターに NFS がマウントされている場合、このセクションはスキップできます。** SambaStack は、チェックポイントやその他の SambaStack アーティファクトの保存に Google Cloud Storage (GCS) を使用します。カスタムチェックポイントの場合、変換済みチェックポイントのアーティファクトは**ご自身の** GCS バケットに保存します。デプロイ時に SambaStack がこれらのアーティファクトを利用できるようにするには、SambaNova から提供されたサービスアカウントにバケットへの読み取りアクセス権が必要です。 > [!NOTE] > > これは一度だけ行うセットアップ手順です。権限を設定した後は、任意の数のカスタムチェックポイントをバケットにアップロードし、デプロイで直接使用できます。 ### サービスアカウントの確認 サービスアカウントの情報は JSON ファイルとして提供されます。`client_email` フィールドを確認してください。これが、バケットへの読み取りアクセス権を必要とする ID です。例: ```json theme={} { "type": "service_account", "project_id": "example-project-id", "private_key_id": "example-private-key-id", "private_key": "-----BEGIN PRIVATE KEY-----\n\n-----END PRIVATE KEY-----\n", "client_email": "ss-artifacts-reader@example-project-id.iam.gserviceaccount.com", "client_id": "12345678901234567890", "auth_uri": "https://accounts.google.com/o/oauth2/auth", "token_uri": "https://oauth2.googleapis.com/token", "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs", "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/ss-artifacts-reader%40example-project-id.iam.gserviceaccount.com", "universe_domain": "googleapis.com" } ``` ### Storage Object Viewer ロールの付与 SambaStack がカスタムチェックポイントにアクセスできるようにするには、サービスアカウントに対して、バケットの **Storage Object Viewer** ロールを付与します。これにより、書き込みや変更を許可せず、オブジェクトへの読み取り専用アクセスのみが可能になります。 **Google Cloud Console を使用する場合:** 1. **Google Cloud Console** を開きます。 2. **Storage → Buckets** に移動し、使用するバケットを選択します。 3. **Permissions** タブに移動します。 4. **+ Add principal** をクリックします。 5. 「New principals」フィールドに、サービスアカウントの `client_email` を入力します。 6. 「Role」ドロップダウンで **Cloud Storage → Storage Object Viewer** を選択します。 7. **Save** をクリックします。 **gcloud CLI を使用する場合:** 以下のコマンドを実行する前に、次の値を確認してください。 * `` – GCS バケットの名前 * `` – サービスアカウントの JSON に記載された `client_email` の値 * `` – バケットを所有する Google Cloud プロジェクト バケットレベルで **Storage Object Viewer** ロールを付与するには: ```bash theme={} gcloud storage buckets add-iam-policy-binding gs:// \ --member="serviceAccount:" \ --role="roles/storage.objectViewer" \ --project= ``` ロールが正常に適用されたことを確認するには: ```bash theme={} gcloud storage buckets get-iam-policy gs:// \ --project= ``` 次のようなエントリが表示されるはずです。 ```yaml theme={} bindings: - members: - serviceAccount: role: roles/storage.objectViewer ``` 詳細については、Google の IAM ドキュメントをご参照ください。 * [Google Cloud: リソースへのアクセス権の付与、変更、取り消し](https://cloud.google.com/iam/docs/granting-changing-revoking-access) * [Google Cloud Storage の IAM ロール](https://cloud.google.com/storage/docs/access-control/iam-roles) ### 3. 変換済みチェックポイントのアップロード ### NFS クラスターに NFS がマウントされている場合は、変換済みチェックポイントが NFS に移動され、クラスターからアクセスできることを確認してください。 ### Google Cloud Storage Google Cloud Storage (GCS) を使用している場合は、チェックポイントの変換後、変換済みチェックポイントのファイルを含むディレクトリを GCS バケットにアップロードします。 > [!NOTE] > > このステップは、チェックポイントのサイズによっては時間がかかることがあります。 **Google Cloud Console を使用する場合:** 1. **Google Cloud Console** を開きます。 2. **Storage → Buckets** に移動し、カスタムチェックポイント用に設定したバケットを選択します。 3. **Upload folder** (または、構成によっては **Upload files**) をクリックします。 4. 変換済みチェックポイントのアーティファクトを含むディレクトリを選択します。 5. アップロードの完了を待ちます。ディレクトリ構造はそのまま維持される必要があります。 **gcloud CLI を使用する場合:** 変換済みチェックポイントのディレクトリ全体を再帰的にアップロードするには、次を実行します。 ```bash theme={} gcloud storage cp -r gs://// ``` ### 4. モデルマニフェストによるチェックポイントの登録 モデルマニフェスト (Model Manifest) を作成して、チェックポイントを登録します。モデルマニフェストには、API リクエストで使用する名前、対応言語、チェックポイントの説明など、チェックポイントに関する情報が保存されます。 ### モデルマニフェストの構造 以下はモデルマニフェストの例です。 ```yaml theme={} apiVersion: sambanova.ai/v1 kind: Model metadata: name: my-custom-llama3.1-8b # kubernetes resource name. Note that this must be a valid Kubernetes resource name (lowercase alphanumeric characters and hyphens only). spec: name: my-custom-llama3.1-8b # serving name used in the inference API owner: jane@doe.ai public: true aliases: - my-custom-llama3.1-8b # other aliases for the serving name used in the inference API - My-Custom-Llama3.1-8B metadata: name: "[optional]" # kubernetes name overview: "[optional description of the model]" architecture: "[optional]" category: "[optional]" status: active github_link: "[optional]" hf_link: "[optional]" languages: - "[optional]" license: "[optional]" vocabulary_size: "[optional]" price: input_tokens: "[optional]" output_tokens: "[optional]" tokenizer: endpointUrl: "" # optional remote tokenizer endpoint path: ./Meta-Llama-3.1-8B-Instruct_tokenizer ``` `name` フィールド (例: `My-Custom-Llama3.1-8B`) が、以降のステップおよび API リクエストで使用する名前になります。 ### tokenizer フィールドの設定 `tokenizer` フィールドには、カスタムチェックポイントに使用したベースモデルを設定できます。例えば、カスタムチェックポイントが `Meta-Llama-3.1-70B-Instruct` からファインチューニングされたものである場合、トークナイザーのパスを次のように設定します。 ```yaml theme={} tokenizer: endpointUrl: '' path: ./Meta-Llama-3.1-70B-Instruct_tokenizer ``` > [!NOTE] > > モデルマニフェストの tokenizer フィールドは、生成の前に入力のチェックを実行してシーケンス長の要件を計算するために**のみ**使用されます。 ### モデルマニフェストの適用 モデルマニフェストを作成したら、次のコマンドで適用します。 ```bash theme={} kubectl apply -f your_model_manifest_filename.yaml ``` ### 5. デプロイ用 Bundle でのチェックポイントの参照 カスタムチェックポイントのデプロイは、[SambaStack で標準モデルをデプロイする](https://docs.sambanova.ai/docs/ja/v1.2.0/sambastack/service-administration/model-deployment/deploying-model-bundles.md)場合と全体として同じワークフローに従います。最も簡単な方法は、カスタムチェックポイントと**同じモデルアーキテクチャ**を使用する既存の **Bundle Template** から始めて、関連するフィールドをカスタムアーティファクトを指すように変更することです。 > [!NOTE] > > Bundle Template やモデルデプロイの概念、ユースケースに応じたテンプレートの選び方がわからない場合は、[バンドルのデプロイ](https://docs.sambanova.ai/docs/ja/v1.2.0/sambastack/service-administration/model-deployment/deploying-model-bundles.md)のページをご参照ください。 ### Bundle 構造の理解 Bundle 定義の中で変更するオブジェクトは以下のとおりです。 1. **`checkpoints`** – チェックポイントのエイリアスと、その GCS ソースパスを定義します 2. **`models`** – モデル名をチェックポイントとテンプレートにマッピングします 以下は、ベースの `Meta-Llama-3.1-8B-Instruct` モデルおよび `Meta-Llama-3.1-70B-Instruct` モデル用の Bundle の例です。 ```yaml theme={} apiVersion: sambanova.ai/v1alpha1 kind: Bundle metadata: name: 8b-3dot1-full spec: checkpoints: LLAMA3_8B_3_1_CKPT: source: gs://path/to/ckpt/in/gcs # gs:// -> Google Cloud Storage toolSupport: true LLAMA3_70B_3_1_CKPT: source: nfs:///nfsdata/path/to/ckpt/in/nfs # nfs:// -> NFS path mounted in the serving pod models: Meta-Llama-3.1-8B-Instruct: checkpoint: LLAMA3_8B_3_1_CKPT template: Meta-Llama-3.1-8B-Instruct Meta-Llama-3.1-70B-Instruct: checkpoint: LLAMA3_70B_3_1_CKPT template: Meta-Llama-3.1-70B-Instruct secretNames: - sambanova-artifact-reader template: 8b-3dot1-full ``` ### checkpoints セクションの更新 `spec.checkpoints` では以下を行います。 * チェックポイントのキーを、カスタムチェックポイント用の名前 (エイリアス) に変更する * `source` フィールドを、変換済みチェックポイントのディレクトリの GCS パスに更新する * ファインチューニング済みチェックポイントがツール利用向けに構成されているかどうかに応じて、`toolSupport` を `true` または `false` に設定する 例: ```yaml theme={} checkpoints: CUSTOM_CHECKPOINT_ALIAS: source: nfs:///nfsdata/path/to/custom/ckpt/dir toolSupport: false ``` `spec.checkpoints.source` には、Google Cloud Storage のパス (`gs://`) または NFS のパス (`nfs://`) を指定できます。上の例では、`/nfsdata` はサービング Pod 内で NFS がマウントされているパスです。 ### models セクションの更新 `spec.models` では以下を行います。 * モデルのキーを、**モデルマニフェストで定義した名前**に変更する (これが推論 API の呼び出しで使用する名前になります) * `checkpoint` フィールドを、上で定義したエイリアスに設定する * `template` は元のモデルテンプレートのままにする 例: ```yaml theme={} models: My-Custom-Llama3.1-8B: checkpoint: CUSTOM_CHECKPOINT_ALIAS template: Meta-Llama-3.1-8B-Instruct ``` > [!NOTE] > > `template` フィールドはベースモデルを反映している必要があります。例えば、カスタムチェックポイントが `Meta-Llama-3.3-70B-Instruct` からファインチューニングされたものであれば、template フィールドは `Meta-Llama-3.3-70B-Instruct` にします。 ### Bundle の適用 Bundle 構成を更新したら、適用します。 ```bash theme={} kubectl apply -f your_bundle_filename.yaml ``` > [!TIP] > > デプロイの稼働後は、定義したモデル名 (例: `My-Custom-Llama3.1-8B`) を推論 API リクエストで使用してください。 ## デプロイの確認 Bundle を適用したら、カスタムチェックポイントのデプロイが成功したことを確認します。 1. **デプロイ状態の確認:** ```bash theme={} kubectl get bundles kubectl describe bundle ``` 2. **モデルが利用可能であることの確認:** ```bash theme={} kubectl get models ``` 3. カスタムモデル名を使用して、**サンプルの推論リクエストでテスト**します。 SambaNova SDK、OpenAI 互換ライブラリ、CURL を使用した推論リクエストの例については、[開発者向けクイックスタートガイド](https://docs.sambanova.ai/docs/ja/get-started/quickstart.md)をご参照ください。 ## トラブルシューティング ### よくある問題 | 問題 | 考えられる原因 | 解決方法 | | - | - | - | | 権限エラーでデプロイが失敗する | サービスアカウントに GCS バケットへの読み取りアクセス権がない | Storage Object Viewer ロールが付与されていることを確認してください (ステップ 2 を参照) | | API リクエストでモデルが見つからない | マニフェストと Bundle の間でモデル名が一致していない | `models` セクションのモデル名が、モデルマニフェストの `name` フィールドと一致していることを確認してください | | チェックポイントファイルが見つからない | Bundle 内の GCS パスが誤っている | `source` パスが、アップロードしたチェックポイントの場所と一致していることを確認してください | | 推論エラー | チェックポイントがテンプレートと互換でない | カスタムチェックポイントが、指定したテンプレートと同じアーキテクチャを使用していることを確認してください | ### GCS アクセスの確認 権限の問題が疑われる場合は、サービスアカウントがチェックポイントにアクセスできることを確認してください。 ```bash theme={} gcloud auth activate-service-account --key-file= gsutil ls gs://// ``` ## 次のステップ * 投機的デコーディングを使用してカスタムチェックポイントをデプロイするには、[投機的デコーディングによるデプロイ](https://docs.sambanova.ai/docs/ja/v1.2.0/sambastack/service-administration/performance/deploy-with-speculative-decoding.md)をご参照ください。 * 監視とモニタリングについては、[SambaStack の監視](https://docs.sambanova.ai/docs/ja/v1.2.0/sambastack/reference-architecture/observability/overview.md)をご参照ください。 * カスタムチェックポイントがベースモデルと異なるチャットテンプレートやツール呼び出しの出力形式を使用する場合は、クライアント側でのプロンプト整形と出力解析の方法について、開発者ガイドの[カスタムチャットテンプレートと出力解析](https://docs.sambanova.ai/docs/ja/build/chat-templates.md)をご参照ください。