amc-run-sample-calibration

技能：校准示例数据集

何时使用此技能

当用户想要使用捆绑的示例数据集对正在运行的 AMC 技术栈进行合理性检查时，启用此技能。常见提示：

• “测试示例数据集” / “运行示例校准”
• “验证 AMC 安装”
• “启动并测试”（如果 MS 尚未运行，请与 amc-setup-calibration-stack 配合使用）

不要在以下情况下使用此技能：

• 用户提及自己的视频路径（例如 /data/videos/、不属于捆绑 ZIP 的 cam_*.mp4）——转到 amc-run-video-calibration。
• 用户提供实时 RTSP 流或 rtsp://... URL——转到 amc-run-rtsp-calibration。
• 此技能仅适用于 assets/sdg_08_2_sample_data_010926.zip。

前提条件：AMC 微服务正在 8000-8009 端口之一运行。如果未检测到后端，请先委派给 amc-setup-calibration-stack。

如果当前环境无法继续执行（没有后端、缺少示例数据等），请指出阻碍因素，并简要说明预期工作流和 API 调用顺序，让用户了解满足前提条件后将运行哪些内容。不要编造校准输出、评估指标或轨迹。

概览

使用捆绑的示例数据集（sdg_08_2_sample_data_010926.zip，包含 4 个带有真实标注的合成仓库摄像头），对正在运行的 AutoMagicCalib 微服务执行完整校准。在使用真实数据前，可借此验证刚启动的技术栈是否能端到端正常工作。

示例数据包含 GT，因此运行会生成评估指标（L2 距离、重投影误差）——无需调整校准参数。

前提条件

• AMC 微服务正在运行（如果尚未运行，请参阅 skills/amc-setup-calibration-stack/SKILL.md）
• 示例 ZIP 文件位于 assets/sdg_08_2_sample_data_010926.zip
• 已安装 Python 3 和 requests，或使用下方的 Swagger UI 方法
  • 运行脚本前，请明确安装：python3 -m pip install requests
  • 如果无法使用 pip，请先安装发行版提供的 Python 打包支持

说明

“启动 AMC 并测试示例数据集”（或类似请求）：

1. 首先运行 skills/amc-setup-calibration-stack/SKILL.md。
2. 等待 /v1/ready 返回 OK。
3. 提取示例数据（见下方代码片段）——操作可幂等执行，重复运行也安全。
4. 运行运行脚本中的捆绑脚本。
5. 报告最终指标和 UI URL，供用户手动检查。
6. 如果项目报告 vggt_state: READY，则默认尝试进行 VGGT 精细化；否则，脚本会说明 VGGT 设置为可选项，之后可启用以进行精细化。

“测试示例数据集”（MS 已在运行）：

1. 检测后端：扫描 8000–8009 端口，查找 /v1/ready 响应。
2. 如果没有找到 → 指向设置技能。
3. 如果尚未缓存，则提取示例数据。
4. 运行捆绑脚本。
5. 报告指标。

检测正在运行的后端

MS_PORT=""
for port in {8000..8009}; do
  if curl -s "http://localhost:$port/v1/ready" | grep -q '"code":0'; then
    MS_PORT=$port; break
  fi
done
[ -z "$MS_PORT" ] && { echo "No running backend. Run amc-setup-calibration-stack skill first."; exit 1; }
echo "Backend on port $MS_PORT"

查找并提取示例数据（可幂等执行）

: "${REPO_ROOT:?set REPO_ROOT to the auto-magic-calib checkout. Run amc-setup-calibration-stack Step 0b first.}"
grep -q "AutoMagicCalib" "$REPO_ROOT/README.md" 2>/dev/null && grep -q "auto-magic-calib-ms" "$REPO_ROOT/compose/ms/compose.yml" 2>/dev/null || { echo "ERROR: REPO_ROOT is not an auto-magic-calib checkout: $REPO_ROOT" >&2; exit 1; }

