vss-deploy-helm

VSS Helm デプロイ

sample-applications/video-search-and-summarization/chart にある VSS サンプルアプリの Helm チャートでは、このワークフローを使用します。このチャートの実際の依存関係は、ovms、minioserver、audioanalyzer、postgresql、rabbitmq、videoingestion、videosearch、vdmsvectordb、multimodaldataprep、multimodalembeddingms、vectorretriever、vllm（vllm-server のエイリアス）、summaryui、および searchui（vssui のエイリアス）です。

Compose または setup.sh の設定を Helm の値に対応付けるよう求められた場合は、references/helm-values-map.md を読んでください。

環境のセットアップ（最初に実行）

このスキルは、実際のソースファイルを使って Video Search & Summarization アプリを操作するため、VSS アプリが存在している必要があります。また、アプリのルートディレクトリからコマンドを実行してください。ほかの作業を始める前に、必ずこれを実行してください。VSS のソースがすでにワークスペースにあるかどうかにかかわらず動作します。

同梱のブートストラップを実行します。まず、現在のディレクトリから上位へたどり、さらにそれを囲む git リポジトリを調べて、既存の VSS チェックアウトを探します。見つかった場合は再利用し、再クローンは一切行いません。チェックアウトが見つからない場合にのみ、main から sample-applications/video-search-and-summarization だけを対象とした、浅い単一ブランチのスパースチェックアウトを実行します。解決されたアプリのルートは標準出力に出力されます。

# SKILL_DIR is THIS skill's own directory (shown to you when the skill loads);
# in-repo it is .github/skills/vss-deploy-helm. Works the same if the skill is installed standalone.
SKILL_DIR=".github/skills/vss-deploy-helm"
APP_ROOT="$(bash "$SKILL_DIR/scripts/vss-bootstrap.sh")"
cd "$APP_ROOT"

以下の各コマンドは、作業ディレクトリがこの APP_ROOT であることを前提としています。フォークやブランチから取得する場合、または特定のチェックアウトディレクトリを再利用する場合は、実行前に VSS_REPO_URL、VSS_REPO_BRANCH、または VSS_CLONE_DIR を上書きしてください。

前提条件

1. 接続可能な Kubernetes クラスター、kubectl、および Helm 3 があることを確認します。

   kubectl cluster-info
   kubectl get nodes
   helm version
   

2. PVC を使用する場合は、動的な PV プロビジョニングを確認します。

   kubectl get storageclass
   

3. GPU/NPU を使用する場合は、値を記述する前にリソースキーを確認します。

   kubectl get nodes -o json | jq -r '.items[] | "\(.metadata.name):\n" + (.status.allocatable | to_entries | map(select(.key | test("gpu|npu|vpu|accel";"i"))) | map("  \(.key): \(.value)") | join("\n"))'
   

   一般的な Intel のキーは gpu.intel.com/i915、gpu.intel.com/xe、および npu.intel.com/accel です。

1. 実際のチャート値から始める

チャートのディレクトリで作業します。

cd sample-applications/video-search-and-summarization/chart
helm dependency update
helm dependency list

ユーザー固有の値には user_values_override.yaml を作成または編集します。入力済みのシークレットはコミットしないでください。

ほとんどのモードで最低限必要な値は次のとおりです。

global:
  usePvc: true
  keepPvc: true
  huggingfaceToken: "hf_..."   # needed for gated/private Hugging Face models
  vlmName: "Qwen/Qwen3-VL-4B-Instruct"
  llmName: ""                  # optional OVMS split-model summarization model
  embeddingModelName: ""       # set per mode below
  modelDownload:
    image:
      repository: intel/model-download
      tag: "2026.2.0-ww30"
      pullPolicy: IfNotPresent
    ovmsReleaseTag: "v2026.1"
  proxy:
    http_proxy: ""
    https_proxy: ""
  env:
    POSTGRES_USER: "vsadmin"
    POSTGRES_PASSWORD: "change-me"
    MINIO_ROOT_USER: "minioadmin"
    MINIO_ROOT_PASSWORD: "change-me-8chars"
    RABBITMQ_DEFAULT_USER: "guest"
    RABBITMQ_DEFAULT_PASS: "change-me"

