vss-deploy-profile

VSS 部署

可用脚本

脚本	用途	参数
scripts/normalize_resolved_yml.py	在部署前，从 resolved.yml 中剔除已被筛选掉的服务对应的可选 depends_on 条目。	resolved.yml 的路径
scripts/probe_remote_models.sh	探测兼容 OpenAI 的远程 LLM/VLM 端点，并验证所选模型 ID。	基础 URL，可选的预期模型 ID

配置档案路由

将用户的请求匹配到相应配置档案，然后加载该档案的参考文档，以了解容量规划、服务、环境配置方案和调试方法。

用户说	配置档案	参考文档
“部署 vss” / “部署 base”	base	references/base.md
“部署 alerts” / “警报验证” / “实时警报” / “为事件报告部署”	alerts	references/alerts.md
“部署 lvs” / “视频摘要”	lvs	references/lvs-profile.md
“部署 search” / “视频搜索”	search	references/search.md
“部署 warehouse” / “warehouse 蓝图” / “vss warehouse”	warehouse	references/warehouse.md
“调试 warehouse” / “warehouse 无法正常工作” / “warehouse FPS 低” / “warehouse BEV 不同步”	warehouse（调试）	references/warehouse-debug.md

边缘硬件路由（DGX Spark、AGX/IGX Thor）：请参阅 references/edge.md。DGX Spark 使用端口 30081 上独立运行的 Spark Nano 9B 本地 LLM；AGX/IGX Thor 使用 Edge 4B 独立运行的 vLLM 后备方案。

每个配置档案的参考文档都包含该档案的容量规划表。 不要根据此文件选择部署规格——打开配置档案的参考文档，并根据其中的（模式 × 平台）矩阵检查主机硬件所需的最低 GPU 数量。

说明

部署流程始终为：将 .env 复制到 generated.env，应用覆盖项，将 compose 试运行结果写入 resolved.yml，检查、规范化、部署，然后等待就绪。

# 1. cp dev-profile-<profile>/.env dev-profile-<profile>/generated.env  (clean copy)
# 2. Apply env overrides to generated.env  (source .env stays untouched)
# 3. docker compose --env-file generated.env config > resolved.yml      (dry-run)
# 4. Review resolved.yml
# 5. docker compose --env-file generated.env -f resolved.yml up -d

.env 是只读的、已纳入版本控制的默认配置；generated.env 是每次部署使用的工作副本。步骤 1c 会对此进行完整说明。

先决条件

1. 仓库路径——先自动检测 video-search-and-summarization/，再询问用户。后续所有命令都使用检测到的路径作为 $REPO。
2. 凭据检查——请参阅 references/credentials.md：本地/本地共享 NIM 拉取需要 NGC_CLI_API_KEY，远程 NIM 端点需要 NVIDIA_API_KEY，使用受限 HF 模型的边缘配置方案需要 HF_TOKEN。
3. 系统先决条件（GPU 驱动程序、Docker、NVIDIA Container Toolkit、内核 sysctl，以及——如果 ufw 处于活动状态——Docker 网桥→主机防火墙放行规则，以便网桥 NIM 从主机模式 VST 获取片段）——完整检查项请参阅 references/prerequisites.md。硬件/驱动程序的标准矩阵见 VSS 先决条件页面。

自动检测片段（先查找 git 根目录，再检查常见路径，并要求存在 deploy/docker/compose.yml、dev-profile.sh 和 skills/vss-deploy-profile） 位于 references/prerequisites.md。 导出解析出的 $REPO；如果检测失败，请向用户询问检出目录的路径。

部署前检查

每次部署前都要运行。完整的系统检查清单和修复步骤见 references/prerequisites.md。 对于 DGX Spark / IGX Thor / AGX Thor，还要运行 references/edge.md 中的缓存清理器检查。

先检测 sudo 模式。 多项部署前修复操作和边缘设备缓存清理器安装程序会调用 sudo。如果主机需要 sudo 密码，这些步骤在 sudo -n 下会静默地什么也不做， 导致部署处于准备不完整的状态。

