NVIDIA VSS Blueprint 完整教學 — Video Search and Summarization (v3.1.0)

本教學以 2026-05-15 main 分支快照 為基礎，搭配 v3.1.0 release 對照撰寫。 對應的 metadata 報告：2026-05-17-github-NVIDIA-AI-Blueprints-video-search-and-summarization.md 對應的 quarkdown HTML：projects/video-search-and-summarization/quarkdown-out/02-tutorial/index.html

1. 專案定位

1.1 一句話定位

「把影片 → 自然語言搜尋 / 摘要 / Q&A / 告警」這條鏈路，NVIDIA 把它做成 可部署的 reference blueprint (參考藍圖) + 可拆解抽用的微服務 + 可定義新 agent tool 的 Python 框架。

1.2 用一張圖看懂分層

 1┌─────────────────────────────────────────────────────────────────┐
 2│ Layer 4: Agentic & Offline Processing                           │
 3│  ├─ top_agent (LangGraph state machine, router pattern)         │
 4│  ├─ 24 NAT tools (search / summarize / Q&A / clip / report ...) │
 5│  └─ MCP server (Video Analytics MCP)                            │
 6├─────────────────────────────────────────────────────────────────┤
 7│ Layer 3: Downstream Analytics                                   │
 8│  ├─ trajectory enrichment                                       │
 9│  ├─ incidents builder                                           │
10│  └─ verified alerts (VLM 二次驗證)                              │
11├─────────────────────────────────────────────────────────────────┤
12│ Layer 2: Real-Time Video Intelligence (RTVI)                    │
13│  ├─ feature extraction                                          │
14│  ├─ embeddings (semantic)                                       │
15│  └─ stream understanding → Kafka                                │
16├─────────────────────────────────────────────────────────────────┤
17│ Layer 1: NIM Microservices                                      │
18│  ├─ VLM:  Cosmos-Reason2-8B / Qwen3-VL-8B                       │
19│  ├─ LLM:  Nemotron-Nano-9B-v2 / Llama-3.3-Nemotron-Super-49B   │
20│  └─ Edge: Nemotron-Nano-9B-v2-FP8 (unified memory)              │
21└─────────────────────────────────────────────────────────────────┘
22       ↑                                            ↑
23   Docker Compose (deployments/)              MCP / Kafka / Elasticsearch

1.3 五個官方 Agent Workflows

1.4 何時該用 VSS、何時不該

2. 安裝指南

2.1 兩種安裝路線

2.2 Prerequisites（兩條路線共用）

• API Keys：NVIDIA AI Enterprise developer licence（本機跑 NIM 必需）+ NGC API key（拉鏡像）
• OS：Ubuntu 22.04 / 24.04（x86）、DGX OS 7.4.0（DGX-SPARK）、Jetson Linux BSP 38.4/38.5（Thor）
• NVIDIA Driver：580.x 系列（依平台不同）
• NVIDIA Container Toolkit ≥ 1.17.8 + Docker ≥ 27.2.0 + Docker Compose v2.29.0+ + NGC CLI ≥ 4.10.0

💡 詳細版本對照表見 README §「System Requirements」。

2.3 路線 A：Brev Launchable

1. 在 build.nvidia.com 開啟 launchable
2. 啟動 2×RTX PRO 6000 SE AWS instance
3. 打開 scripts/deploy_vss_launchable.ipynb，依 cell 順序跑
4. notebook 內建：disk 切換到 ephemeral storage、Docker daemon 換 data-root、Brev secure link 自動偵測（BREV_ENV_ID / BREV_LINK_PREFIX）

2.4 路線 B：本機 Docker Compose

 1# 1. clone repo
 2git clone --depth 1 https://github.com/NVIDIA-AI-Blueprints/video-search-and-summarization.git
 3cd video-search-and-summarization
 4
 5# 2. 設定 .env（NGC API key、HOST_IP、選擇 profile）
 6cp deployments/developer-workflow/dev-profile-base/.env.example \
 7   deployments/developer-workflow/dev-profile-base/.env
 8vi deployments/developer-workflow/dev-profile-base/.env
 9
10# 3. 用 skills/deploy/SKILL.md 推薦的「compose 三步法」
11cd deployments/developer-workflow/dev-profile-base
12docker compose --env-file .env config > /tmp/resolved.yml    # dry-run
13less /tmp/resolved.yml                                       # 審視
14docker compose -f /tmp/resolved.yml up -d                    # 真正起服務
15
16# 4. 驗證
17docker compose ps
18curl http://localhost:8000/v1/health/live

⚠️ 不要 直接執行 scripts/dev-profile.sh（1412 行 bash）。skills/deploy 改用「config → 審視 → up」三步法，可審計、可重現。

