vss-deploy-dense-captioning

目的

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

前置条件

独立部署 RT-VLM：

• Docker、Docker Compose、NVIDIA Container Toolkit，以及可用的 GPU。
• 将 NGC 注册表凭据存放在 $NGC_CLI_API_KEY 中，用于执行 docker login nvcr.io、拉取映像，以及在本地下载 NGC 模型/制品。
• curl、jq，以及用于存放独立 compose 副本的任意可写工作目录。

调用现有服务的 API：

• 正在运行且可通过 $BASE_URL 访问的 RT-VLM 服务。
• 根据服务的配置方式，在 $RTVI_VLM_API_KEY 或 $NGC_CLI_API_KEY 中设置 Bearer 令牌。

部署完整的 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 配置文件，请先按照 references/deploy-rt-vlm-service.md 中的独立 RT-VLM 流程操作，再调用 API。该流程采用与 vss-deploy-profile 相同的以 Compose 为核心的模式：收集上下文、运行预检、基于本地副本操作、使用 docker compose config 执行试运行、检查、部署，然后等待服务就绪。

独立部署流程

始终遵循以下顺序。绝不要跳过试运行。

# 1. Copy deploy/docker/services/rtvi/rtvi-vlm/rtvi-vlm-docker-compose.yml
#    into any writable standalone working directory.
# 2. Derive RTVI_VLM_IMAGE_TAG from that compose copy.
# 3. Strip the standalone-only dangling depends_on block from the copy.
# 4. Create a gitignored rtvi-vlm.env with the required RT-VLM values.
# 5. Prepare host bind paths such as $VSS_DATA_DIR/data_log/vst/clip_storage.
#    Use `sudo -n` for ownership fixes; if passwordless sudo is unavailable,
#    stop and ask the host owner to run the printed command manually.
# 6. docker compose --env-file rtvi-vlm.env -f rtvi-vlm-docker-compose.yml config --quiet
# 7. docker pull the exact RT-VLM image tag.
# 8. docker compose ... up -d rtvi-vlm, wait for ready, then smoke test.

在执行任何拉取或 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：它包含对同级 VLM/NIM 服务的 depends_on 引用，而这些服务只在完整的 VSS/met-blueprints Compose 项目中定义。独立参考文档会说明如何复制 Compose 文件、从中获取当前镜像标签、移除 depends_on 块，并在执行 up 前验证结果。

对于 Agent 驱动的验证，绝不要让 sudo 以交互方式提示输入密码。在执行任何需要特权的所有权变更或 Docker 操作之前，请使用 references/deploy-rt-vlm-service.md 中的非交互保护措施：优先使用普通的 docker；否则使用 sudo -n docker；如果 sudo -n 失败，请停止，并向主机所有者提供准确的手动命令，而不要改用交互式 sudo 重试或放宽权限。

如果在 Docker 28+ 上，docker pull 因 containerd snapshotter/unpack 错误而失败，请先按照独立参考文档修复 /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 bootstrap 主机（${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}"  # host-side RT-VLM port
export API_KEY="${NGC_CLI_API_KEY:-${RTVI_VLM_API_KEY:-}}" # bearer token used by host-side curl commands
: "${API_KEY:?Set NGC_CLI_API_KEY or RTVI_VLM_API_KEY before calling authenticated endpoints}"

以下所有请求都使用 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、示例数据包或任何其他备用来源推导替代值，因为那样验证的是与调用方所要求不同的流。

: "${RTSP_SAMPLE_URL:?Set RTSP_SAMPLE_URL to a reachable RTSP sample stream before RTSP validation}"
case "$RTSP_SAMPLE_URL" in
  rtsp://*) ;;
  *) echo "RTSP_SAMPLE_URL must be an rtsp:// URL, got: $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 "Install ffprobe or gst-discoverer-1.0 before RTSP validation." >&2
  exit 1
fi

快速入门 — 从本地视频生成密集型字幕

# 1. Upload the video, capture its file 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. Generate captions + alerts (SSE stream of chunked responses)
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 用于服务探测。除非 OpenAPI 中列出，否则不要假定 /v1/license 存在。

详细的端点架构、响应格式、CV 风格的单数流端点以及 26.05 兼容性说明，请参阅 references/api-surface-26.05.md。

常见工作流

• 已存储文件的字幕生成：使用 POST /v1/files 上传，通过返回的文件 ID 调用 /v1/generate_captions，使用 stream=true 启用 SSE，然后删除文件以释放存储空间。
• RTSP 实时字幕生成：调用方提供 RTSP_SAMPLE_URL 时，使用该确切 URL，并在注册前运行 RTSP Sample Stream Guard。如果 RTSP_SAMPLE_URL 为空，请勿从 NvStreamer 或 VIOS 推导替代流；应立即失败。注册前必须确认存在实际视频流/能力项；添加流、生成字幕，然后注销该流。
• 警报提示词：加入确定性的 Anomaly Detected: Yes/No 行。Kafka 发布由服务端配置，是 HTTP 响应的附加功能，相关说明见 references/kafka-workflows.md。
• Kafka 验证：主题名称以实时 vss-rtvi-vlm 环境为准。在完整的 VSS 实时警报配置中，使用现有的 VSS Kafka 容器 mdx-kafka 执行 CLI 检查和最终的事件使用方命令。独立验证时，使用通告 ${HOST_IP}:9092 的代理；未经用户确认，绝不要停止或替换现有代理。

错误参考

常见原因：请求格式或模型 ID 无效会导致 400；缺少或错误的 bearer token 会导致 401/403；文件/流已删除或端点不受支持会导致 404；上传内容过大会导致 413；架构验证失败会导致 422；并发过多会导致 429；推理/运行时故障会导致 500；启动尚未完成时会导致 503。请检查 docker logs vss-rtvi-vlm，查看服务端故障。