if sudo -n true 2>/dev/null; then
  echo "passwordless sudo — pre-flight will auto-install missing pieces"
else
  echo "sudo requires password — pre-flight will NOT auto-install; hand commands to the user"
fi

如果 sudo 需要密码，技能不得自行运行需要特权的安装程序。将 references/prerequisites.md 中可直接复制粘贴的命令块提供给用户，并要求用户 “运行一次并确认”，随后等用户回复后再继续。

最低限度的冒烟测试（必须成功）：

nvidia-smi --query-gpu=index,name --format=csv,noheader
docker info 2>/dev/null | grep -qi runtimes \
  && docker run --rm --gpus all ubuntu:22.04 nvidia-smi >/dev/null 2>&1 \
  && echo "nvidia runtime OK"

如果冒烟测试失败，请勿继续；打开 references/prerequisites.md 查看修复流程。

模型选择

• 用户要求使用远程服务时，使用 $LLM_REMOTE_URL / $VLM_REMOTE_URL
• $NGC_CLI_API_KEY（本地 NIM）或 $NVIDIA_API_KEY（远程服务）

端点用途判定关卡。 不要根据偶然存在的环境变量推断要部署到远程服务 （LLM_ENDPOINT_URL、VLM_ENDPOINT_URL、LLM_BASE_URL、VLM_BASE_URL 可能是 遗留变量）。只有在以下情况下才使用远程 LLM/VLM：（1）用户要求使用远程服务或 提供了远程端点；（2）本地配置无法满足所选模型的需求，且用户同意；或（3）某个 边缘设备配置需要独立的本地服务，而 VSS 将其视为 remote（例如，DGX Spark Nano 9B 位于 localhost:30081）。如果设置了端点变量，但用户没有要求使用远程 服务，应在步骤 1 中向用户说明并询问，切勿仅仅因为变量存在就悄悄部署到远程服务。

如果此主机上没有任何组合能满足配置文件的需求，请停止并报告阻碍因素——不要 悄悄选择其他规格。

边缘设备共享模式因平台而异。 完整配置见 references/edge.md。

部署流程

务必遵循以下顺序。切勿跳过试运行。

步骤 0 — 拆除任何现有部署并清除数据卷

如果已有部署，请先将其拆除并清除过时的数据卷，然后再重新部署。

完整流程见 references/teardown.md。

步骤 0a — 凭据检查关卡（在修改任何环境变量之前运行）

在步骤 1c 将 .env 复制到 generated.env 之前，验证所选配置文件需要的每项凭据和 远程端点。这里的 401 错误只会造成 30 秒的失败；同一个 401 若发生在 NIM 冷启动期间， 则会导致 10–20 分钟的失败。按照 references/credentials.md 中的发现和探测流程操作，并对 计划写入 generated.env 的任何 LLM/VLM 端点运行 scripts/probe_remote_models.sh。根据所选模式判断结果：缺失或无效的必需凭据/端点 属于阻碍因素，可选凭据则不属于。

步骤 1 — 收集上下文

构建环境覆盖项之前，请确认：

值	确定方法
配置文件	将用户意图与上方的路由表匹配。默认值：base
仓库路径	使用先决条件中自动检测到的 $REPO 值。如果自动检测失败，请先向用户询问检出路径，再继续。
硬件	nvidia-smi --query-gpu=name,memory.total --format=csv,noheader
LLM/VLM 部署位置	明确选择本地 / local_shared / 远程。将可用 GPU 与所选配置文件的最低 GPU 数量表交叉核对。如果存在端点环境变量，但用户没有要求使用远程部署，请询问是使用还是忽略这些变量。
API 密钥	本地 NIM 使用 NGC_CLI_API_KEY，远程部署使用 NVIDIA_API_KEY
HOST_IP	集群内的拨号地址：ip route get 1.1.1.1 的 src（类似 dev-profile.sh；在局域网和云环境中均正确）。如果该接口是 VPN/隧道，请回退到局域网 IP，并提示用户 — 网络寻址。
EXTERNAL_IP	浏览器访问地址；默认为 ${HOST_IP}。浏览器访问路径不同时覆盖 — 云公共 IP、Brev 安全链接（步骤 1d）或隧道；如果不确定，询问用户从哪里浏览。网络寻址。
HAPROXY_PORT	浏览器访问的入口端口。默认值为 7777；请确保该端口未被占用。

