⚡

vss-deploy-dense-captioningSkill vss-deploy-dense-captioning

该技能用于在NVIDIA VSS（视频智能服务）环境中独立部署RT-VLM密集字幕微服务，并调用其REST API完成视频/RTSP流的字幕生成、文件上传、实时流管理、聊天补全及Kafka集成。包含Docker Compose部署流程、模型选择、健康检查和故障排除指南。关键词：RT-VLM、密集字幕、视频智能服务、VSS、实时视觉语言模型、Docker部署、Kafka、NVIDIA。

视频智能服务(VSS) 0 次安装 0 次浏览 更新于 9/6/2026
名称 vss-deploy-dense-captioning
描述 使用此技能在部署独立的RT-VLM密集字幕服务或调用其REST API（上传、字幕、流、聊天补全、Kafka）时使用。不用于VSS配置文件部署或视频搜索摄取。
开源协议 Apache-2.0 metadata:
版本 “3.2.1” github-url: “https://github.com/NVIDIA-AI-Blueprints/video-search-and-summarization” tags: “nvidia blueprint operational deployment”

目的

独立部署RT-VLM密集字幕微服务，并测试其公开的每个端点（文件上传、generate_captions、流添加/删除、聊天补全、Kafka主题）。

前提条件

对于独立RT-VLM部署：

  • Docker、Docker Compose、NVIDIA容器工具包以及可用GPU。
  • NGC注册表凭据存储在$NGC_CLI_API_KEY中，用于docker login nvcr.io、镜像拉取和本地NGC模型/工件下载。
  • curl、jq以及任意可写的独立compose副本工作目录。

对于现有服务API调用：

  • 运行中的RT-VLM服务可通过$BASE_URL访问。
  • Bearer令牌在$RTVI_VLM_API_KEY或$NGC_CLI_API_KEY中，取决于服务配置方式。

对于完整VSS配置文件部署：

  • 使用../vss-deploy-profile/SKILL.md；本技能不部署完整VSS配置文件。

说明

遵循下列路由表及分步工作流。每个以workflow、quick start或flow结尾的部分应自上而下执行。详细参考材料位于references/；直接执行文档化的工作流，除非未来修订版指定了具体辅助工具。

示例

完整的端到端示例保存在evals/下（每个*.json清单包含可运行场景）以及下方每个工作流的curl块内。使用nv-base validate <this-skill-dir> --agent-eval运行Tier-3评估以重放它们。

限制

  • 需要独立RT-VLM服务由本技能部署，或调用方可访问现有RT-VLM服务。
  • NGC托管的模型和NIM可能受到速率限制、GPU内存需求和许可证限制。
  • 并发、GPU内存和存储限制取决于主机硬件和配置文件的compose文件。
  • 将NGC_CLI_API_KEY、RTVI_VLM_API_KEY和rtvi-vlm.env文件保留在git和日志之外；不要在最终响应中回显凭证值或包含它们。
  • Docker组访问权限和sudo本质上是root级权限。在部署参考中使用非交互式sudo -n保护，在没有无密码sudo可用时停止并等待主机所有者操作。

故障排除

  • 错误：REST调用返回连接拒绝。原因：目标微服务未运行。解决方案：探测/docs或/health；通过vss-deploy-profile或匹配的vss-deploy-*技能重新部署。
  • 错误：NGC拉取的HTTP 401/403。原因：NGC_CLI_API_KEY缺失/过期。解决方案：重试前执行docker login nvcr.io并重新导出密钥。
  • 错误：容器OOM或模型加载失败。原因：所选配置文件的GPU内存不足。解决方案：切换到较小变体或通过docker compose down释放GPU。

部署并使用RT-VLM密集字幕（VSS 3.2）

RT-VLM是NVIDIA的实时视觉语言微服务：解码视频（文件或RTSP）、分块、运行VLM（cosmos-reason1、cosmos-reason2、cosmos-reason3或任何OpenAI兼容模型），通过SSE/HTTP流式返回密集字幕，并将字幕、事件告警和错误发布到Kafka。使用本技能可在完整VSS配置文件未运行时独立部署RT-VLM服务，然后调用其/v1/...API生成字幕、上传文件、管理实时流、健康检查、NIM兼容聊天补全或Prometheus指标。API参考：https://docs.nvidia.com/vss/latest/real-time-vlm-api.html。

部署路由

如用户要求部署完整VSS配置文件，请使用../vss-deploy-profile/SKILL.md。该技能负责配置文件路由、generated.env、resolved.yml、多服务大小调整及全栈部署/拆除。