# Summary/OVMS model workspace:
ovms:
  claimSize: "20Gi"

# Search model caches (needed only when search is enabled):
multimodaldataprep:
  modelPvc:
    enabled: true
    size: "10Gi"
multimodalembeddingms:
  modelPvc:
    enabled: true
    size: "10Gi"

これらの値が重要な理由：

• global.usePvc を有効にすると、サービスごとの要求が有効になります。OVMS、video-ingestion、Multimodal DataPrep、および埋め込みサービスが、1 つの PVC を共有しなくなります。
• global.keepPvc: true にすると、アンインストール後にモデルを再ダウンロード／再変換せずに済みます。ただし、古い PVC に互換性のない以前の状態が残ることもあります。vLLM サブチャートの vllm-model-cache PVC は現在 global.keepPvc に従わず、リリースとともに削除されます。
• ovms.claimSize は、要約モードの OVMS モデルワークスペースのサイズを指定します。
• multimodaldataprep.modelPvc と multimodalembeddingms.modelPvc では、検索モデルキャッシュを個別に設定します。
• global.vlmName は要約モード／統合モードで必須であり、OVMS または vLLM で使用されます。
• global.embeddingModelName は、検索コンポーネントが有効な場合に必須です。
• global.modelDownload は、OVMS および video-ingestion の init コンテナーで使用するイメージを指定します。各 init コンテナーはローカル REST サービスを起動してダウンロードジョブを送信し、完了を待ってから終了します。その後、アプリケーションコンテナーが起動します。

2. 実際のオーバーライドファイルを使用してモードを選択する

次のチャートオーバーライドファイルをそのまま使用してください。

Docker／セットアップの概念	Helm コマンドのファイル	チャートで有効になる機能
source setup.sh --summary	-f summary_override.yaml -f user_values_override.yaml	rabbitmq、ovms、videoingestion、audioanalyzer、summaryui、pipelinemanager.env.SUMMARY_FEATURE=FEATURE_ON
--summary と ENABLE_VLLM=true	-f summary_override.yaml -f xeon_vllm_values.yaml -f user_values_override.yaml	summary モードに加え、vllm.enabled=true、ovms.enabled=false、pipelinemanager.env.USE_VLLM=CONFIG_ON
source setup.sh --search	-f search_override.yaml -f user_values_override.yaml	multimodalembeddingms、multimodaldataprep、vdmsvectordb、vectorretriever、videosearch、searchui、global.vdmsIndexName=video_frame_embeddings
VECTORDB_BACKEND=milvus と source setup.sh --search	-f search_override.yaml -f search_milvus_override.yaml -f user_values_override.yaml	検索バックエンドをMilvusに切り替えます（global.vectordbBackend=milvus）。milvusstandaloneを有効にし、vdmsvectordbを無効にして、multimodaldataprep、vectorretriever、videosearchは維持します
--summary-and-search／--all／--unified	-f unified_summary_search.yaml -f user_values_override.yaml	検索と要約を1つのsummaryui（名前はunified-ui）に統合します。global.vdmsIndexName=video_summary_embeddings
vLLMを使用する統合モード	-f unified_summary_search.yaml -f xeon_vllm_values.yaml -f user_values_override.yaml	統合モードに加え、vLLMバックエンドを使用します
UIを分けるデュアルモード	-f summary_override.yaml -f search_override.yaml -f user_values_override.yaml	summaryuiとsearchuiの両方を使用します。nginxが/summary/と/search/をルーティングします

埋め込みモデルのルール：

• 検索専用モードとデュアルUIモードでは、マルチモーダル埋め込みモデルを使用します。例：global.embeddingModelName: "CLIP/clip-vit-b-32"。
• 要約と検索の統合モードでは、テキスト埋め込みモデルを使用します。例：global.embeddingModelName: "QwenText/qwen3-embedding-0.6b"。

3. インストール

名前空間を一度作成します：

export NAMESPACE=vss-deployment
kubectl create namespace "$NAMESPACE"

OVMS CPUを使用した要約：