SAMPLE_ZIP="$REPO_ROOT/assets/sdg_08_2_sample_data_010926.zip"
[ -f "$SAMPLE_ZIP" ] || { echo "Sample zip not found at $SAMPLE_ZIP"; exit 1; }

# Cache directory next to the zip.
SAMPLE_DIR="$(dirname "$SAMPLE_ZIP")/.cache/sdg_08_2_sample_data_010926"

if [ ! -d "$SAMPLE_DIR" ]; then
  mkdir -p "$SAMPLE_DIR"
  unzip -q "$SAMPLE_ZIP" -d "$SAMPLE_DIR"
fi
ls "$SAMPLE_DIR"
# Expected (possibly inside a wrapper folder): alignment_data/  GT.zip  videos/

运行脚本

请从 amc-run-sample-calibration 技能包运行捆绑脚本，而不是从 auto-magic-calib 仓库根目录运行。如果用户直接将此技能文件夹指定给 Agent，而不是安装该技能，请将 AMC_SAMPLE_SKILL_DIR 设置为包含此 SKILL.md 的目录，或从该目录运行命令。将 REPO_ROOT 设置为 amc-setup-calibration-stack 所解析的 AutoMagicCalib 检出目录；如果未设置 BASE_URL / MS_PORT，脚本会自动检测 localhost 的 8000-8009 端口上正在运行的后端。脚本接受 BASE_URL、MS_PORT、SAMPLE_DIR 和 RUN_VGGT 覆盖项，每次运行都会创建一个新项目，在 VGGT 就绪时尝试使用它，并在最后打印 NGC 仓库数据集说明。

# REPO_ROOT must point to the auto-magic-calib checkout, not the DeepStream repo.
: "${REPO_ROOT:?set REPO_ROOT to the auto-magic-calib checkout. Run amc-setup-calibration-stack Step 0b first.}"
grep -q "AutoMagicCalib" "$REPO_ROOT/README.md" 2>/dev/null && grep -q "auto-magic-calib-ms" "$REPO_ROOT/compose/ms/compose.yml" 2>/dev/null || { echo "ERROR: REPO_ROOT is not an auto-magic-calib checkout: $REPO_ROOT" >&2; exit 1; }

# If AMC was resolved from DeepStream's tools/auto-magic-calib submodule,
# derive the DeepStream root so the unpacked repo skill can be used directly.
if [ -z "${DEEPSTREAM_REPO_ROOT:-}" ] && [ -d "$REPO_ROOT/../../skills/amc-run-sample-calibration" ]; then
  DEEPSTREAM_REPO_ROOT="$(cd "$REPO_ROOT/../.." && pwd)"
fi

SCRIPT_PATH=""
for candidate in \
  "${AMC_SAMPLE_SKILL_DIR:+$AMC_SAMPLE_SKILL_DIR/scripts/run_sample_calibration.py}" \
  "$PWD/scripts/run_sample_calibration.py" \
  "${DEEPSTREAM_REPO_ROOT:+$DEEPSTREAM_REPO_ROOT/skills/amc-run-sample-calibration/scripts/run_sample_calibration.py}" \
  "$PWD/skills/amc-run-sample-calibration/scripts/run_sample_calibration.py" \
  "$HOME/.claude/skills/amc-run-sample-calibration/scripts/run_sample_calibration.py" \
  "$HOME/.codex/skills/amc-run-sample-calibration/scripts/run_sample_calibration.py" \
  "$HOME/.cursor/skills/amc-run-sample-calibration/scripts/run_sample_calibration.py"; do
  if [ -f "$candidate" ]; then
    SCRIPT_PATH="$candidate"
    break
  fi
done

[ -n "$SCRIPT_PATH" ] || {
  echo "ERROR: could not find amc-run-sample-calibration/scripts/run_sample_calibration.py" >&2
  echo "Set AMC_SAMPLE_SKILL_DIR to the amc-run-sample-calibration skill directory, or run this block from that directory." >&2
  exit 1
}

