
名称	vss-generate-video-calibration
描述	在本地MP4、RTSP或捆绑的示例数据集上运行AutoMagicCalib，并在需要时部署vss-auto-calibration。不要用于非AMC校准或运行分析。
开源协议	Apache-2.0 metadata:
版本	“3.2.1” github-url: “https://github.com/NVIDIA-AI-Blueprints/video-search-and-summarization” tags: “nvidia blueprint operational”

目的

对本地文件、RTSP流或捆绑的示例数据集端到端运行AutoMagicCalib，并在需要时部署AMC微服务。

说明

遵循下面的路由表和逐步工作流。每个以 工作流、快速开始 或流程结尾的段落都旨在从上到下执行。详细参考资料位于 references/ 中；仅加载所选输入模式需要的参考资料。

示例

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

限制

需要匹配的 VSS 配置 / 微服务已部署并可从调用方访问。
NGC 托管的模型和 NIM 可能受到速率限制、GPU 内存要求和许可证限制。
并发性、GPU内存和存储限制取决于主机硬件和配置文件的compose文件。

故障排除

错误：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。

VSS 生成视频标定

通过三种输入源之一运行 AutoMagicCalib，并通过微服务 REST API 驱动标定。不同输入源的输入处理工作不同；从 verify_project 开始的后续操作全部相同，并在本文件中。选择正确的输入模式参考，并将其与下面的共享标定尾部配对。

仅在需要时加载共享辅助参考：

当模式参考需要共享的 create_project、视频上传或交接片段时，阅读 references/common-steps.md。
当需要验证→标定→轮询→结果的尾部的可复用 Python 实现时，阅读 references/calibration-tail.md。

输入路由

将用户的请求匹配到一种模式，然后加载该模式参考以进行输入收集、模式特定的 API 调用和完整的 Python 脚本。

用户说 / 拥有	模式	参考资料
“启动 AMC” / “部署自动标定” / “设置 auto-magic-calib” / “启动 AMC 微服务”	`deploy`	`references/deploy-auto-calibration-service.md`
“标定我的视频” / “从视频文件标定” / 本地 `cam_*.mp4` 文件	`videos`	`references/videos.md`
“标定 RTSP 流” / “从实时摄像机标定” / 实时 RTSP URL	`rtsp`	`references/rtsp.md`
“测试样本数据集” / “验证 AMC 安装” / “启动并测试”	`sample-dataset`	`references/sample-dataset.md`

消歧规则： 如果用户在要求启动 / 部署 / 设置 AMC（没有标定动词）→ deploy。如果他们提供 RTSP URL → rtsp。如果他们提到本地文件 / 视频目录 → videos。如果他们要求验证安装或测试捆绑样本 → sample-dataset。组合意图（例如"启动 AMC 并标定我的视频"）→ 先执行 deploy，然后执行标定模式。若有歧义，请通过 AskUserQuestion 提问。

先决条件（所有标定模式通用）

AMC 微服务 + UI 正在运行。如果没有，先参考 references/deploy-auto-calibration-service.md。
微服务可在 http://<HOST_IP>:${VSS_AUTO_CALIBRATION_PORT:-8010}/v1/ready 访问 → {"code":0,...}。
Projects 目录对容器用户可写。如果你不是刚刚部署（所以部署参考的第 5 步没有执行），请确认 references/deploy-auto-calibration-service.md § Step 5 中的写测试 —— 否则第一次 create_project 会返回 [Errno 13] Permission denied。
安装了带 requests 的 Python 3（每个输入模式参考都包含一个用于直接运行的自修复 venv 后备）。

模式特定的先决条件（RTSP 模式需要 VIOS，示例数据集模式需要示例 zip）位于各自的参考中。

共享标定尾部

无论输入模式如何，验证 → 标定 → 轮询 → 结果的序列都是相同的。在模式特定参考上传视频 / 摄取 RTSP 片段 / 上传捆绑样本后，运行此尾部。对于共享 Python 片段，请使用 references/calibration-tail.md。

步骤 A — 验证项目

POST /v1/verify_project/<project_id>

响应：{"project_state": "READY"} — 在标定前必须为 READY。如果不是 READY，请重新检查视频 + 对齐 + 布局是否存在（通过 API 或通过 UI 手动对齐）。

步骤 B — 开始标定

在标定前确认计划。 无论设置文件和检测器是自动检测还是询问的，都要在 POST /calibrate 之前通过 AskUserQuestion 显示简短摘要并确认。解析的值是默认值，因此确认只需单击一次 —— 但用户可以切换检测器或跳过自动检测的设置文件。摘要包含：

检测器 — resnet 或 transformer（要发送的值）。
标定设置 — 应用的文件（路径），或默认参数（并可以选择先在 UI 中调整它们——见下文）。
可选覆盖 — 如果存在，则为 ground-truth zip 和焦距。

示例数据集安装检查运行使用固定的 resnet，可以不经确认直接进行。

POST /v1/calibrate/<project_id>
Content-Type: application/json