2.5 開發環境（要改 agent 程式碼）

 1cd agent/
 2uv venv --python 3.13 && uv sync --group dev
 3source .venv/bin/activate
 4sudo apt-get install libcairo2-dev pkg-config python3-dev  # PDF 生成依賴
 5pre-commit install
 6
 7# 測試 / lint / type check
 8uv run pytest tests/unit_test/ -v
 9uv run ruff check src/
10uv run ruff format --check src/
11uv run mypy src/vss_agents/

3. 核心架構解析

3.1 agent/ — VSS Agent（Python 3.13 + NAT + LangGraph）

檔案布局（鏡像 src/ 與 tests/）：

 1agent/src/vss_agents/
 2├── agents/              # LangGraph state machine 編排
 3│   ├── top_agent.py     # 1509 行；router pattern，分派到 sub-agents / tools
 4│   ├── report_agent.py
 5│   ├── multi_report_agent.py
 6│   ├── critic_agent.py
 7│   ├── search_agent.py
 8│   └── postprocessing/  # URL validator 等 response 後處理
 9├── tools/               # 24 個 NAT tools（核心）
10│   ├── video_understanding.py   # VLM Q&A 主入口
11│   ├── video_caption.py / video_detailed_caption.py / video_skim_caption.py
12│   ├── lvs_video_understanding.py  # 長片摘要
13│   ├── search.py / attribute_search.py / embed_search.py
14│   ├── report_gen.py / template_report_gen.py / video_report_gen.py (1830 行)
15│   ├── chart_generator.py / fov_counts_with_chart.py
16│   ├── incidents.py / multi_incident_formatter.py
17│   ├── rtvi_vlm_alert.py
18│   ├── vst/             # Video Storage Toolkit (clip / snapshot / video_list)
19│   ├── code_executor/   # Docker sandbox 執行 LLM 生成的 Python
20│   └── register.py      # NAT entry point 註冊
21├── api/                 # FastAPI endpoints + custom workers + RTSP/video ingest
22├── data_models/         # Pydantic v2 模型
23├── embed/               # 向量檢索工具
24├── evaluators/          # LLM-judge：trajectory / QA / report quality
25├── utils/               # asyncmixin / reasoning_parsing / frame_select ...
26└── video_analytics/     # Video Analytics MCP server + Elasticsearch client

3.2 設計模式（重點）

1. Tool = FunctionBaseConfig 子類：每個 tool 都有自己的 Pydantic config + register.py entry point，註冊到 [project.entry-points.'nat.components']
2. Agent = LangGraph state machine：top_agent.py 是 router，依 user query 決定走哪幾個 tool / sub-agent
3. Config = YAML + ${ENV_VAR} substitution：profiles 在 deployments/developer-workflow/<profile>/vss-agent/configs/config.yml
4. Stubs：agent/stubs/ 放 NAT 框架的 mypy stubs，子類化 NAT base config 時要更新

3.3 deployments/ — Docker Compose 樹

 1deployments/
 2├── compose.yml              # 根 compose，include 各子系統
 3├── nim/                     # 7 個 NIM 模型 compose（cosmos-reason1/2、nemotron-3-nano、nano-9b-v2 +FP8、llama-3.3-nemotron-super-49b-v1.5、gpt-oss-20b、qwen3-vl-8b-instruct）
 4├── developer-workflow/      # 4 個 dev-profile（base / search / alerts / lvs）
 5├── foundational/            # mdx-foundational：Kafka / Redis / ELK / broker-health-check
 6├── agents/                  # VSS agent service compose
 7├── vst/                     # Video Storage Toolkit
 8├── rtvi/                    # Real-Time Video Intelligence
 9├── lvs/                     # Long Video Summarization
10├── vlm-as-verifier/         # VLM 二次驗證 service
11└── proxy/                   # nginx reverse proxy (Brev secure link 需要)

3.4 skills/ — 10 個 agentskills.io 規格 SKILL

SKILL 規格參考：https://agentskills.io/specification。所有含 eval/*.json 的 SKILL 都被 .github/skill-eval/ CI 在 PR 時自動驗證。

4. Helper Scripts 詳細用法

4.1 scripts/dev-profile.sh（1412 行 bash）

這支腳本是 NVIDIA 自己給示範用的 一鍵起服務 包裝器，但複雜度極高。建議：

• ✅ 讀：理解 IP 偵測、磁碟切換、NGC 登入、compose include 拼裝邏輯
• ❌ 改 / 直接執行：請改用 skills/deploy/SKILL.md 提供的 compose 三步法（config → 審視 → up）