python3 "$SCRIPT_PATH"

替代方案：Swagger UI 操作指南

Agent 快捷方式：如果用户明确要求使用 Swagger UI 操作指南（或表示“不要 Python”），则输出下表并停止——不要调用 shell 工具、读取其他章节或运行随附的 Python 脚本。

微服务在 http://<HOST_IP>:<MS_PORT>/docs 提供交互式 OpenAPI UI。如果你更喜欢手动点击操作 API：

1. 在浏览器中打开 http://<HOST_IP>:<MS_PORT>/docs。

2. 将 sdg_08_2_sample_data_010926.zip 解压到旁边的缓存目录中。

3. 按顺序执行以下端点，并将第 1 步中的 project_id 复制到后续路径中：

   #	端点	请求体 / 文件
   1	POST /v1/create_project	project_name：任意字符串
   2	POST /v1/upload_video_files/{project_id}	files：上传全部 4 个按名称排序的 videos/cam_0*.mp4
   3	POST /v1/upload_alignment/{project_id}	alignment_file：alignment_data/alignment_data.json
   4	POST /v1/upload_layout/{project_id}	layout_file：alignment_data/layout.png
   5	POST /v1/upload_gt_file/{project_id}	gt_file：GT.zip
   6	POST /v1/verify_project/{project_id}	—（预期 project_state: READY）
   7	POST /v1/calibrate/{project_id}	JSON：{"detector_type": "resnet"}
   8	GET /v1/get_project_info/{project_id}	每约 10 s 刷新一次，直到 project_state = COMPLETED
   9	GET /v1/result/{project_id}/evaluation_statistics	查看 L2 距离和重投影误差
   10 可选	POST /v1/vggt/calibrate/{project_id}，然后调用 GET /v1/vggt_results/{project_id}/evaluation_statistics	仅当 vggt_state 为 READY 时运行；轮询 vggt_state 直到 COMPLETED

随附的 Python 脚本执行的也是同一套流程，只是这里改为手动操作。默认情况下，如果 vggt_state 为 READY，会尝试执行第 10 步；否则会跳过并提供设置指引。

get_project_info 中的状态字段

project_info.project_state 是项目的 AMC 校准生命周期状态。轮询此字段，直到其变为 COMPLETED（或在出现 ERROR 时停止）。

project_info.vggt_state 是每个项目独立的 VGGT 优化生命周期状态，属于项目级状态，而非直接反映全局服务或模型加载状态。即使 VGGT 模型已存在并挂载，新建项目也可能报告 vggt_state: "INIT"。预期生命周期为：AMC 校准完成后，从 INIT 变为 READY → VGGT 优化运行期间为 RUNNING → 最终变为 COMPLETED（或 ERROR）。对于新建或尚未校准的项目，INIT 属于正常项目状态。如果 AMC 校准已完成，但项目的 VGGT 状态仍未就绪，请通过设置技能检查和服务日志确认 VGGT 配置及模型可用性。

成功标准

• 项目在约 30 min 内达到 project_state == "COMPLETED"。
• /v1/result/{id}/evaluation_statistics 返回非空的 statistics（已上传 GT）。
• VGGT 成功运行至 vggt_state == "COMPLETED"，并报告 /v1/vggt_results/{id}/evaluation_statistics；或者因项目尚未达到 VGGT 的 READY 状态而跳过，并提供设置指引。
• 未遇到 ERROR 状态。

该样本的代表性指标（你的结果应与此类似）：

Average L2 distance(m)               : < 1.5
Average reprojection error 0(px)     : < 10

关键输出文件（位于服务器上）

结果保存在 $REPO_ROOT/projects/project_<project_id>/ 下：