{"detector_type": "resnet"}   # 或 "transformer"

有关 /v1/calibrate 的 detector_type 是独立参数——不是由 /v1/config/<id> 使用的。如果用户提供了标定设置文件，解析其中的 "detector" / "detector_type" 并使用该值。如果文件未指定，则默认值 (resnet) 是上面确认中显示的值——用户可以在标定前在此处切换。如果没有任何设置文件，请通过 AskUserQuestion 询问用户：

resnet — 默认，快速。
transformer — 更慢，在严重遮挡下效果更好。

UI 步骤 3（参数）不涵盖检测器选择；永远不要假设用户在 UI 中选择了。

另外当没有设置文件时，询问是否先调整标定参数 (AskUserQuestion)：

使用默认参数继续 — 适合典型仓库场景；除非用户有特定调整想法，否则推荐。
先在 UI 中调整参数 — 打开项目，进入步骤 3：参数，更改值，单击保存；然后继续。

等待用户的选择——如果他们选择调整，也需要等待他们确认已保存——然后再调用 /calibrate。

步骤 C — 轮询完成

GET /v1/get_project_info/<project_id>

每 10 秒轮询一次。project_info.project_state：

状态	含义
`RUNNING`	标定进行中
`COMPLETED`	已完成
`ERROR`	失败 —— 通过 `GET /v1/amc/calibrate/<id>/log` 拉取日志

当标定开始时，显示项目 ID、UI URL（http://<HOST_IP>:${VSS_AUTO_CALIBRATION_UI_PORT:-5000}）和日志端点，以便用户在运行期间查看进度。在 RUNNING 期间，至少每分钟输出一个带有已用时间的进度行，避免长运行看起来像卡住。在 ERROR 时，在停止前获取并显示 GET /v1/amc/calibrate/<id>/log 的最后几行。日志也可以通过 GET /v1/calibrate/<project_id>/log/<type>/stream 流式传输。

典型时间：10–60 分钟（自有视频），10–30 分钟（捆绑样本）。

步骤 D — 结果

GET /v1/get_project_info/<project_id>                    # 项目状态
GET /v1/result/<project_id>/evaluation_statistics        # 仅当上传了 GT
GET /v1/result/<project_id>/overlay_image                # 视觉覆盖图 (PNG)
GET /v1/amc/calibrate/<project_id>/log                   # 标定日志

评估响应包括 Average L2 distance(m) 和 Average reprojection error 0(px)。只有当上传了地面真值 GT.zip 时才生成评估指标—— 缺失 evaluation_statistics 结果是正常的，并且不等于结束。

在 COMPLETED 之后，始终让用户能够查看该确切项目的结果，无论是否存在指标：

UI — http://<HOST_IP>:${VSS_AUTO_CALIBRATION_UI_PORT:-5000}；打开项目，然后打开"结果"页面查看叠加图。
磁盘上的叠加图 — ${VSS_APPS_DIR}/services/auto-calibration/projects/project_<id>/output/multi_view_results/BA_output/results_ba_scaled_world/overlay_img_*.png（单摄像头项目使用 output/single_view_results/cam_00/verification_map_overlay.png）。
项目文件 — ${VSS_APPS_DIR}/services/auto-calibration/projects/project_<id>/。

步骤 E — VGGT 细化

完成 AMC 运行后，始终检查项目信息中的 vggt_state。VGGT 模型暂存是可选设置且不得阻塞 AMC 结果，但 AMC 后的处理遵循以下状态：

如果 vggt_state == "READY" 且用户明确请求 VGGT 细化或在此设置流程中暂存了 VGGT，则直接运行 VGGT 细化，不要再询问。
如果 vggt_state == "READY" 但 VGGT 在此请求之前已经暂存，且用户尚未要求 VGGT 细化输出，则通过 AskUserQuestion 询问是否在开始之前运行细化。
如果 VGGT 未就绪，跳过细化并提及 VGGT 细化在暂存模型后可用（参见 references/deploy-auto-calibration-service.md 步骤 2）。

POST /v1/vggt/calibrate/<project_id>
GET  /v1/get_project_info/<project_id>                    # 轮询 vggt_state
GET  /v1/vggt_results/<project_id>/evaluation_statistics  # VGGT 指标

设置文件 + 检测器模式

在所有三种模式下都是可选的。当用户提供 JSON 设置文件（通常从 UI 步骤 3 下载导出）时，原样 POST：

POST /v1/config/<project_id>
Content-Type: application/json

<文件内容，按原样发布>

该文件替换用户本会在 UI 步骤 3（校正、束调整、评估旋钮、检测器等）中调整的内容。成功 POST 后，也要解析文件中的 "detector" / "detector_type"——如果是 "resnet" 或 "transformer"，请将该值用于步骤 B 中的 /calibrate 调用（检测器是独立 API 参数，不是 /config 消耗的）。

非 2xx 会浮出——不要静默回退。如果用户选择了 UI 回退路径，则完全跳过此调用。

UI 回退模式

