vss-deploy

VSS 部署

使用 setup.sh 部署、切换、检查和拆除 VSS。此技能仅适用于 sample-applications/video-search-and-summarization。所有回答都必须以仓库文件为依据，尤其是 setup.sh 和 docker/compose.*.yaml；不要臆造标志、服务、端口或变量。**请亲自运行命令并转述输出；**不要把部署命令交给用户（唯一例外是 --setenv，见下文）。

环境设置（首先运行）

此技能通过 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. Works the same if the skill is installed standalone.
SKILL_DIR=".github/skills/vss-deploy"
APP_ROOT="$(bash "$SKILL_DIR/scripts/vss-bootstrap.sh")"
cd "$APP_ROOT"

以下每条命令都假定工作目录为此 APP_ROOT。如需从 fork 或分支拉取代码，或复用指定的检出目录，请在运行前覆盖 VSS_REPO_URL、VSS_REPO_BRANCH 或 VSS_CLONE_DIR。

模式路由

用户说	模式标志	UI URL
“summary” / “summarize videos” / “summary only”	--summary	http://<host-ip>:12345/
“search” / “search my videos” / “search only”	--search	http://<host-ip>:12345/
“both” / “dual” / “side by side” / “two UIs”	--summary --search（别名 --dual）	…/summary/ 和 …/search/
“unified” / “one UI” / “search over summaries” / “all”	--summary-and-search（别名 --unified、--all）	http://<host-ip>:12345/

如果用户表达不明确，请询问要使用哪种模式；不要默认选择。

快速部署流程

1. 在应用根目录中操作：

   cd sample-applications/video-search-and-summarization
   

2. 提供配置和凭据。 setup.sh 从 shell 环境读取所有内容，并在缺少首个必需变量时中止。仓库现在提供了 .env.example，作为通用应用模板，但此技能将配置与生成的密钥分开保存，以免凭据进入已提交的文件：

   • 非敏感配置——模型、端口、调优参数——保存在已提交的 vss.config.env 中。
   • 凭据在运行时由 scripts/gen-secrets.sh 生成到被 git 忽略的 vss.secrets.env 中（使用强随机值，生成一次并重复使用，以确保数据卷保持有效）。

   生成一次密钥，然后在同一个 shell 中加载这两个文件：

   ./.github/skills/vss-deploy/scripts/gen-secrets.sh     # makes vss.secrets.env if absent
   source .github/skills/vss-deploy/vss.config.env
   source .github/skills/vss-deploy/vss.secrets.env
   

   所有模式都需要：MINIO_ROOT_USER、MINIO_ROOT_PASSWORD、POSTGRES_USER、POSTGRES_PASSWORD、RABBITMQ_USER、RABBITMQ_PASSWORD。各模式专用的模型变量（summary 使用 VLM_MODEL_NAME、ENABLED_WHISPER_MODELS、OD_MODEL_NAME；search/dual 使用 MULTIMODAL_EMBEDDING_MODEL；unified 使用 TEXT_EMBEDDING_MODEL）都已在 vss.config.env 中设置默认值——完整列表请参阅 references/env-vars.md。如需注入自己的凭据（vault/CI）而非使用随机值，请在运行 gen-secrets.sh 前导出这些凭据——脚本会重复使用已设置的凭据。

3. 不确定时先试运行——追加 config 以渲染解析后的 .env/compose，而不启动容器，然后在实际部署前检查：

   source setup.sh --summary config     # or --search / --summary --search / --summary-and-search
   

4. 部署——由你亲自运行。 必须以 source 方式执行 setup.sh（它会使用 return，并在构建 Compose 命令时导出环境变量），但不需要使用用户的交互式 shell：部署使用 docker compose up -d（后台运行），因此子 shell 退出后容器仍会继续运行。先停止任何之前运行的堆栈，以免过期或模式错误的部署发生冲突，然后部署——在一次 bash -c 调用中运行完整命令链：

   bash -c '
     source setup.sh --stop                                  # clear any running stack first
     ./.github/skills/vss-deploy/scripts/gen-secrets.sh       # secrets if absent
     source .github/skills/vss-deploy/vss.config.env
     source .github/skills/vss-deploy/vss.secrets.env
     source setup.sh --summary                                # the chosen mode
   '
   

   在后台运行此命令（run_in_background: true），或使用较长的超时时间。Compose 启动前，如果选定的 OD 工件或 OVMS VLM/拆分 LLM 工件缺失，setup.sh 会在 loopback 端口 8640 上启动一个临时的 vss-model-download 容器。它会提交 REST 作业，每个作业最多等待 MODEL_DOWNLOAD_JOB_TIMEOUT 秒（默认值为 5400 秒），将失败服务的日志写入 ov_models/model-download-*.log，移除临时容器，然后才运行 docker compose up -d。

   唯一例外： --setenv 仅用于将环境变量留在用户的交互式 shell 中，以供之后手动使用——子 shell 无法做到这一点，因此仅对此动词，请向用户提供带 ! 前缀的命令，让他们亲自运行。