projects/project_<project_id>/
├── output/
│   ├── single_view_results/cam_XX/
│   │   ├── camInfo_hyper_XX.yaml
│   │   └── trajDump_Stream_0_3d.txt
│   └── multi_view_results/BA_output/results_ba/refined/
│       └── camInfo_XX.yaml          # ← final calibration (use this)
└── calibration.log

监控进度

PROJECT_ID=<id_from_step_1>
: "${REPO_ROOT:?set REPO_ROOT to the auto-magic-calib checkout. Run amc-setup-calibration-stack Step 0b first.}"
grep -q "AutoMagicCalib" "$REPO_ROOT/README.md" 2>/dev/null && grep -q "auto-magic-calib-ms" "$REPO_ROOT/compose/ms/compose.yml" 2>/dev/null || { echo "ERROR: REPO_ROOT is not an auto-magic-calib checkout: $REPO_ROOT" >&2; exit 1; }
tail -F --retry "$REPO_ROOT/projects/project_${PROJECT_ID}/calibration.log"

或者实时查看 MS 日志：

: "${REPO_ROOT:?set REPO_ROOT to the auto-magic-calib checkout. Run amc-setup-calibration-stack Step 0b first.}"
grep -q "AutoMagicCalib" "$REPO_ROOT/README.md" 2>/dev/null && grep -q "auto-magic-calib-ms" "$REPO_ROOT/compose/ms/compose.yml" 2>/dev/null || { echo "ERROR: REPO_ROOT is not an auto-magic-calib checkout: $REPO_ROOT" >&2; exit 1; }
docker compose -f "$REPO_ROOT/compose/compose.yml" logs -f auto-magic-calib-ms

故障排除

问题	解决方法
未安装 requests	运行脚本前先安装：python3 -m pip install requests
[2] Uploaded N videos 中 N >> 4	SAMPLE_DIR 指向了仓库根目录（或其他范围过大的路径），而 rglob("cam_*.mp4") 扫描到了 .cache/、projects/ 等目录中的旧视频。请修正 SAMPLE_DIR，然后启动一个新项目，不要尝试挽救错误的视频上传集。脚本以 videos/ 为基准，并断言 len(videos) <= 16，以便在出现问题时立即报错
verify_project 返回的状态 != READY	确认已上传全部 4 个视频、对齐数据、布局和 GT；检查 GET /v1/get_project_info/{id} 的响应
未提取样本	unzip <repo_root>/assets/sdg_08_2_sample_data_010926.zip -d <repo_root>/assets/.cache/sdg_08_2_sample_data_010926/
cam_*.mp4 glob 未找到任何文件	检查包装文件夹的层级：find <sample_dir> -name "cam_*.mp4"
校准超时（>60 min）	检查 calibration.log 中是否有 "insufficient tracklets"；查看根目录 README.md 中有关输入视频的指南
上传返回 413	提高服务端上传限制，或拆分文件（样本文件总大小不到 200 MB，因此这种情况并不常见）
端口扫描未找到后端	后端未运行——运行 amc-setup-calibration-stack 技能

其他样本数据集

根目录 README.md 还介绍了 nv_warehouse_032326.zip，这是一个可从 NGC 获取的真实仓库数据集。使用 ngc registry resource download-version "nvidia/amc-nv-warehouse" 下载；然后使用 amc-run-video-calibration，在配置步骤中上传 nv_warehouse_config.json，并使用 transformer 检测器运行。该数据集不包含真实标注数据。

相关技能

• skills/amc-setup-calibration-stack/SKILL.md — 启动 MS + UI（前置条件）。
• skills/amc-run-video-calibration/SKILL.md — 使用你自己的预录制 MP4 文件运行校准。
• skills/amc-run-rtsp-calibration/SKILL.md — 通过 VIOS 采集，从实时 RTSP 流运行校准。

根目录 README.md 中的“Sample Data Setup”和“Calibration Workflow (UI)”部分介绍了通过同一份样本完成该流程的面向用户操作路径。