开始VSS前必看：API Key、Docker、NGC CLI三大准备工作，5分钟搞定不踩坑

开始VSS前必看API Key、Docker、NGC CLI三大准备工作5分钟搞定不踩坑【免费下载链接】video-search-and-summarizationNVIDIA AI Blueprint for video search and summarization (VSS) is a GPU-accelerated reference architecture for building video analytics agents with real-time verified alerts, visual QA, and automated reporting. The VSS Blueprint uses vision language models (VLMs) such as NVIDIA Cosmos, LLMs such as NVIDIA Nemotron, RAG, and NVIDIA NIMs.项目地址: https://gitcode.com/GitHub_Trending/vi/video-search-and-summarizationNVIDIAVSSVideo Search and Summarization视频搜索与摘要Blueprint是一套 GPU 加速的视频分析参考架构你可以用自然语言搜索视频、对视频提问、自动生成长视频摘要并推送实时告警。要跑通 VSS部署前的准备工作其实只有三件事——申请 API Key、配置 Docker、安装 NGC CLI。本文带你按清单逐项完成全程约 5 分钟并附常见报错的避坑提示。为什么是这三件事VSS 通过 Docker Compose 编排几十个微服务视频存储、行为分析、LLM/VLM 推理等模型和镜像则从 NVIDIA NGC 注册表拉取。因此API Key→ 从 NGC 下载模型与镜像的门票Docker NVIDIA Container Toolkit→ 承载 GPU 容器的运行时NGC CLI→ 命令行认证 NGC 并下载资源的工具。下图是 VSS 的整体架构三大准备工作就是让这套架构跑起来的地基准备工作一申请 API Key2 分钟1. 创建 NGC 账号并生成 Personal Key在浏览器打开 NVIDIA NGC 站点注册或登录账号点击右上角用户名 →Setup→API Keys点击Generate API Key→Generate Personal Key起个名字如 VSS Blueprint DevelopmentKey Permissions 选择 NGC Catalog生成后立即复制保存——Key 只显示这一次。⚠️避坑 1Cosmos 系列 VLM 容器只认Personal API Key旧版 Legacy Key 会直接认证失败。生成时选 Personal Key一劳永逸。2. 顺带准备 Hugging Face TokenVA-MCP 服务初始化时会从 Hugging Face 下载模型。没有 Token 也能跑但初始化很慢日志里容易出现 HTTP 429 限流错误。建议注册 Hugging Face 后创建一个只读Read权限的 Token。3. 验证 Key 是否可用export NGC_CLI_API_KEY你的NGC密钥 ngc registry resource list nvidia/vss-developer/*能正常列出资源即说明权限 OK。部署时这两个值会注入到各开发配置dev-profile的 overrides.env如NGC_CLI_API_KEY、HF_TOKEN两个变量。准备工作二安装并正确配置 Docker2 分钟1. 版本有硬性区间先看这个组件要求版本Docker Engine28.3.3 ~ 29.5.0必须小于 29.5.0Docker Composev2.39.1 及以上NVIDIA Container Toolkit1.17.8 及以上操作系统Ubuntu 24.04x86 主机版本不对齐的典型症状是拉取 NGC 镜像时莫名失败。先用docker --version和docker compose version各确认一次。⚠️避坑 2不要用 snap 安装 Docker。snap 版 Docker 运行在受限沙箱里文件访问受限部署过程行为异常。请用官方 apt 仓库安装并按 Docker 官方指引完成 post-installation 步骤让docker无需 sudo 即可运行。2. 配置 cgroup 驱动编辑/etc/docker/daemon.json加入 cgroupfs 驱动配置如已有其他配置合并进同一 JSON 对象{ exec-opts: [native.cgroupdrivercgroupfs] }然后重载并重启 Docker注意重启会停掉所有运行中的容器sudo systemctl daemon-reload sudo systemctl restart docker3. 安装 NVIDIA Container Toolkit按 NVIDIA 官方安装指南安装它让容器能直接使用宿主机 GPU。装完可执行nvidia-smi确认驱动版本与 GPU 识别正常。准备工作三安装 NGC CLI 并完成认证1 分钟NGC CLI 用于下载 Blueprint 资源并访问 NGC 模型/镜像要求4.10.0 及以上。1. 下载并安装以 AMD64 Linux 为例curl -sLo /tmp/ngccli.zip https://api.ngc.nvidia.com/v2/resources/nvidia/ngc-apps/ngc_cli/versions/4.10.0/files/ngccli_linux.zip sudo mkdir -p /usr/local/bin sudo unzip -qo /tmp/ngccli.zip -d /usr/local/lib sudo chmod x /usr/local/lib/ngc-cli/ngc sudo ln -sfn /usr/local/lib/ngc-cli/ngc /usr/local/bin/ngcARM64 平台请下载ngccli_arm64.zip包其余步骤相同。2. 验证并认证ngc --version # 确认版本 ≥ 4.10.0 ngc config set # 按提示填入第一步申请的 API Key⚠️避坑 3拉取资源报Missing org或Artifact is not Guest accessible说明 NGC 未选择组织。执行ngc config set重新选择与 API Key同一个组织再重试。3. 顺手克隆仓库部署包通过 Git LFS 管理大文件克隆前先装好git-lfs否则会拉到一堆指针文件sudo apt-get install git-lfs git clone --branch develop https://gitcode.com/GitHub_Trending/vi/video-search-and-summarization cd video-search-and-summarization git lfs install git lfs pull完成部署后长什么样三大准备就绪后按官方快速上手文档部署 base 配置你就可以在 Web UI 中上传视频、提问、生成报告上传视频后Agent 会结合 VLM 理解画面内容完成问答与报告生成例如识别视频中的事件并输出结构化摘要5 分钟自检清单#检查项验证命令 / 方法1NGC Personal API Key 已生成并保存能列出nvidia/vss-developer/*资源2HF 只读 Token 已准备以hf_开头的 Token3Docker 版本在 28.3.3 ~ 29.5.0 之间docker --version4cgroupfs 驱动已配置且已重启docker info \| grep -i cgroup5Compose 插件 ≥ v2.39.1docker compose version6GPU 容器可用nvidia-smi正常7NGC CLI ≥ 4.10.0 且已认证ngc --version、ngc config list8仓库已用 Git LFS 完整拉取大文件非指针文件下一步准备工作全部通过后打开官方 快速上手指南 按步骤部署你的第一个视觉 Agent 吧。更多环境要求、GPU 配置表和安装细节完整收录在 官方先决条件文档 中遇到问题可先查 FAQ其中专门整理了 Docker 版本、防火墙、NGC 权限等高频坑点。【免费下载链接】video-search-and-summarizationNVIDIA AI Blueprint for video search and summarization (VSS) is a GPU-accelerated reference architecture for building video analytics agents with real-time verified alerts, visual QA, and automated reporting. The VSS Blueprint uses vision language models (VLMs) such as NVIDIA Cosmos, LLMs such as NVIDIA Nemotron, RAG, and NVIDIA NIMs.项目地址: https://gitcode.com/GitHub_Trending/vi/video-search-and-summarization创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考