> ## 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 管理者向けに、ユーザー権限の管理、管理者アクセスの設定、サービスティアおよび QoS (サービス品質) レベルの設定方法を説明します。どのユーザーがどのモデルにアクセスできるか、どの程度利用できるか、そしてリクエストにどの優先度を割り当てるかを、管理者がどのように制御するかを解説します。 ## 管理者の追加 ユーザーのメールアドレスを SambaStack の設定に追加することで、そのユーザーに管理者権限を付与できます。ユーザーを管理者として追加するには、以下の手順を実行します。 ### ステップ 1: 管理者メールアドレスの追加 `sambastack.yaml` ファイルの `auth-and-billing` セクションに、対象ユーザーのメールアドレスを追加します。例: ```yaml theme={} auth-and-billing: admins: - abc@example.com ``` セキュリティを維持するため、認可された管理者のメールアドレスのみを追加してください。`gateway` と同じ YAML レベル (sambastack.yaml のルートレベルキー) に配置する必要があります。 **v1.x からアップグレードする場合:** 管理者メールアドレスは、以前はルートレベルの `db-admin:` ブロックに記載していましたが、このブロックは v2.0.2 で削除されました。残された `db-admin:` ブロックはエラーにならずに無視されるため、アップグレードは成功したように見えても、そこに記載された全ユーザーが Admin UI へのアクセスを失います。リストを `auth-and-billing.admins` に移動し、古いブロックは削除してください。 完全な例については、[SambaStack.yaml リファレンス](/docs/ja/v2.2.3/sambastack/resources/sambastack-yaml) をご覧ください。 ### ステップ 2: 設定の適用 .yaml ファイルを更新したら、以下のとおり設定を適用します。 #### オンプレミス ```bash theme={} helm upgrade \ --install \ --namespace sambastack \ --version \ sambastack \ -f sambastack.yaml \ oci:///sambastack/sambastack ``` #### エアギャップ OCI レジストリパスの代わりに、ローカルにある Helm チャートのコピーを使用します。 ```shellscript theme={} helm upgrade sambastack \ -f sambastack.yaml \ --namespace sambastack \ sambastack-.tgz ``` `sambastack-.tgz` は、アップグレードに使用する Helm チャートのローカルコピーです。さらにサポートが必要な場合は、SambaNova のサポート窓口までお問い合わせください。 バージョン番号は、チャートの新しいリリースごとに変わります。SambaNova の担当者から提供されたバージョン番号を使用してください。 ### ステップ 1: 管理者メールアドレスの追加 `sambastack.yaml` ファイルの `auth-and-billing` セクションに、対象ユーザーのメールアドレスを追加します。例: ```yaml theme={} data: sambastack.yaml: | auth-and-billing: admins: - abc@example.com ``` セキュリティを維持するため、認可された管理者のメールアドレスのみを追加してください。 **v1.x からアップグレードする場合:** 管理者メールアドレスは、以前は `db-admin:` ブロックに記載していましたが、このブロックは v2.0.2 で削除されました。残された `db-admin:` ブロックはエラーにならずに無視されるため、アップグレードは成功したように見えても、そこに記載された全ユーザーが Admin UI へのアクセスを失います。リストを `auth-and-billing.admins` に移動し、古いブロックは削除してください。 完全な例については、[SambaStack.yaml リファレンス](/docs/ja/v2.2.3/sambastack/resources/sambastack-yaml) をご覧ください。 ### ステップ 2: 設定の適用 .yaml ファイルを更新したら、以下のコマンドで設定を適用します。 ```bash theme={} kubectl apply -f sambastack.yaml ``` ### ステップ 3: 管理パネルへのアクセスの確認 ブラウザ (Chrome を推奨) を開き、管理者用 URL にアクセスします。 ```text theme={} /admin ``` または、左側のパネルで「Administration」タブを選択します。 Admin ページ *** ## サービスティア サービスティアは、ユーザーがアクセスできるモデル、使用制限、権限を定義します。 ### 主要な概念 サービスティアは、ユーザーアクセス、使用制限、権限をきめ細かく調整するための強力な制御手段を提供します。 * **アクセス制御**: 各ユーザーまたはグループが使用できるモデルを決定します。 * **使用制限の設定**: 一定期間内にユーザーが実行できるリクエスト数やトークン数を定義します。 サービスティアは、アクセス制御と運用上の制限を定義するモデルグループオブジェクトのリストとして構成されます。各モデルグループのブロックでは、キュー深度やユーザーごとのレート制限などのパラメータを設定します。 `inherits` 属性を使用すると、ティアが別のベースティアの構成を拡張できます。継承時には `overrides` セクションで指定したフィールドのみが変更されるため、的確で保守しやすいカスタマイズが可能です。 ### 設定フィールド 以下の表は、サービスティアを定義する際に使用される主要フィールドと、それぞれの説明・値の例を示しています。 | フィールド | 説明 | 例 | | :- | :- | :- | | `qos` | このティアからのリクエストに割り当てられる QoS (サービス品質) レベル。通常はサービスティア名と一致します。 | `enterprise-group-1`, `customer-demo` | | `models` | ティア内のユーザーがアクセスできるモデルのリスト。ユーザーがモデルにアクセスするには、そのモデルが少なくとも 1 つのティアに含まれている必要があります。 | `[Llama-3.3-Swallow-70B-Instruct-v0.4]` | | `queueDepth` | ビジー応答を返す前にキューに入れられるクエリの最大数。 | `100` | | `maxNewTokens` | このティアのリクエストが `max_tokens` を省略した場合に使用される出力トークン数。最小値 `1`、デフォルトでは未設定。 | `8192` | | `maxNewTokensHard` | クライアントが `max_tokens` を送信したかどうかにかかわらず、このティアのどの生成も超えられない出力トークン数。最小値 `1`、デフォルトでは未設定。 | `32768` | | `contextGroups` | ティア内のコンテキスト長単位の設定。各エントリで `contextLengths` と `queueDepth` は必須です。`maxNewTokens` と `maxNewTokensHard` は任意で、ティアの値をオーバーライドします。 | `[{ contextLengths: ["32k"], queueDepth: 25, maxNewTokens: 1024 }]` | | `allowedRequests` | 期間 (秒) あたりに許可されるリクエスト数を定義します。allowedTokens と組み合わせて使用できます。 | `{ allowedRequests: 10, periodSeconds: 60 }` | | `allowedTokens` | 期間 (秒) あたりに許可されるトークン数を定義します。allowedRequests と組み合わせて使用できます。 | `{ allowedTokens: 300000, periodSeconds: 60 }` | | `periodSeconds` | レート制限の対象となる期間を定義します。`allowedRequests` や `allowedTokens` と組み合わせて使用します。 | `{ allowedRequests: 10, periodSeconds: 60 }`, `{ allowedTokens: 300000, periodSeconds: 60 }`, `{ allowedRequests: 20, allowedTokens: 200000, periodSeconds: 86400 }` | | `inherits` | ティアがベースティアから設定を継承し、特定のフィールドを上書きできるようにします。 | `inherits: previously defined tier name`, `overrides: mentions which properties to override` | 具体的なフォーマットについては、[SambaStack.yaml リファレンス](/docs/ja/v2.2.3/sambastack/resources/sambastack-yaml) をご覧ください。 ### 出力トークンの上限 `maxNewTokens` と `maxNewTokensHard` は、ティア上の 1 回の生成が生成できる出力トークン数を制限します。これらの設定がない場合、`max_tokens` を省略したリクエストは、自然な停止に達するか、モデルのコンテキストウィンドウに達するまで生成を続けます。異常な生成 (たとえば同じトークンを繰り返すもの) は、この後者に行き着きます。 2 つのフィールドの役割は異なります。 * `maxNewTokens` は、リクエストが `max_tokens` を省略した場合に `max_tokens` を補完します。自身の `max_tokens` を送信したリクエストには影響しません。 * `maxNewTokensHard` は、クライアントが `max_tokens` を送信したかどうかにかかわらず、ティア上のすべての生成に上限を課します。上限を超えそうな生成はそこで停止し、クライアント指定の上限と同じ finish reason をレポートします。 上限はデフォルト値の解決後に適用されるため、ティア自身の `maxNewTokensHard` より大きい `maxNewTokens` を設定しても、その値を超えることはできません。 | `maxNewTokens` | `maxNewTokensHard` | リクエストが `max_tokens` を省略した場合の結果 | | :- | :- | :- | | `8192` | `32768` | 出力トークン 8,192 で停止 | | `8192` | 未設定 | 出力トークン 8,192 で停止 | | 未設定 | `32768` | 出力トークン 32,768 で停止——上限がデフォルト値を兼ねる | | 未設定 | 未設定 | 制限なし: 自然な停止、またはモデルのコンテキストウィンドウまで | いずれのフィールドも、[Model](/docs/ja/v2.2.3/sambastack/service-administration/model-deployment/custom-resources/model) リソース、サービスティア、ティア内の `contextGroups` エントリの 3 つのレベルで設定できます。各フィールドは、それを設定している最も狭いレベル (コンテキストグループ、次にティア、次にモデルの順) から独立して解決されるため、ティアに広めの上限を持たせつつ、特定のコンテキストグループだけ引き締めることができます。 レベルは影響範囲に合わせて選択してください。 * **モデル**——そのモデルへのすべてのリクエストに、ティアを問わず、変更がクラスターに反映され次第適用されます。 * **サービスティア**——そのティアの、リストされたモデルへのリクエストに適用されます。制限付きティアへアカウントを移すのが、単一アカウントを封じ込める最速の方法です。 * **コンテキストグループ**——コンテキスト長がそのグループに該当するリクエストのみに適用されます。 いずれのフィールドも、トークナイザーを経由してルーティングされるモデルにのみ適用されます。音声専用モデルと Vision 専用モデルはこれらを無視し、それらのモデルでの生成は制限のないままです。 ### システム管理ティア 一部のティアは、**事前構成されたシステム管理ティア**です。これらのティアを削除または無効化しないでください。設定を誤ると、重要なワークフローが中断される恐れがあります。 | ティア | 用途 | HTTP レスポンス | | :- | :- | :- | | `free` / `web` | デフォルトの基本アクセスティア | 標準 | | `deprecated` | 恒久的に削除されたモデル | 410 (Gone) | | `maintenance` | 一時的に利用できないモデル | 503 | | `restricted` | アクセスが制限されたモデル | 403 | ティアを `sambastack.yaml` から削除すると、そのティアは SambaNova のデフォルト設定に戻ります。 ### 設定例 `gateway` と同じ YAML レベル (ルートレベルキー) に、`serviceTiers` セクションを追加します。 ```yaml theme={} serviceTiers: : # Custom service tier name - models: - Llama-4-Maverick-17B-128E-Instruct queueDepth: 25 # Queries to queue before returning busy qos: "free" # Usually matches service tier name rates: - allowedRequests: 0 periodSeconds: 30 : # Tier that inherits from another inherits: overrides: - models: - Llama-4-Maverick-17B-128E-Instruct queueDepth: 25 qos: "free" rates: - allowedRequests: 2 periodSeconds: 30 ``` 完全な例については、[SambaStack.yaml リファレンス](/docs/ja/v2.2.3/sambastack/resources/sambastack-yaml) をご覧ください。 変更を適用します。 #### オンプレミス ```bash theme={} helm upgrade \ --install \ --namespace sambastack \ --version \ sambastack \ -f sambastack.yaml \ oci:///sambastack/sambastack ``` #### エアギャップ OCI レジストリパスの代わりに、ローカルにある Helm チャートのコピーを使用します。 ```shellscript theme={} helm upgrade sambastack \ -f sambastack.yaml \ --namespace sambastack \ sambastack-.tgz ``` `sambastack-.tgz` は、アップグレードに使用する Helm チャートのローカルコピーです。さらにサポートが必要な場合は、SambaNova のサポート窓口までお問い合わせください。 バージョン番号は、チャートの新しいリリースごとに変わります。SambaNova の担当者から提供されたバージョン番号を使用してください。 sambastack.yaml の `data` の下に、`serviceTiers` セクションを追加します。 ```yaml theme={} data: sambastack.yaml: | serviceTiers: : # Custom service tier name - models: - Llama-4-Maverick-17B-128E-Instruct queueDepth: 25 # Queries to queue before returning busy qos: "free" # Usually matches service tier name rates: - allowedRequests: 0 periodSeconds: 30 : # Tier that inherits from another inherits: overrides: - models: - Llama-4-Maverick-17B-128E-Instruct queueDepth: 25 qos: "free" rates: - allowedRequests: 2 periodSeconds: 30 ``` 完全な例については、[SambaStack.yaml リファレンス](/docs/ja/v2.2.3/sambastack/resources/sambastack-yaml) をご覧ください。 変更を適用します。 ```bash theme={} kubectl apply -f sambastack.yaml ``` **\/\** という名前のティア (以下のスクリーンショットの例では「Premium2」) は、Admin ページ上で Usage Plan として表示され、ユーザーに割り当てることができます。 ユーザーサービスティアの Admin ページ ### 継承の使用 ベースティアを定義し、継承を利用して派生ティアを作成することで、再利用性と一貫性を確保できます。 **ベースティアの例:** ```yaml theme={} serviceTiers: free: - models: - Llama-3.1-Swallow-8B-Instruct-v0.3 - Meta-Llama-3.1-8B-Instruct queueDepth: 25 qos: "free" rates: - allowedRequests: 20 periodSeconds: 60 ``` **派生ティアの例:** ```yaml theme={} premium2: inherits: free overrides: - models: - Meta-Llama-3.1-70B-Instruct batchSize: 2 queueDepth: 50 qos: "premium2" rates: - allowedRequests: 100 periodSeconds: 60 ``` 設定を更新したら、変更を適用します。 #### オンプレミス ```bash theme={} helm upgrade \ --install \ --namespace sambastack \ --version \ sambastack \ -f sambastack.yaml \ oci:///sambastack/sambastack ``` #### エアギャップ OCI レジストリパスの代わりに、ローカルにある Helm チャートのコピーを使用します。 ```shellscript theme={} helm upgrade sambastack \ -f sambastack.yaml \ --namespace sambastack \ sambastack-.tgz ``` `sambastack-.tgz` は、アップグレードに使用する Helm チャートのローカルコピーです。さらにサポートが必要な場合は、SambaNova のサポート窓口までお問い合わせください。 バージョン番号は、チャートの新しいリリースごとに変わります。SambaNova の担当者から提供されたバージョン番号を使用してください。 設定を更新したら、変更を適用します。 ```bash theme={} kubectl apply -f sambastack.yaml ``` ### ベストプラクティス サービスティアを作成・管理する際は、安定性・セキュリティ・柔軟性を確保するため、以下のベストプラクティスを考慮してください。 **1. システム管理ティアとデフォルトティアを維持する** 一部のティアは、**事前構成されたシステム管理ティアであり、削除や無効化を行うべきではありません**。これらのティアは基本的なアクセスを提供し、モデルのライフサイクル管理とアクセス制御を担っています。削除や誤設定を行うと、重要なワークフローが中断される恐れがあります。 対象は以下のとおりです。 * **free / web**: デフォルトの基本アクセスティア。 * **deprecated**: 恒久的に削除されたモデル (HTTP 410)。 * **maintenance**: 一時的に利用できないモデル (HTTP 503)。 * **restricted**: アクセスが制限されたモデル (HTTP 403)。 これらのティアはシステムによって管理されるため、カスタマイズの対象とせず、サービスティアの設計時に考慮してください。 **2. 変更は慎重に行う** デフォルトティアのレート制限やモデルリストは調整できますが、変更はユーザーのニーズに沿ったものにしてください。ティアを上書きすると、その構成全体が置き換わります。 **3. カスタムティアで柔軟性を確保する** ベースティア (`free` や `web` など) を継承してカスタムティアを作成すると、基盤となる構造を維持しながらアクセスを柔軟に調整できます。 ### 完全な例 `sambastack.yaml` におけるシステム管理ティア、必須ティア、カスタムティアの例です。`gateway` と同じ YAML レベル (sambastack.yaml のルートレベルキー) に配置する必要があります。 ```yaml theme={} serviceTiers: # SYSTEM-MANAGED TIERS deprecated: - models: - Old-Model-v1 queueDepth: 0 rates: - allowedRequests: 0 periodSeconds: 3600 restricted: - models: - Restricted-Model queueDepth: 1 rates: - allowedRequests: 0 periodSeconds: 60 # REQUIRED TIERS free: - models: - Meta-Llama-3.1-8B-Instruct queueDepth: 100 qos: "free" rates: - allowedRequests: 20 periodSeconds: 60 web: - models: - Meta-Llama-3.1-8B-Instruct queueDepth: 100 qos: "web" rates: - allowedRequests: 20 periodSeconds: 60 # CUSTOM TIERS developer: inherits: free overrides: - models: - Meta-Llama-3.1-8B-Instruct queueDepth: 100 qos: "developer" rates: - allowedRequests: 60 periodSeconds: 60 enterprise: inherits: developer overrides: - models: - Meta-Llama-3.3-70B-Instruct queueDepth: 100 qos: "enterprise" rates: - allowedRequests: 200 periodSeconds: 60 ``` sambastack.yaml におけるシステム管理ティア、必須ティア、カスタムティアの例: ```yaml theme={} apiVersion: v1 kind: ConfigMap metadata: name: sambastack labels: sambastack-installer: "true" data: sambastack.yaml: | version: serviceTiers: # SYSTEM-MANAGED TIERS deprecated: - models: - Old-Model-v1 queueDepth: 0 rates: - allowedRequests: 0 periodSeconds: 3600 restricted: - models: - Restricted-Model queueDepth: 1 rates: - allowedRequests: 0 periodSeconds: 60 # REQUIRED TIERS free: - models: - Meta-Llama-3.1-8B-Instruct queueDepth: 100 qos: "free" rates: - allowedRequests: 20 periodSeconds: 60 web: - models: - Meta-Llama-3.1-8B-Instruct queueDepth: 100 qos: "web" rates: - allowedRequests: 20 periodSeconds: 60 # CUSTOM TIERS developer: inherits: free overrides: - models: - Meta-Llama-3.1-8B-Instruct queueDepth: 100 qos: "developer" rates: - allowedRequests: 60 periodSeconds: 60 enterprise: inherits: developer overrides: - models: - Meta-Llama-3.3-70B-Instruct queueDepth: 100 qos: "enterprise" rates: - allowedRequests: 200 periodSeconds: 60 ``` version フィールドは、SambaNova の担当者から提供されたバージョンに合わせて更新してください。 *** ## レート制限 レート制限は、1 分あたりに受け付ける API または UI のリクエスト数を制御し、クラスターを過負荷や不正利用から保護します。 SambaStack オンプレミスでは、レート制限は次の 2 つのレイヤーで適用できます。 | レイヤー | 説明 | 設定場所 | ステータス | | - | - | - | - | | **Ingress レイヤー (NGINX)** | NGINX アノテーションを使用して、Kubernetes ingress コントローラーで制限を適用します | NGINX ingress コントローラーの設定 | 任意 (推奨) | | **アプリケーションレイヤー (サービスティア)** | Helm チャートのパラメータを使用して、ゲートウェイレベルで制限を適用します | `sambastack.yaml` (`serviceTiers` セクション) | 必須。[サービスティア](#サービスティア) を参照 | アプリケーションレイヤーのレート制限は**必須**であり、サービスティアを通じて設定します。詳細は [サービスティア](#サービスティア) をご覧ください。 ### 概要 * **Ingress レイヤーのレート制限**は任意ですが、NGINX ingress コントローラーを使用しているお客様には推奨されます。 * Helm チャートには、デフォルトのレート制限アノテーションは含まれていません。お客様側で手動で有効化できます。 * **アプリケーションレイヤーのレート制限**は引き続き必須であり、`sambastack.yaml` の `serviceTiers` ブロックで設定します。 * 独自の Kubernetes クラスターと ingress コントローラーを使用する場合は、同等のアノテーションを使用することも、ingress レベルの制限を完全に省略することもできます。 ### Ingress レイヤーのレート制限 (任意、推奨) クラスターで RKE2 組み込みの NGINX ingress コントローラーを使用している場合、クラスターレベルでグローバルなレート制限ゾーンを定義し、API および UI の ingress アノテーションから参照できます。 **ステップ 1: グローバルレート制限ゾーンの定義** 以下の `HelmChartConfig` を適用して、ingress コントローラーのグローバルレート制限ゾーンを設定します。 以下の内容を `rke2-ingress-nginx.yaml` として保存します。 ```yaml theme={} apiVersion: helm.cattle.io/v1 kind: HelmChartConfig metadata: name: rke2-ingress-nginx namespace: kube-system spec: valuesContent: |- controller: config: limit-req-status-code: "429" allow-snippet-annotations: "true" http-snippet: | limit_req_zone $binary_remote_addr zone=240_req_min_ip:50m rate=240r/m; limit_req_zone $http_authorization zone=240_req_min_header:50m rate=240r/m; ``` 適用します。 ```bash theme={} kubectl apply -f rke2-ingress-nginx.yaml ``` **ゾーン定義:** * `_req_min_ip` ゾーンは **UI** に使用されます (IP ベースの制限) * `_req_min_header` ゾーンは **API/ゲートウェイ** に使用されます (Authorization ヘッダーベースの制限) レート制限の値は、クラスターの規模に合わせて調整してください。大規模なデプロイメント (例: 10 ノードのクラスター) では、毎分 5000 や 8000 リクエストなど、より高い制限値を検討してください。 **ステップ 2: sambastack.yaml での ingress アノテーションの適用** ゾーンを定義したら、`sambastack.yaml` の `cloud-ui.ingress` および `gateway.ingress` セクションで参照します。 ```yaml theme={} cloud-ui: ingress: annotations: nginx.ingress.kubernetes.io/backend-protocol: HTTP nginx.ingress.kubernetes.io/force-ssl-redirect: 'true' nginx.ingress.kubernetes.io/proxy-body-size: 21m nginx.ingress.kubernetes.io/configuration-snippet: | proxy_set_header Authorization $http_authorization; limit_req zone=240_req_min_ip burst=240 nodelay; limit_req_status 429; gateway: ingress: annotations: nginx.ingress.kubernetes.io/backend-protocol: HTTP nginx.ingress.kubernetes.io/force-ssl-redirect: 'true' nginx.ingress.kubernetes.io/proxy-read-timeout: '600' nginx.ingress.kubernetes.io/proxy-body-size: 25m nginx.ingress.kubernetes.io/enable-cors: 'true' nginx.ingress.kubernetes.io/configuration-snippet: | proxy_set_header Authorization $http_authorization; limit_req zone=240_req_min_header burst=360 nodelay; limit_req_status 429; ``` 完全な例については、[SambaStack.yaml リファレンス](/docs/ja/v2.2.3/sambastack/resources/sambastack-yaml) をご覧ください。 **設定の詳細:** * これらのスニペットは、適用するレート制限ゾーンを NGINX に指示します * `burst` と `rate` の値は必要に応じて調整できます * ingress ベースのレート制限は、クラスター全体ではなく **ingress コントローラーの Pod ごと**に適用されます * 実効レートの合計 = 設定したレート × ingress Pod 数 **ステップ 3: 更新した設定の適用** #### オンプレミス ```bash theme={} helm upgrade sambastack \ -f sambastack.yaml \ --namespace sambastack \ oci:///sambastack/sambastack ``` #### エアギャップ OCI レジストリパスの代わりに、ローカルにある Helm チャートのコピーを使用します。 ```shellscript theme={} helm upgrade sambastack \ -f sambastack.yaml \ --namespace sambastack \ sambastack-.tgz ``` `sambastack-.tgz` は、アップグレードに使用する Helm チャートのローカルコピーです。さらにサポートが必要な場合は、SambaNova のサポート窓口までお問い合わせください。 SambaNova は、引き渡し時に完全なレジストリ URL とバージョン番号を提供します。アクセス用の認証情報については、SambaNova の担当者にお問い合わせください。 ### 主な推奨事項 * インフラレベルの保護 (DDoS や不正なバーストの防止など) には、**ingress レイヤーの制限**を使用してください * アプリケーションレベルのスロットリングやユーザー単位のレート制御には、**サービスティアの制限**を使用してください * ingress の設定は**任意**ですが、RKE2 組み込みの NGINX ingress コントローラーを使用する場合は、有効化することを SambaNova は推奨します * 他の ingress コントローラー (Istio、AWS ALB、NGINX Plus など) を使用しているお客様は、必要に応じて同等の設定を適用できます * Helm チャートのデフォルト値にはレート制限アノテーションは含まれません。デプロイ時にお客様側で上書きできます アプリケーションレイヤーのレート制限は、必ずサービスティアで設定してください。ingress レイヤーのレート制限だけでは、適切なリクエスト管理には不十分です。 *** ## サービス品質 (QoS) QoS (サービス品質) は、リソースが競合する際に、複数のデプロイメント間でリクエストをどのように処理するかを決定する優先度レベルを定義します。優先度の高いトラフィックが優先度の低いトラフィックよりも先に処理されることを保証し、リソース競合時のリソース割り当てを最適化します。 ### QoS の仕組み * 各サービスティアには `qos` ラベルが割り当てられます。 * デプロイメントは、その spec 内の `qosList` で優先順位を定義します。 * リクエストは優先度順に処理されます。リストの先頭にある QoS レベルが最初に処理されます。 **設定例:** サービスティアとデプロイメントグループは別々のチャートに属するため、この 2 つの設定は別々のファイルに記述します。 ```yaml theme={} # sambastack.yaml (main chart) serviceTiers: : - models: - qos: queueDepth: rates: - allowedRequests: periodSeconds: ``` ```yaml theme={} # models chart values (on-prem) / models.yaml section (hosted) modelDeploymentSpecs: - name: groups: - name: minReplicas: qosList: - "web" - "free" ``` `modelDeploymentSpecs[].name` は**バンドル**名です。`ModelDeployment` の名前とその `spec.bundle` の両方に使用されるため、`ModelBundle` の名前と一致している必要があります。モデル ID を列挙する `serviceTiers[].models[]` とは異なる点に注意してください。 完全な例については、[SambaStack.yaml リファレンス](/docs/ja/v2.2.3/sambastack/resources/sambastack-yaml) をご覧ください。 この例では、デプロイメントは `web` ティアのリクエストを最初に処理し、`web` のトラフィックがキューにない場合に `free` ティアのリクエストを処理します。 **`modelDeploymentSpecs` への変更の適用:** デプロイメント側の設定を編集した場合は、`sambastack` チャートではなく `sambastack-models` リリースを更新します。オンプレミスでは、モデルチャートの values ファイルを編集し、[クイックスタート - オンプレミス](/docs/ja/v2.2.3/sambastack/getting-started/on-prem) に示すとおり `helm upgrade --install sambastack-models` を再実行します。Hosted では、[クイックスタート - Hosted](/docs/ja/v2.2.3/sambastack/getting-started/hosted) に示すとおり、インストーラー ConfigMap の `models_values:` ブロックを編集して再適用します。`serviceTiers` への変更は、引き続き上記のとおり `sambastack.yaml` を通じて適用します。パラメータのリファレンスについては、[モデル構成](/docs/ja/v2.2.3/sambastack/resources/sambastack-yaml#モデル構成) をご覧ください。 ### QoS の目的 QoS はリクエストに優先順位を付け、上位ティアのトラフィックが下位ティアのトラフィックよりも先に処理されるようにすることで、予測可能で公平なリソース共有を実現します。 * 例: `qosList: ["free", "web"]` を指定したデプロイメントは、free ティアのリクエストを最初に処理し、free のトラフィックがキューにない場合にのみ web ティアのリクエストを処理します。 ### QoS とサービスティアの違い | 概念 | 目的 | 定義場所 | | :- | :- | :- | | **サービスティア** | 「誰が」「何に」「どれだけ」アクセスできるかを定義 (モデル、レート制限) | `sambastack.yaml` または Admin UI | | **QoS** | リクエストが「いつ」処理されるかを定義 (優先順位) | モデルチャートの values 内の `modelDeploymentSpecs` にある `qosList` | つまり、次のようになります。 * サービスティアは、誰が何にどれだけアクセスできるかを定義します。 * QoS は、優先度に基づいてリクエストがいつ処理されるかを定義します。 ### 注意事項 * `free` ティアは、すべての新規ユーザーに自動的に割り当てられます。 * デプロイメントは複数の QoS レベルをサポートでき、異なる種類のトラフィックを同時に処理できます。 ## リクエスト処理のワークフロー 以下は、ユーザーリクエストが処理されるステップごとの流れです。サービスティアと QoS の優先度がどのように連携して、トラフィックを効率的に管理・ルーティングするかを示しています。 1. ユーザーが自身の認証情報を使用して API リクエストを送信します。 2. SambaStack が、そのユーザーに割り当てられたサービスティア (Usage Plan) を特定します。 3. リクエストが、そのティアで許可されたモデル、バッチサイズ、レート制限、および関連する QoS に適合しているかを確認します。 4. デプロイメントが、`qosList` の優先順位に従って処理するリクエストを選択します。 5. リクエストがユーザーのレート制限を超えている場合、`429 Too Many Requests` レスポンスで拒否されます。 6. リクエストの優先度レベルの QoS キューが満杯の場合、システムはビジー応答を返します。 7. それ以外の場合、リクエストは QoS キューに登録され、処理を待ちます。 管理者は、Admin UI からサービスティアやクォータ (使用枠) を調整できます。ティア、レート制限、QoS 設定への変更はクラスター全体に適用されます。これらの変更は YAML 設定を編集・デプロイして行い、可能な限りバージョン管理下で行うことを推奨します。