运行 docker compose up 之前，请确认 EXTERNAL_IP、HAPROXY_PORT、VSS_PUBLIC_HOST 和 VSS_PUBLIC_PORT 均已填入浏览器可访问的值。否则，整个服务栈可能看似正常，但 UI/API/VST 链接会返回 404，或经由 Cloudflare Access 循环跳转。

步骤 1b — 准备数据目录

目录布局（资源路径、所有权、挂载点、特定配置文件的子目录）记录在 references/data-directory.md 中。首次在某台主机上部署或更改配置文件时，请先阅读该文件。

步骤 1c — 初始化 generated.env

这是该技能每次部署时使用的工作副本。始终从源 .env 创建全新副本，切勿修改源文件。

PROFILE=base
ENV_SRC=$REPO/deploy/docker/developer-profiles/dev-profile-$PROFILE/.env
ENV_GEN=$REPO/deploy/docker/developer-profiles/dev-profile-$PROFILE/generated.env

cp "$ENV_SRC" "$ENV_GEN"

之后的所有写入（Brev EXTERNAL_IP、步骤 2 中的 env_overrides 字典）都写入 $ENV_GEN。从此处开始，$ENV_SRC 只读。

步骤 1d — 仅限 Brev：先检测，再将 EXTERNAL_IP 设置为安全链接域名

先检测 Brev — 由 Brev 配置的实例会在 /etc/environment 中设置 BREV_ENV_ID；其他情况都不会：

grep -qE '^BREV_ENV_ID=' /etc/environment && echo "on Brev" || echo "not Brev"

• 不是 Brev → 跳过此步骤的其余部分，且不要读取 references/brev.md；保留基于 ${HOST_IP} 的常规 EXTERNAL_IP。
• 是 Brev → 将 references/brev.md § 设置流程中的 Brev 安全链接覆盖项应用到 generated.env（不是 .env）。这些设置会将 EXTERNAL_IP / VSS_PUBLIC_HOST 指向安全链接域名，并且将 VSS_PUBLIC_HTTP_PROTOCOL=https / VSS_PUBLIC_WS_PROTOCOL=wss / VSS_PUBLIC_PORT=443 — 仅设置 EXTERNAL_IP 会留下 http://…:7777 UI/API/WS 链接，浏览器会将其拦截为混合内容。

步骤 2 — 构建 env_overrides

根据用户请求和收集到的上下文生成 env_overrides 字典：明确选择远程/本地 LLM/VLM，设置凭据，指定端点，并设置特定平台的标志。不要让现有 shell 环境变量悄然决定部署位置；将选定的 LLM_MODE / VLM_MODE 及匹配的端点/模型字段写入 generated.env。完整映射（每个覆盖键、适用条件、默认值、特定配置文件的差异）见 references/env-overrides.md。每个配置文件的参考文档都提供了该配置文件常见场景的完整示例。

步骤 3 — 应用覆盖值 + 试运行

工作环境文件： <repo>/deploy/docker/developer-profiles/dev-profile-<profile>/generated.env（在步骤 1c 中创建）。

提醒（参见步骤 1c）： 将所有覆盖值（步骤 2 字典 + Brev EXTERNAL_IP）应用到 generated.env；--env-file 始终指向该文件，部署后的验证程序会读取它，以获取实际部署的值。

# (Step 1c already ran: cp $ENV_SRC $ENV_GEN)

# Apply the env_overrides dict from Step 2 to generated.env
# (read lines, update matching keys, append new keys, write)
# Example:
#   sed -i "s|^LLM_MODE=.*|LLM_MODE=remote|" "$ENV_GEN"
#   sed -i "s|^LLM_BASE_URL=.*|LLM_BASE_URL=http://localhost:30081|" "$ENV_GEN"