如用户要求独立RT-VLM密集字幕，或无已有VSS配置文件运行，请在调用API前使用references/deploy-rt-vlm-service.md中的独立RT-VLM流程。这遵循与vss-deploy-profile相同的compose中心模式：收集上下文、运行预检、在本地副本上工作、用docker compose config试运行、审查、部署，然后等待健康。

独立部署流程

始终按此顺序执行。切勿跳过试运行。

# 1. 复制 deploy/docker/services/rtvi/rtvi-vlm/rtvi-vlm-docker-compose.yml 到任意可写的独立工作目录。
# 2. 从该compose副本派生 RTVI_VLM_IMAGE_TAG。
# 3. 删除副本中仅独立模式悬空的 depends_on 块。
# 4. 创建包含必需RT-VLM值的gitignored rtvi-vlm.env。
# 5. 准备宿主绑定路径，如 $VSS_DATA_DIR/data_log/vst/clip_storage。使用 sudo -n 修复所有权；如果无密码sudo不可用，停止并要求主机所有者手动运行打印的命令。
# 6. docker compose --env-file rtvi-vlm.env -f rtvi-vlm-docker-compose.yml config --quiet
# 7. docker pull 确切的RT-VLM镜像标签。
# 8. docker compose ... up -d rtvi-vlm，等待就绪，然后冒烟测试。

任何拉取或up前先运行预检；在此处停止并修复失败，而不是调试RT-VLM本身：

nvidia-smi --query-gpu=index,name --format=csv,noheader
nvidia-container-cli info
docker compose version
docker run --rm --gpus all nvidia/cuda:12.4.0-base-ubuntu22.04 nvidia-smi

独立单文件部署时，不要直接运行原始deploy/docker/services/rtvi/rtvi-vlm/rtvi-vlm-docker-compose.yml：它包含对仅在完整VSS/met-blueprints compose项目中定义的兄弟VLM/NIM服务的depends_on引用。独立参考说明了如何复制compose文件、从中派生当前镜像标签、移除depends_on块并在up前验证结果。

代理驱动验证时，绝不要让sudo交互式提示。在任何特权所有权或Docker操作前，使用references/deploy-rt-vlm-service.md中的非交互保护：优先使用普通docker；否则使用sudo -n docker；若sudo -n失败，则停止并提供主机所有者应执行的确切手动命令，不要重试交互式sudo或削弱权限。

若docker pull在Docker 28+上因containerd快照器/解包错误失败，在重试前应用独立参考中的/etc/docker/daemon.json下containerd-snapshotter=false修复。

最小独立rtvi-vlm.env值：

主机环境变量 何时需要 用途
NGC_CLI_API_KEY 独立部署路径 NGC注册表镜像拉取和NGC模型/工件下载
RTVI_VLM_API_KEY或NGC_CLI_API_KEY 认证API调用 服务运行后的RT-VLM Bearer认证
RTVI_VLM_PORT 总是 映射到容器8000的主机API端口
HOST_IP 总是 Kafka引导主机（${HOST_IP}:9092）
VSS_DATA_DIR 总是 必需的剪辑存储绑定挂载
RTVI_VLM_MODEL_TO_USE 总是（独立） 后端选择器；本地默认模型用cosmos-reason3，远程/兄弟端点用openai-compat
RTVI_VLM_MODEL_PATH 本地自托管模型 源支持的Cosmos Reason3 Nano BF16路径：ngc:nim/nvidia/cosmos3-nano-reasoner:bf16-final
RTVI_VLM_ENDPOINT RTVI_VLM_MODEL_TO_USE=openai-compat 远程/兄弟OpenAI兼容VLM端点
VLM_NAME RTVI_VLM_MODEL_TO_USE=openai-compat 该端点暴露的模型/部署名称

设置

export BASE_URL="http://localhost:${RTVI_VLM_PORT:-8018}"  # 主机侧RT-VLM端口
export API_KEY="${NGC_CLI_API_KEY:-${RTVI_VLM_API_KEY:-}}" # 主机侧curl命令使用的Bearer令牌
: "${API_KEY:?在调用认证端点前设置NGC_CLI_API_KEY或RTVI_VLM_API_KEY}"