4.2 scripts/deploy_vss_launchable.ipynb（1353 行 Jupyter）

Brev launchable 專用，做這幾件事：

1. 偵測 internal / external IP（NAT 環境）
2. 切換 Docker data-root 到 ephemeral storage（避免根碟撐爆）
3. 建立 Brev secure link（BREV_ENV_ID + BREV_LINK_PREFIX，所有 UI 透過 nginx proxy 統一走一個 port）
4. 透過 NGC API key 拉所有 NIM 鏡像
5. 起 compose

💡 ipynb 內部有大量 subprocess.run(..., shell=True, ...) — 因為它的執行環境是 Brev 雲端 VM（受信任），但 不要把這段邏輯複製到生產環境。詳見第 6 節資安掃描。

4.3 沒有「日常用」的 helper script

VSS 沒有 bin/vss 這類日常 CLI；日常操作走 nat serve + Docker Compose + agentskills。

5. 應用場景

5.1 短影片 Q&A（最快上手）

1# 起 base profile
2cd deployments/developer-workflow/dev-profile-base
3docker compose up -d
4
5# 用 agent CLI 問問題
6curl -X POST http://localhost:8000/v1/chat/completions \
7  -H "Content-Type: application/json" \
8  -d '{"model": "vss-agent", "messages": [{"role": "user", "content": "影片中發生了什麼？"}]}'

5.2 長片摘要（LVS）

部署 dev-profile-lvs，呼叫 lvs_video_understanding tool；內部會 chunk + dense captioning + 聚合，最後吐結構化摘要。注意：DGX Spark / ARM64 目前 LVS 鏡像缺 sbsa 變體（Issue #111 open）。

5.3 即時告警

dev-profile-alerts + rtvi/ 微服務；RTVI 抓 frame → VLM rt-vlm skill 連續推論 → 異常觸發 Kafka event → alerts skill 把 event 變成可觀察的告警。

5.4 影片搜尋（alpha）

dev-profile-search + multi-embedding fusion + VLM critique；目前 alpha，文檔指向 docs.nvidia.com。

5.5 「我只想拆 NIM 出來用」

直接走 deployments/nim/ 任一 compose（例如 nvidia-nemotron-nano-9b-v2/compose.yml），不用整套 VSS。

6. 資安掃描報告

掃描範圍：agent/src/、scripts/、deployments/；方法：grep -rnE 對 eval/exec/subprocess/secrets/http 等 pattern。

🟢 整體：低風險（沒有發現高風險議題）

重點觀察

1. 沒有 eval() / exec() 動態執行字串，這在 LLM 專案中已是優等。
2. 沒有發現硬編密碼 / API key；secrets 都靠 ${ENV_VAR} 或 Pydantic config 注入。
3. code_executor/ 走 Docker sandbox，比直接在 host 跑 LLM 生成的 code 安全很多。
4. 資訊外洩 vector：tools/report_gen.py:323 對 api.ipify.org 做 outbound 呼叫，建議內網部署用 firewall 阻擋 + 改用 env var 固定 IP。
5. Brev launchable notebook 不適合 copy 到生產：大量 subprocess.run(..., shell=True) + sudo + 切 docker data-root，是「一次性 setup script」風格。

給導入團隊的清單

• outbound firewall：阻擋 agent 容器對 api.ipify.org / ifconfig.me / icanhazip.com 的呼叫
• code_executor Docker backend 啟用最小權限（readOnlyRoot、drop caps、no host docker.sock）
• NGC API key、AWS secret、VLM API key 走 secret manager（Vault / AWS SM / k8s Secret），不要寫 .env
• CI 啟用 gitleaks（pre-commit 已含，但 CI 也要跑一遍）
• dev-profile-* 起服務後第一件事：把 nginx proxy 的 ${HOST_IP} 限制成 internal LAN（不要 0.0.0.0）

7. FAQ

Q1. VSS 跟「直接打 build.nvidia.com 的 VLM endpoint」差在哪？ A：VSS 是 整個 pipeline + 編排（取片 → 抽特徵 → 索引 → agent + tool 編排 → 報告）；單打 build.nvidia.com 是 一次推論。要做產品要 pipeline。

Q2. 沒有 NVIDIA AI Enterprise 授權能跑嗎？ A：可以「不本機跑 NIM」，改打 build.nvidia.com 的遠端 endpoint（agent 那段都能跑）。本機跑 NIM 才需要 AI Enterprise developer licence。

Q3. 跑得起來最低硬體？ A：x86 + 1 張 RTX A6000 / L40S（48 GB）可以跑 dev-profile-base 的最小組合。要跑 49B Nemotron Super 要至少 2 張 80 GB+ 卡。edge：DGX Spark 是設計目標。