5. 等待健康检查通过，然后打印 URL（请参阅 scripts/wait-health.sh）：

   ./.github/skills/vss-deploy/scripts/wait-health.sh "${HOST_IP:-localhost}" "${APP_HOST_PORT:-12345}"
   

模式别名和仅配置检查

setup.sh 会将 --summary --search 和 --search --summary 规范化为 --dual；将 --summary-and-search、--search-and-summary 和 --all 规范化为 --unified；将 config 规范化为 --dual config；将 config --summary 规范化为 --summary config；并将 --down 规范化为 --stop。使用 config 模式可验证解析后的 Compose 配置，而不启动容器：

source setup.sh --summary config
source setup.sh --search config
source setup.sh --summary --search config
source setup.sh --summary-and-search config

选择 OVMS、vLLM、CPU 或 GPU

默认摘要后端是 docker/compose.summary.yaml 中的 OVMS（ovms-service，配置文件 ovms）。

source setup.sh --summary                                                # OVMS CPU default
VLM_TARGET_DEVICE=GPU source setup.sh --summary                          # OVMS GPU for VLM
LLM_TARGET_DEVICE=GPU OVMS_LLM_MODEL_NAME=<llm> source setup.sh --summary # OVMS GPU for LLM
ENABLE_VLLM=true source setup.sh --summary                               # vLLM CPU backend
ENABLE_VLLM_GPU=true source setup.sh --summary                           # experimental vLLM XPU/GPU backend
ENABLE_EMBEDDING_GPU=true source setup.sh --search                       # GPU for search embeddings

对于 vLLM，setup.sh 会添加 docker/compose.vllm.yaml，在主机端口 8200 上启动 vllm-cpu-service（配置文件 vllm），并将 VLM_MODEL_NAME 用于生成标题和最终摘要。实验性选项 ENABLE_VLLM_GPU=true 则会添加 docker/compose.vllm.xpu.yaml，选择配置文件 vllm-xpu，并禁用 OVMS。对于 OVMS GPU，setup.sh 会添加 docker/compose.gpu_ovms.yaml，并将 ovms-service 切换为 openvino/model_server:2026.1-gpu。

该技能的全新 bash -c 部署流程可防止派生的 OVMS 存储名称在不同运行之间泄漏。如果在同一个交互式 shell 中手动从 OVMS 切换到 vLLM，请先运行 unset VLM_STORAGE_MODEL_NAME LLM_STORAGE_MODEL_NAME；否则，Compose 可能会复用 vLLM 无法提供服务的 OVMS 存储别名。

生命周期：停止或重置

请自行通过 bash -c 'source setup.sh …' 运行这些命令。--stop/--down/ --clean-data 与模式无关，无需设置环境变量。

source setup.sh --stop       # stop/remove containers across all VSS overlays/profiles
source setup.sh --down       # alias for --stop
source setup.sh --clean-data # also removes the VSS application data volumes
source setup.sh --help       # full help

--clean-data 会删除 docker_minio_data、docker_pg_data、docker_vdms-db、 docker_audio_analyzer_data、docker_data-prep 和 docker_collector_signals。 它不会删除由主机提供的 ov_models/ 模型缓存。

默认端口和 URL

setup.sh 会自动检测 HOST_IP；APP_HOST_PORT 默认为 12345。

界面	URL
UI（摘要 / 搜索 / 统一）	http://<HOST_IP>:<APP_HOST_PORT>/
UI（双模式）	…/summary/ 和 …/search/
Pipeline Manager API 和文档	…/manager/docs，健康检查 …/manager/health
Data Prep 文档（搜索模式）	http://<HOST_IP>:7890/docs
Embedding 服务文档（搜索模式）	http://<HOST_IP>:9777/docs

故障排查（“为什么 vss 无法启动”）

1. ERROR: <VAR> is not set → 缺少 shell 环境变量；重新载入 vss.config.env
   • vss.secrets.env（步骤 2）。
2. Invalid VECTORDB_BACKEND → 将 VECTORDB_BACKEND 设置为 vdms 或 milvus。
3. 健康状态始终未变为绿色 → 运行 docker compose ps 查看崩溃的容器，然后运行 docker compose logs <service>。占用资源较多的是模型服务（ovms、 vlm-ov/vllm、embedding）。
4. 已有错误或不完整的堆栈正在运行 → 执行 source setup.sh --stop，然后重新部署。
5. Compose 启动前设置失败 → 检查报告的 ov_models/model-download-*.log；如果回环端口 8640 已被占用，请将 MODEL_DOWNLOAD_HOST_PORT 设置为空闲端口，然后重新运行。

如果遇到超出上述基础问题的情况——模型服务崩溃、OVMS token/缓存/GPU 错误、主机模型缓存或模型下载权限失败、搜索无结果、 NPU/OpenGL 问题——请转交给 .github/skills/vss-troubleshoot/SKILL.md 中的 vss-troubleshoot 技能， 并参阅权威指南 docs/user-guide/troubleshooting.md。

参考资料

• 模式到 overlay/配置文件/服务/URL 的精确映射： references/modes-and-overlays.md。
• 必需和可选的环境变量： references/env-vars.md。