当磁盘上没有对齐 / 布局文件时，指导用户到相应的 AMC UI 步骤：

设置缺失 → “打开 UI 项目 <project_id>，转到步骤 3：参数，通过设置对话框调整（或接受默认值），单击保存。” 另外：在 /calibrate 调用之前，通过 AskUserQuestion 询问用户是否使用 resnet 还是 transformer 检测器——步骤 3 不涵盖检测器选择。
布局缺失 → “打开 UI 项目 <project_id>，转到步骤 2：视频配置，仅上传 layout.png（不要重新上传视频——它们已经通过 API/RTSP 附加），单击保存。”
对齐缺失 → “打开 UI 项目 <project_id>，转到步骤 4：对齐，上传 alignment_data.json 或在布局上标记对应点，单击保存。”

等待用户确认。对于对齐 / 布局，在继续之前检查磁盘：

# 项目状态位于 $VSS_APPS_DIR/services/auto-calibration/projects 下
# （该路径在 deploy/docker/services/auto-calibration/ms/compose.yml 中绑定挂载到 MS 容器）
HOST_PROJECTS="${VSS_APPS_DIR}/services/auto-calibration/projects"

ls "$HOST_PROJECTS/project_<project_id>/manual_adjustment/"
# 预期: alignment_data.json, layout.png

成功标准

轮询后 project_state == "COMPLETED"。
如果使用了手动对齐：${VSS_APPS_DIR}/services/auto-calibration/projects/project_<id>/manual_adjustment/ 包含 alignment_data.json + layout.png。
如果上传了 GT：评估返回典型阈值（Average L2 distance(m) < 1.5，Average reprojection error 0(px) < 5 对于你的数据；捆绑样本 < 10）。
没有 ERROR 状态。

关键输出文件

在 ${VSS_APPS_DIR}/services/auto-calibration/projects/project_<project_id>/ 下：

project_<project_id>/
├── manual_adjustment/
│   ├── alignment_data.json
│   └── layout.png
├── output/
│   ├── single_view_results/cam_XX/
│   │   ├── camInfo_hyper_XX.yaml
│   │   └── trajDump_Stream_0_3d.txt
│   ├── multi_view_results/BA_output/results_ba/
│   │   ├── initial/camInfo_XX.yaml
│   │   └── refined/camInfo_XX.yaml          # ← 最终标定
│   └── multi_view_results/BA_output/results_ba_scaled_world/
│       └── overlay_img_XX.png               # ← 用于审查的视觉叠加图
└── calibration.log

跨领域故障排除

特定于模式的问题位于各参考的故障排除表中。

问题	修复
`verify_project` 状态不是 `READY`	确认视频已上传/摄取且对齐 + 布局存在（通过 API 或通过 UI 手动对齐）。上传步骤参考特定模式。
UI 步骤后缺少手动对齐文件	用户未单击保存；还要检查 `${VSS_APPS_DIR}/services/auto-calibration/projects/project_<id>/manual_adjustment/` 是否存在。
标定卡在 `RUNNING` 超过 90 分钟	`GET /v1/amc/calibrate/<id>/log`——通常是 tracklets 不足（场景太静态）。请参阅根 `README.md` 中的"自定义数据集"指南。
立即 `ERROR` 状态	检查视频命名：必须是 `cam_00.mp4`, `cam_01.mp4`, … 连续的（视频模式）/ camera_name 标签（RTSP 模式）。
L2 低但重投影高	在输入上传期间提供显式 `focal_length` 覆盖（见视频 / rtsp 参考）。
VGGT `INIT` 永远不会 `READY`	VGGT 模型未加载——参见 `references/deploy-auto-calibration-service.md` 步骤 2。
上传超时	大视频—— 在按模式 Python 脚本中将 `timeout=300` 提高到例如 `600`。
端口扫描找不到后端	后端未运行——先执行 `references/deploy-auto-calibration-service.md`。

对于下游技能 — MV3DT 导出

下游消费者（例如由另一团队拥有的多视图 3D 跟踪技能）直接从微服务获取 MV3DT 格式的标定输出。此技能返回 project_id；下游技能调用：

GET /v1/result/{project_id}/mv3dt_result?result_type=amc
# 响应: application/zip — 包含 transforms.yml 的 mv3dt_output.zip

对于 VGGT 细化的输出（仅当 VGGT 运行到 COMPLETED 时才可用，见步骤 E）：

GET /v1/result/{project_id}/mv3dt_result?result_type=vggt
# 响应: application/zip — vggt_mv3dt_output.zip

下游技能流程：

使用用户的输入调用此技能；捕获打印的 project_id。
等待技能返回（它内部轮询直到 COMPLETED）。
GET /v1/result/{project_id}/mv3dt_result?result_type=amc — 将 ZIP 保存到本地。
如果 VGGT 也运行了，可选地获取 ?result_type=vggt 以获得细化的 MV3DT。

VSS视频标定生成Skill vss-generate-video-calibration

目的

说明

示例

限制