vss-deploy-dense-captioning

用途

独立部署 RT-VLM 密集描述微服务，并测试其提供的所有端点（文件上传、generate_captions、流添加／删除、chat-completions、Kafka 主题）。

前置条件

独立部署 RT-VLM：

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

针对现有服务调用 API：

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

完整 VSS 配置部署：

• 使用 ../vss-deploy-profile/SKILL.md；此技能不会部署完整的 VSS 配置。

说明

按照以下路由表和分步工作流操作。每个以 工作流、快速入门 或 流程 结尾的章节都应从头到尾依次执行。详细参考资料位于 references/ 中；除非后续修订指定了具体辅助工具，否则请直接执行文档中的工作流。

示例

端到端示例存放在 evals/ 下（每个 *.json 清单都包含一个可运行的场景），也内嵌在下方各工作流的 curl 代码块中。运行 Tier-3 评估：nv-base validate <this-skill-dir> --agent-eval，即可重放这些示例。

限制

• 需要通过此技能部署独立 RT-VLM 服务，或调用方能够访问现有 RT-VLM 服务。
• NGC 托管的模型和 NIM 可能受速率限制、GPU 内存要求和许可证限制约束。
• 并发量、GPU 内存和存储限制取决于主机硬件及配置的 compose 文件。
• 请勿将 NGC_CLI_API_KEY、RTVI_VLM_API_KEY 和 .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 或任何 兼容 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 .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 .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.

在执行任何 pull 或 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 pull 在 Docker 28+ 上因 containerd 快照器/解包错误而失败，请先按照独立参考文档应用 /etc/docker/daemon.json 中的 containerd-snapshotter=false 修复，然后再重试。

独立部署所需的最低 .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-reason2，远程/同级端点使用 openai-compat
RTVI_VLM_MODEL_PATH	本地自托管模型	有来源依据的 Cosmos Reason 2 路径：ngc:nim/nvidia/cosmos-reason2-8b:hf-1208
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 用于上传 multipart 媒体；将返回的文件 id 传入 字幕生成请求，并在完成后删除文件。
• POST /v1/generate_captions 用于为文件或流生成字幕。请使用 GET /v1/models 返回的 确切模型 id；cosmos-reason2 等别名是后端选择器，不是请求模型 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 派生替代流；应立即失败。注册前必须有实际的视频流／caps 条目；添加流、生成字幕，然后取消注册。
• 告警提示词：添加确定性的 Anomaly Detected: Yes/No 行。 Kafka 发布由服务端配置，作为 HTTP 响应的补充功能，详见 references/kafka-workflows.md。
• Kafka 验证：主题名称以实时 vss-rtvi-vlm 环境为准。 在完整的 VSS 告警实时配置中，使用现有的 VSS Kafka 容器 mdx-kafka 执行 CLI 检查和最终的事件消费者命令。对于独立验证，请使用会通告 ${HOST_IP}:9092 的 broker；未经用户确认，切勿停止或替换已存在的 broker。

错误参考

常见原因：请求格式或模型 id 无效时返回 400；缺少或 bearer token 错误时返回 401/403； 文件／流已删除或端点不受支持时返回 404；上传内容过大时返回 413；架构验证失败时返回 422； 并发过高时返回 429；推理／运行时故障时返回 500；启动仍在进行时返回 503。 请检查 docker logs vss-rtvi-vlm 以排查服务端故障。