下方每个请求均使用Authorization: Bearer $API_KEY。健康端点（/v1/health/*、/v1/ready、/v1/live、/v1/startup）通常无需认证。

使用前冒烟测试：

curl -fsS "$BASE_URL/v1/health/ready"
MODEL_ID="$(curl -fsS "$BASE_URL/v1/models" -H "Authorization: Bearer $API_KEY" | jq -r '.data[0].id // .id')"
curl -fsS "$BASE_URL/openapi.json" | jq -r '.paths | keys[]' | sort

RTSP示例流保护

当任务或评估指定RTSP_SAMPLE_URL时，将该确切环境变量视为必需输入。在探测或注册任何流前验证其已设置且非空；若缺失则停止并显示明确失败信息。不要从NvStreamer、VIOS、sample-data包或任何其他回退派生替代流，因为那会验证与调用方请求不同的流。

: "${RTSP_SAMPLE_URL:?在RTSP验证前设置RTSP_SAMPLE_URL为可达的RTSP示例流}"
case "$RTSP_SAMPLE_URL" in
  rtsp://*) ;;
  *) echo "RTSP_SAMPLE_URL必须是rtsp:// URL，收到: $RTSP_SAMPLE_URL" >&2; exit 1 ;;
esac

if command -v ffprobe >/dev/null 2>&1; then
  ffprobe -v error -rtsp_transport tcp \
    -select_streams v:0 -show_entries stream=codec_type \
    -of csv=p=0 "$RTSP_SAMPLE_URL" | grep -qx video
elif command -v gst-discoverer-1.0 >/dev/null 2>&1; then
  gst-discoverer-1.0 "$RTSP_SAMPLE_URL" | grep -qi 'video'
else
  echo "安装ffprobe或gst-discoverer-1.0后再进行RTSP验证。" >&2
  exit 1
fi

快速开始 — 从本地视频生成密集字幕

# 1. 上传视频，捕获其文件id
FILE_ID=$(curl -fsS -X POST "$BASE_URL/v1/files" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@/path/to/warehouse.mp4" \
  -F "purpose=vision" \
  -F "media_type=video" | jq -r '.id')

# 2. 生成字幕+告警（分块响应的SSE流）
curl -N -X POST "$BASE_URL/v1/generate_captions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"id\": \"$FILE_ID\",
    \"prompt\": \"Write a concise dense caption for each 10-second segment of this warehouse video.\",
    \"model\": \"$MODEL_ID\",
    \"chunk_duration\": 10,
    \"stream\": true
  }"

API表面

在调用可选端点前，使用实时OpenAPI作为真相来源：

curl -fsS "$BASE_URL/openapi.json" | jq -r '.paths | keys[]' | sort

VSS 3.2核心路径：

  • POST /v1/files：多媒体上传；将返回的文件id传给字幕生成，完成后删除文件。
  • POST /v1/generate_captions：文件或流字幕。使用GET /v1/models返回的确切模型id；cosmos-reason2或cosmos-reason3等别名是后端选择器，不是请求模型id。
  • POST /v1/streams/add、GET /v1/streams/get-stream-info和DELETE /v1/streams/delete/{stream_id}：RTSP生命周期。从results[0].id解析流id。
  • POST /v1/chat/completions：OpenAI兼容文本和多模态调用。当前26.05版本对纯文本/v1/completions返回HTTP 400；验证遗留行为时按预期处理。
  • GET /v1/health/ready、/v1/models、/v1/assets/stats和/v1/metrics：服务探测。不要假设/v1/license存在，除非OpenAPI列出。

详细端点模式、响应形状、CV风格单数流端点和26.05兼容性说明见references/api-surface-26.05.md。

常见工作流

  • 存储文件字幕：用POST /v1/files上传，以返回文件id调用/v1/generate_captions，用stream=true做SSE，完成后删除文件释放存储。
  • RTSP实时字幕：调用方提供RTSP_SAMPLE_URL时，注册前使用该确切UR并运行RTSP示例流保护；为空时不要从NvStreamer或VIOS派生替代流，快速失败。要求真实视频流/编码条目后再添加流、生成字幕并注销。
  • 告警提示：包含确定性的Anomaly Detected: Yes/No行。Kafka发布是服务器端配置，对HTTP响应附加，记录于references/kafka-workflows.md。
  • Kafka验证：信任实时vss-rtvi-vlm环境中的主题名称。完整VSS告警实时配置中，对CLI检查和最终事件消费者命令使用现有VSS Kafka容器mdx-kafka。独立验证时使用广播${HOST_IP}:9092的broker；未经确认绝不停止或替换现有broker。

错误参考

常见原因：400无效请求形状或模型id，401/403缺失或错误Bearer令牌，404已删除文件/流或不支持端点，413上传过大，422架构验证失败，429并发过多，500推理/运行时失败，503启动仍在进行。检查docker logs vss-rtvi-vlm查看服务端失败。