# Resolve compose
cd $REPO/deploy/docker
docker compose --env-file $ENV_GEN config > resolved.yml

解析后的 YAML 会保存到 <repo>/deploy/docker/resolved.yml。

步骤 3b — 验证 resolved.yml 中没有未展开的 ${...} 标记

resolved.yml 中未展开的 ${VAR} 标记表示 compose 未获取到这些环境变量值。诊断流程和常见原因见 references/troubleshooting.md。

步骤 3c — 验证是否可以访问所选的 NGC 工件

请在 resolved.yml 存在后、运行 docker compose up 之前执行此步骤。步骤 0a 中的 NGC 令牌探测只能证明密钥通过了身份验证，无法证明该密钥所属的组织或团队有权访问所选的镜像或模型仓库。

根据实际选定的部署，整理工件列表：

• resolved.yml：Compose 将拉取的所有 nvcr.io/... 下的 image:。
• $ENV_GEN：由 NGC 提供的模型／资源路径，例如 RTVI_VLM_MODEL_PATH=ngc:nim/nvidia/cosmos-reason2-8b:hf-1208。跳过 none、git:...、本地路径和远程端点 URL。
• 配置文件暂存步骤：配置文件参考文档中说明的任何 NGC 模型／资源下载，例如 alerts/search 感知模型暂存。

继续之前，使用规范化后的 NGC 密钥逐一探测所选工件：

• 容器镜像：在执行 docker login nvcr.io 后运行 docker manifest inspect <nvcr.io/...> — 对于受限的 nvcr.io 仓库，此处返回 401／403 即可明确表明没有访问权限（读取清单需要与拉取镜像层相同的组织／团队授权）；或者在工件可直接对应到 NGC 镜像路径时，运行相应的 ngc registry image info ...。
• NGC 模型／资源路径（例如运行时由 RT-VLM 下载的 Cosmos 检查点）：针对配置文件将要加载或下载的确切仓库／标签，运行相应的 ngc registry model info ... 或 ngc registry resource info ...；这些命令使用 NGC 的范围限定式身份验证。不要使用 docker manifest inspect 探测模型（由于模型不是 OCI 镜像，会返回“no such manifest”），也不要使用原始的 Authorization: Bearer <key> REST 调用（由于这不是 NGC 的身份验证流程，会返回 403）；这两种情况都是预期的误报，并不表示没有访问权限。如果无法使用 ngc CLI，请将上述容器镜像探测结果作为权限信号，因为 NGC 会同时授予组织／团队对镜像和模型的访问权限。
• 配置文件暂存的 TAO／感知模型：在暂存代码块下载文件前，针对每个仓库／标签运行相应的 ngc registry model info ...／resource info ...。

如果任何探测返回 401、403、permission、not being a member of the organization that owns the repo、组织／仓库缺失或类似的访问错误，请停止操作，并提示用户提供一个所属组织／团队有权访问这些工件的 NGC 密钥。不要启动 Compose 后才在 NIM 冷启动期间发现问题。

步骤 3d — 从 resolved.yml 中移除悬空的可选 depends_on

必须在步骤 3 之后、步骤 5 之前运行。 跳过此步骤会中止部署：

规范化 — 移除已从 resolved.yml 中筛除的服务对应的可选依赖

# From the repo root
uv run skills/vss-deploy-profile/scripts/normalize_resolved_yml.py "$REPO/deploy/docker/resolved.yml"

如果主机上没有 uv，请使用 curl -LsSf https://astral.sh/uv/install.sh | sh 安装一次（无需 root 权限）。 在执行 up -d 之前重新验证：

docker compose -f "$REPO/deploy/docker/resolved.yml" config --quiet && echo "resolved.yml OK"

如果规范化程序运行后验证仍然失败，请记录错误并进行检查 — 这是另一类问题（非可选依赖或其他架构违规），而不是悬空 depends_on 问题。

步骤 4 — 审核

向用户展示即将部署的内容摘要：