Q4. 為什麼有 scripts/dev-profile.sh 還要 skills/deploy/？ A：dev-profile.sh 是 NVIDIA 內部演化來的，1412 行不利審計；skills/deploy/ 是 2026-05 新加的「compose 三步法」，可重現、可審計、由 coding agent 直接驅動。新專案請走 skills。

Q5. top_agent.py 1509 行讀不懂？ A：先看開頭 import + 末尾 register_function，再從 class TopAgentConfig(FunctionBaseConfig) 找 entry point，最後追 LangGraph state graph 定義（StateGraph / CompiledStateGraph 關鍵字）。

Q6. Issue #108 / #111 的 DGX Spark 問題是 blocker 嗎？ A：對 DGX Spark 是 blocker（VLM config 雙 /v1 + LVS 缺 sbsa 鏡像），請等 v3.1.1 或回退到 x86。x86 不受影響。

8. 進階技巧

8.1 想自己加 NAT tool

 1# agent/src/vss_agents/tools/my_tool.py
 2from nat.data_models.function import FunctionBaseConfig
 3from nat.cli.register_workflow import register_function
 4
 5class MyToolConfig(FunctionBaseConfig, name="my_tool"):
 6    threshold: float = 0.5
 7
 8@register_function(config_type=MyToolConfig)
 9async def my_tool(config: MyToolConfig, _builder):
10    async def _run(query: str) -> str:
11        return f"echo: {query} (threshold={config.threshold})"
12    yield FunctionInfo.from_fn(_run, description="echo with threshold")

接著在 agent/pyproject.toml 的 [project.entry-points.'nat.components'] 加一行，重啟 agent 就能用。

8.2 自訂 dev-profile

複製 deployments/developer-workflow/dev-profile-base/ → 改名 → 改 vss-agent/configs/config.yml（LLM / VLM / tools 開關）→ 改 compose include。

8.3 把 VSS 接到既有 LangGraph app

從 top_agent.py 借 StateGraph 定義，但只用 agents/ 跟 tools/ 兩層；丟掉 deployments/，把 NIM endpoint 指向公開的 build.nvidia.com。

8.4 接 MCP

VSS 的 agent/src/vss_agents/video_analytics/ 提供 Video Analytics MCP server；用 MCP client（例如 Claude Desktop、custom agent）連上去，可以問「過去 24 小時有幾起 incidents」這種結構化問題。

8.5 LangGraph 觀測

NAT 內建 IntermediateStepPayload + StreamEventData，加 callback handler 就能拿到所有 tool call、token usage、step trace。

9. 整合進其他工作流

9.1 與本知識系統的關係

9.2 適合做為「內部 RAG demo 標的」

VSS 程式碼結構乾淨（pyproject.toml + uv.lock + 嚴格型別 + AGENTS.md），是練習 graphify / paper-qa-lite / ai-notebooklm 的好標的。

10. 重點摘要 Checklist

• VSS = 5 個 official workflow + 4 個 dev-profile + 10 個 skill + 1 套 NAT-based agent 編排
• 想看示範 → scripts/deploy_vss_launchable.ipynb（Brev）
• 想本機跑 → skills/deploy/SKILL.md（不是 dev-profile.sh）的 compose 三步法
• 想改程式 → agent/ 內走 uv + ruff + mypy + pytest，pre-commit 已含 gitleaks
• 沒有高風險資安議題；中風險是 subprocess shell=True（限雲端 VM）與 urlopen api.ipify.org（資訊外洩）
• DGX Spark 目前有 LVS / VLM config 已知問題（Issue #108、#111 open），x86 不受影響
• 想拆抽 → deployments/nim/ 任一 compose 可獨立跑
• 想加 tool → tools/my_tool.py + entry point + 重啟 agent
• LangGraph 觀測點：IntermediateStepPayload + custom callback

11. 進一步閱讀

• 官方文件：https://docs.nvidia.com/vss/3.1.0/index.html
• Build 體驗：https://build.nvidia.com/nvidia/video-search-and-summarization
• NeMo Agent Toolkit：https://docs.nvidia.com/nemo/agent-toolkit/latest/index.html
• agentskills.io 規格：https://agentskills.io/specification
• LangGraph：https://langchain-ai.github.io/langgraph/
• Model Context Protocol：https://modelcontextprotocol.io/
• 本專案 agent/AGENTS.md（最濃縮的開發指南）

教學完成日：2026-05-17 | 對應 commit：dfa79c9（2026-05-15 main HEAD）| Generated by gh-tutorial-qd skill