helm install vss . \
  -f summary_override.yaml \
  -f user_values_override.yaml \
  -n "$NAMESPACE"

Xeon CPU上のvLLMを使用した要約：

helm install vss . \
  -f summary_override.yaml \
  -f xeon_vllm_values.yaml \
  -f user_values_override.yaml \
  -n "$NAMESPACE"

検索のみ：

helm install vss . \
  -f search_override.yaml \
  -f user_values_override.yaml \
  -n "$NAMESPACE"

要約と検索の統合：

helm install vss . \
  -f unified_summary_search.yaml \
  -f user_values_override.yaml \
  -n "$NAMESPACE"

UIを分けるデュアルモード：

helm install vss . \
  -f summary_override.yaml \
  -f search_override.yaml \
  -f user_values_override.yaml \
  -n "$NAMESPACE"

モードを切り替える前に、まずリリースをアンインストールしてください。有効なサブチャートとUIルーティングが変更されるためです：

helm uninstall vss -n "$NAMESPACE"

4. GPU／NPUとvLLMの値

OVMS GPU VLMの例：

global:
  vlmName: "OpenVINO/Phi-3.5-vision-instruct-int8-ov"
  devices:
    ovms:
      vlm:
        device: GPU
        key: "gpu.intel.com/i915"
      llm:
        device: CPU
        key: ""

OVMSの分割モデル（例：GPU VLMとNPU LLM）：

global:
  vlmName: "OpenVINO/Phi-3.5-vision-instruct-int8-ov"
  llmName: "OpenVINO/Qwen3-8B-int4-cw-ov"
  devices:
    ovms:
      vlm:
        device: GPU
        key: "gpu.intel.com/i915"
      llm:
        device: NPU
        key: "npu.intel.com/accel"
ovms:
  env:
    VLM_WEIGHT_FORMAT: ""   # auto: CPU int8, GPU/NPU int4
    LLM_WEIGHT_FORMAT: ""

埋め込み／データ準備にGPUを使用する検索：

global:
  devices:
    multimodalEmbedding:
      device: GPU
      key: "gpu.intel.com/i915"
    multimodalDataprep:
      embedding:
        device: GPU
        key: "gpu.intel.com/i915"
      detection:
        device: CPU
        key: ""

プロセス内のDataPrep埋め込みにはglobal.devices.multimodalDataprep.embeddingを、クエリ側の埋め込みサービスにはglobal.devices.multimodalEmbeddingを、DataPrepの物体検出にはglobal.devices.multimodalDataprep.detectionを使用します。これらの設定はそれぞれ独立しています。GPU／NPUの各設定には、それぞれ固有のリソースkeyが必要です。

実際のvllmサブチャートで使用されるvLLMのチューニングキー：

vllm:
  enabled: true
  pvc:
    size: 80Gi
  env:
    vllmCpuKvCacheSpace: "48"
    vllmRpcTimeout: "100000"
    vllmAllowLongMaxModelLen: "1"
    vllmEngineIterationTimeoutS: "120"
    vllmCpuNumReservedCpu: "0"
    vllmLoggingLevel: "INFO"
  model:
    dtype: bfloat16
    maxModelLen: 32000
    maxNumBatchedTokens: 2048
    maxNumSeqs: 256
    tensorParallelSize: 1
  resources:
    requests:
      cpu: "16"
      memory: 128Gi
    limits:
      cpu: "16"
      memory: 128Gi

これらすべてを手動で設定するのではなく、xeon_vllm_values.yamlを使用することをおすすめします。このファイルでは、pipelinemanager.env.USE_VLLM=CONFIG_ONと依存サービスのリソース要求も設定されます。

5. 安全にアップグレードする

値を編集した後も、インストール時と同じオーバーライドファイルの組み合わせを使用してください：

helm upgrade vss . \
  -f summary_override.yaml \
  -f user_values_override.yaml \
  -n "$NAMESPACE"

vLLMを使用する要約の場合：

helm upgrade vss . \
  -f summary_override.yaml \
  -f xeon_vllm_values.yaml \
  -f user_values_override.yaml \
  -n "$NAMESPACE"