• 配置文件名称和硬件
• LLM/VLM 模型及模式（local/remote/local_shared）
• 即将启动的服务
• GPU 设备分配
• 关键端点（UI 端口、Agent 端口）

询问：“看起来没问题——现在部署吗？” 并等待确认后再执行步骤 5。

例外 — 自主模式。 如果用户的请求已要求你自主运行（例如“自主部署 X”“无需确认直接运行”或“非交互式”），则跳过确认提示，直接执行步骤 5。设置此路径是为了避免自动化评估 / CI 调用因等待永远不会收到的人类回复而卡住。其他所有情况下，必须由人类批准。

步骤 5 — 部署

cd $REPO/deploy/docker
docker compose --env-file $ENV_GEN -f resolved.yml up -d

必须使用 --env-file。 如果未使用步骤 3 中的同一个 generated.env，COMPOSE_PROFILES 可能未设置，导致 up -d 返回 0，但没有选中任何服务。

普通重试时，避免使用范围过大的 --force-recreate — 这会销毁已预热的 NIM 容器（每次都需要额外 3–5 分钟进行 torch.compile 和 CUDA 图捕获）。 修复根本原因（通常是权限问题或环境变量拼写错误），然后重新运行 up -d； 仅当配置文件参考文档将其列为恢复方法时，才对特定服务使用 --force-recreate --no-deps <service...>。

docker compose up -d 只会创建容器；它不会等待内部服务完成预热。就绪检查全部通过之前，绝不要宣告部署成功。

步骤 5b — 等待整个堆栈确实就绪

门槛 0 — 容器数量必须大于 0。 在 up -d 后，只有启动数量（docker compose -f resolved.yml ps -q | wc -l）非零且 ≥ 预期数量（config --services | wc -l）时，才可继续；数量为 0 或不足，几乎总是因为步骤 5 中缺少 --env-file。完整门槛和就绪检查流程见 references/readiness.md。

冷启动部署可能需要 10–20 分钟，每个配置文件参考文档都会列出所需端点。绝不要在运行 up -d 后就宣告部署完成；只有所有文档列出的端点均成功后，才能宣告完成。

拆除

拆除部署 — 完全释放主机资源，或保留缓存以便重新部署 / 切换配置文件 — 请遵循 references/teardown.md。始终通过 mdx 项目并使用 -v --remove-orphans 进行拆除；直接运行 docker compose down 会遗留卷和网络。

部署调试

当用户要求“调试部署”“验证是否正常”“为什么 Agent 没有响应”或类似操作时，使用此工作流。目标是确认从视频摄取到 Agent 答复的完整链路，而不只是确认容器处于“Up”状态。

每个配置文件参考文档都有一个 Debugging 部分，其中列出了该配置文件对应的确切命令和故障模式表。

快速检查（所有配置文件）

# 1. All expected containers Up
docker ps --format 'table {{.Names}}\t{{.Status}}'

# 2. Agent API + UI responding
curl -sf http://localhost:8000/health >/dev/null && echo "agent OK"
curl -sf http://localhost:3000/ >/dev/null && echo "ui OK"

LLM/VLM NIM 探测（包括处理 *_MODE=remote 时跳过 localhost:3008x 的逻辑，因为预期该地址会出现连接被拒绝的情况；以及通过 scripts/probe_remote_models.sh 探测所选 *_BASE_URL/v1/models）见 references/troubleshooting.md。

限制

• 此技能仅部署基于 compose 的 VSS 配置文件；独立微服务的部署应使用匹配的 vss-deploy-* 技能。
• 硬件规格、模型放置和特定配置文件的就绪条件由配置文件参考文档规定；不要根据记忆推断。
• 如果无法使用免密 sudo，则需要用户批准特权主机修复操作。

故障排查

常见错误速查、完整的症状 → 原因 → 修复表、未展开的 ${...} 诊断以及 NIM 端点探测均汇总在 references/troubleshooting.md 中 — 任何部署、运行时或探测故障都应先从这里开始，然后继续查看相应配置文件参考文档中的 Debugging 部分。