vss-deploy-helm

VSS Helm 部署

使用此工作流部署 sample-applications/video-search-and-summarization/chart 中的 VSS 示例应用 Helm chart。该 chart 的实际依赖项为 ovms、minioserver、audioanalyzer、postgresql、rabbitmq、videoingestion、videosearch、vdmsvectordb、multimodaldataprep、multimodalembeddingms、vectorretriever、vllm（vllm-server 的别名）、summaryui 和 searchui（vssui 的别名）。

如果用户要求将 Compose 或 setup.sh 设置映射到 Helm values，请阅读 references/helm-values-map.md。

环境设置（先运行）

此技能通过 VSS 应用的实际源文件操作 Video Search & Summarization 应用，因此必须确保 VSS 应用已就绪，并从其应用根目录运行命令。请先完成此操作；无论 VSS 源代码是否已在工作区中，都可以使用此流程。

运行随附的引导脚本。它会先尝试查找现有的 VSS 检出版本——从当前目录向上遍历，并检查外层的 git 仓库——找到后直接复用，绝不会重新克隆。只有在找不到检出版本时，才会从 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。如需从 fork 或其他分支拉取，或复用指定的检出目录，请在运行前设置 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，在编写 values 前先查明资源键：

   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. 从实际 chart values 开始

在 chart 目录中操作：

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

创建或编辑 user_values_override.yaml，设置用户专属 values。请勿提交已填写的密钥。

大多数模式所需的最少配置：

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 和嵌入服务不再共用一个 PVC。
• global.keepPvc: true 可避免卸载后重新下载或转换模型，但遗留的 PVC 也可能保留不兼容的旧状态。vLLM 子 chart 的 vllm-model-cache PVC 目前不遵循 global.keepPvc，并会随 release 一并删除。
• ovms.claimSize 用于设置摘要模式下 OVMS 模型工作区的大小。
• multimodaldataprep.modelPvc 和 multimodalembeddingms.modelPvc 可分别配置搜索模型缓存。
• 摘要模式或统一模式需要设置 global.vlmName，该值供 OVMS 或 vLLM 使用。
• 启用搜索组件时需要设置 global.embeddingModelName。
• global.modelDownload 用于控制 OVMS 和 video-ingestion init 容器所使用的镜像。每个 init 容器都会启动本地 REST 服务、提交下载任务、等待任务完成，并在应用容器启动前退出。

2. 使用实际的覆盖文件选择模式

请严格使用以下 Helm 覆盖文件：

Docker/设置概念	Helm 命令文件	Chart 启用的内容
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	摘要模式，并启用 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	在名为 unified-ui 的单个 summaryui 中整合搜索和摘要；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"

切换模式前，请先卸载该 Release，因为启用的子 Chart 和 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 子 Chart 中的调优键：

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"

如果更改子 Chart 代码或依赖项：

helm dependency update

6. 验证

查看 Pod；首次启动可能需要 20–50 分钟，因为需要下载/转换模型：

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

获取 NodePort URL。Release 名称 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 模式：/summary/ 和 /search/；根路径会重定向到 /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 状态时，检查 Pod 的模型下载 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。