サブチャートのコードまたは依存関係を変更する場合：

helm dependency update

6. 確認する

ポッドを監視します。モデルのダウンロード／変換が行われるため、初回起動には20～50分かかる場合があります：

kubectl get pods -n "$NAMESPACE" -w
kubectl get svc -n "$NAMESPACE"

NodePortのURLを取得します。リリース名がvssの場合、nginxサービス名はvss-nginxです：

VSS_HOST=$(kubectl get pods -l app=vss-nginx -n "$NAMESPACE" -o jsonpath='{.items[0].status.hostIP}')
VSS_PORT=$(kubectl get service vss-nginx -n "$NAMESPACE" -o jsonpath='{.spec.ports[0].nodePort}')
echo "http://${VSS_HOST}:${VSS_PORT}"

UIのパス：

• 要約／検索／統合の単一UIモード：/
• デュアルUIモード：/summary/と/search/。ルートURLは/summary/にリダイレクトします

起動が遅い場合や失敗した場合は、ログを確認します：

kubectl logs -n "$NAMESPACE" deploy/vss-pipelinemanager
kubectl logs -n "$NAMESPACE" deploy/vss-nginx
kubectl get events -n "$NAMESPACE" --sort-by=.lastTimestamp

OVMSまたは動画取り込みがInitのまま停止している場合は、ポッドのモデルダウンロード用initコンテナを確認します：

kubectl describe pod -n "$NAMESPACE" <pod-name>
kubectl logs -n "$NAMESPACE" <ovms-pod> -c download-vlm
kubectl logs -n "$NAMESPACE" <ovms-pod> -c download-llm   # split-model mode only
kubectl logs -n "$NAMESPACE" <video-ingestion-pod> -c od-model-downloader

ovms.enabled=trueの場合のOVMSメトリクス：

kubectl port-forward svc/vss-nginx 8081:80 -n "$NAMESPACE"
curl http://localhost:8081/ovms/metrics

7. よくある修正方法

• Helm で認証情報が不足しているというエラーが発生する場合：global.env.POSTGRES_USER、global.env.POSTGRES_PASSWORD、global.env.MINIO_ROOT_USER、global.env.MINIO_ROOT_PASSWORD、global.env.RABBITMQ_DEFAULT_USER、global.env.RABBITMQ_DEFAULT_PASS を設定してください。
• Helm で GPU キーのエラーが発生する場合：CPU 以外のすべてのデバイスについて global.devices.*.key を設定してください。
• モデルのダウンロードジョブ／初期化コンテナが失敗する場合：メインコンテナのデバッグを始める前に、該当するモデルダウンロードの ログを確認し、global.modelDownload.image、プロキシ／トークンの値、モデル ID、デバイスの サポート状況、利用可能なモデルストレージを確認してください。
• Helm でデバイスキーが不足しているというエラーが発生する場合：GPU または NPU に設定されている global.devices.* エントリに対応する key を設定してください。
• 検索結果が不適切、または結果が返されない場合：global.embeddingModelName がモードと一致していること、および global.vdmsIndexName が適切なオーバーライドファイルに由来することを確認してください。
• global.keepPvc: true の状態で再インストールしても問題が解決しない場合：古い PVC の内容に互換性がない可能性があります。該当するモードを特定し、キャッシュされたモデル／データが失われることをユーザーが了承した後で、そのモードの PVC のみを削除してください。：

  # Summary with OVMS:
  kubectl delete pvc vss-ovms-pvc -n "$NAMESPACE"
  
  # Search model caches:
  kubectl delete pvc vss-multimodaldataprep-models-pvc \
    vss-multimodalembeddingms-models-pvc -n "$NAMESPACE"
  

• より大きなストレージが必要な場合：変換済み VLM／LLM モデルには ovms.claimSize、 OD モデルには videoingestion.claimSize、 検索モデルのキャッシュには multimodaldataprep.modelPvc.size／multimodalembeddingms.modelPvc.size、 または minioserver.claimSize、postgresql.claimSize、vdmsvectordb.claimSize、vllm.pvc.size などの 該当するデータ設定を指定してください。