← HOT3D 提交说明 · Test40 提交说明 · OpenAPI JSON · 纯文本 Markdown

Agent 提交与结果查询 API

将模型预测 ZIP 提交到 Benchmark，异步获取评测结果。本接口负责评测已有预测；视频上传与 Pipeline 推理使用 Playground 的独立接口。

当前规范 · 选择评测方式 · 准备 ZIP · 上传与预检查 · 完整请求示例 · 模型与 Pipeline · 提交与重试 · 结果解释 · Python 流程 · 升级与错误

OpenAPI JSON · 展开当前版本的 Markdown · HOT3D 逐帧格式 · Test40 逐帧格式

1. 先确认目标和当前规范

服务地址使用你实际获授权的实例 origin。本文路径均相对该 origin；以下 curl 示例需要 curl 与 jq，并假定已经设置 EGO_URL。开发者先从本人 checkout 执行 ./deploy/run-dev target --service benchmark，核对 /api/health 的 service=benchmark、environment、instance_id、build；生产提交按实际使用授权执行。当前接口没有应用层登录，幂等键与同源检查不构成身份认证。

# 以下命令在同一个 Bash 会话执行；失败时停止，先修正问题。
set -eu
# EGO_URL 为你确认的服务地址，不包含末尾斜杠。
curl --fail-with-body -sS "$EGO_URL/api/health"
curl --fail-with-body -sS "$EGO_URL/api/hot3d/protocols" > protocols.json
jq '.versions[] | {protocol_id, ready, accepting_submissions}' protocols.json

从 versions[].protocol_id 选择题集，再请求 /api/submission-contract?protocol=...。不要依赖默认协议或永久固定当前的题集列表。每次准备新提交都刷新规范；使用同键恢复已经接收的请求时保留原 JSON，不擅自替换字段。

以下身份和后面的完整请求示例由服务的 submission_contract 定义生成，HTML、Markdown、OpenAPI 使用同一来源，随发布版本更新。它们说明当前接受什么格式；实时 ready / accepting_submissions 仍需查询规范接口，页面展示不代表当前允许提交。

题集	当前 split_id	ZIP schema_version	Case 数	每个 Case 的帧数
HOT3D	`test200-v3`	`hot3d-pose-prediction-v4`	1–200	150
Test40	`test40-v1`	`reinterhand-pose-prediction-v1`	1–40	按原始 inputs.json 的完整 frame_count

HOT3D 当前身份

{
  "protocol": "local-hot3d-quest3-mano21-pose-v1",
  "dataset_id": "hot3d-quest3-mano21-test200-v3",
  "split_id": "test200-v3",
  "schema_version": "hot3d-pose-prediction-v4",
  "input_manifest_sha256": "b3a405063e0158b47fa19c3ad4bf0acdd65785a0e9acb36f6d045412e3cbf1ef",
  "contract_id": "294efdf809b02422087de511f0900063fb2c7abcab403f3dcd14b846b6b020e6"
}

实时规范 · 输入包索引 · 提交工具 · 坐标与逐帧格式

Test40 当前身份

{
  "protocol": "reinterhand-ego-mano21-pose-v1",
  "dataset_id": "reinterhand-ego-envmap-per-segment-mano21-test40-v1",
  "split_id": "test40-v1",
  "schema_version": "reinterhand-pose-prediction-v1",
  "input_manifest_sha256": "66546c045e09a197322aae3388822aa56faf9af6c4eec8b37d871320baad4e2b",
  "contract_id": "3ecb48a0d8f2c2013efac41fb51550b7d15e9982eb202e8e1573246e4703ffe7"
}

实时规范 · 输入包索引 · 提交工具 · 坐标与逐帧格式

需要区分四个值：protocol 是评测协议；split_id / dataset_id 是冻结题集身份；schema_version 是 ZIP 中 submission.json 的格式；下载包文件名的 vN 是交付版本。它们不要求使用相同版本号。contract_id 绑定当前提交要求，提交前以实时接口返回为准。

2. 选择评测方式

HTTP 的 evaluation_profile 描述预测类型和实际使用的输入相机。它必须与 ZIP 中 prediction_type、inference_camera_ids 一致；更改请求 JSON 不会将已有 3D ZIP 转成 2D，也不会将单目结果变成双目。不能把没有参与推理的相机填进去。

场景 / 完整请求	prediction_type	inference_camera_ids
HOT3D · 左目 3D · 1201-1	`3d`	`["1201-1"]`
HOT3D · 右目 3D · 1201-2	`3d`	`["1201-2"]`
HOT3D · 双目 3D · 1201-1 + 1201-2	`3d`	`["1201-1", "1201-2"]`
HOT3D · 左目 2D · 1201-1	`2d`	`["1201-1"]`
HOT3D · 右目 2D · 1201-2	`2d`	`["1201-2"]`
HOT3D · 双目 2D · 1201-1 + 1201-2	`2d`	`["1201-1", "1201-2"]`
Test40 · Ego 单目 3D · ego	`3d`	`["ego"]`
Test40 · Ego 单目 2D · ego	`2d`	`["ego"]`

坐标和评分范围

• HOT3D 3D：无论左目、右目还是双目推理，输出都统一到左相机 camera:1201-1:native，单位米。右目模型的输出需要先按题集标定转换，不能直接当作右相机坐标提交。

• HOT3D 2D：所选相机的扶正原图像素，坐标声明 upright、单位 px；当前原图 1024×1280。双目要分别提交两路视图，不是把两路点拼在一起。

• Test40：仅 ego。3D 为 camera:ego:native / 米；2D 为 image:ego:native / px，当前原图 1024×1024。相机和每帧标定以输入包为准，不能套用 HOT3D 的旋转或帧数。

• 3D 提交计算空间指标，并由平台按标定投影计算 2D 指标；纯 2D 提交计算 2D 及公共指标，不补造 3D 分数。详见结果解释。

• expected_count 是 ZIP 里实际选择的 Case 数，不是采样帧数，也不表示让服务器截取前 N 个。子集在打包前用 Case ID 选择；每个 Case 仍需完整帧序列。

• leaderboard_type 独立取 formal 或 temporary，默认 temporary。正式榜也允许合法子集，不按 Case 数自动决定榜单；不同题集、Case 集和评测设置不混排名。

3. 准备当前题集的预测 ZIP

从规范响应的 links.input_package 获取输入包索引 JSON，再读取 downloads.full.url（完整输入）或 downloads.starter.url（工具包）。该接口本身不是 ZIP。包下载后保留原始 inputs.json 的字节；不要裁切或重写它，也不要用 /api/hot3d/inputs?case_id=... 的展示响应代替原清单。

# EGO_PROTOCOL 从上一步 versions[].protocol_id 中选择。
curl --fail-with-body -sS --get "$EGO_URL/api/submission-contract" \
  --data-urlencode "protocol=$EGO_PROTOCOL" > contract.json
jq -e '.ready and .accepting_submissions' contract.json
curl --fail-with-body -sS "$EGO_URL$(jq -r '.links.input_package' contract.json)" > package.json
jq '{ready, downloads}' package.json
# 确认需要下载完整包后执行；可能为数十 GB。
curl --fail-with-body -L "$EGO_URL$(jq -r '.downloads.full.url' package.json)" -o inputs.zip
# 使用当前服务的工具，不沿用旧下载包里可能过期的脚本。
curl --fail-with-body -sS "$EGO_URL$(jq -r '.links.submission_tool' contract.json)" -o submission_tool.py

解压 inputs.zip，在模型侧使用原始视频/图像与相机参数完成推理。两个题集的提交工具都有 template、verify、pack 三个命令。下面示例分别创建 HOT3D 左目 3D 和 Test40 Ego 2D 模板；运行前下载对应协议的工具，设置原始清单路径 INPUTS 和真实 CASE_ID。两个模板示例任选其一。

# HOT3D：一个 Case，左目 3D。
python submission_tool.py template --inputs "$INPUTS" --submission prediction-hot3d \
  --type 3d --cameras 1201-1 --case-id "$CASE_ID"
# Test40：一个 Case，Ego 2D；此时 submission_tool.py 必须是 Test40 工具。
python submission_tool.py template --inputs "$INPUTS" --submission prediction-test40 \
  --type 2d --cameras ego --case-id "$CASE_ID"

--case-id 可重复传入；省略选择全题集。新模板目录必须不存在。将模型预测填入 JSONL，填写实际 prediction_adapter_id 和 pipeline_version，保留输入身份及 joint_names 语义映射。随后选择对应目录验证和打包：

python submission_tool.py verify --inputs "$INPUTS" --submission "$PREDICTION_DIR"
# 仅当已经填入真实模型输出时使用 --model-output；目标 ZIP 必须不存在。
python submission_tool.py pack --inputs "$INPUTS" --submission "$PREDICTION_DIR" \
  --output prediction.zip --model-output

模板默认是 gt_derived_fixture，不能把空模板或 GT 衍生联调数据标成 model_output。fixture 只在历史区展示，不能提交正式榜；真实模型输出可按用途选择正式或临时榜。

prediction.zip
├── submission.json
└── predictions/
    ├── <case_id_1>.jsonl
    └── <case_id_2>.jsonl

允许唯一一层外目录。不要将 inputs.json、GT、原视频或其他文件混装进预测 ZIP。

• submission.json 保存 schema_version、protocol_id、dataset_id、input_manifest_sha256、case_ids、joint_names、prediction_type、inference_camera_ids、coordinate_frame、unit 等；由当前工具生成，Test40 还声明 split_id。这里的 protocol_id 对应 HTTP 请求的 protocol。

• 3D 每帧直接包含左右手及 points_3d；2D 每帧在 views 下按声明的相机分别包含左右手及 points_2d。每只有效手必须是 21 个有限数值点；3D 不混入 2D 字段，2D 不混入 3D 字段。

• 缺失手显式写 status: "missing" 和对应点字段 null，保留该帧及双手字段。不能因未检测到手就删帧。HOT3D 为逐 Case 完整 150 帧；Test40 按清单的实际 frame_count，不能统一裁成 150 帧。

4. 上传与预检查

POST /api/uploads?filename=prediction.zip 的正文为 ZIP 原始二进制，不是 multipart、Base64 或 JSON。单包 1 byte–2 GiB，准确 Content-Length，不支持 chunked。下面 curl 从文件上传，无需将整个包读进 Python 内存。

curl --fail-with-body -sS -H 'Content-Type: application/zip' \
  --data-binary @prediction.zip "$EGO_URL/api/uploads?filename=prediction.zip" > upload.json
jq '{upload_id, filename, size_bytes}' upload.json

HTTP 201 返回 upload_id、filename、size_bytes、sha256。上传成功只代表保存完成；Agent 使用 upload_id，不依赖响应里的内部 archive_path，也不直接访问服务存储路径。

从下一节选取与 ZIP 对应的完整请求，保存为 submit.json，将占位 upload_id 替换为真实返回值。确认已按当前输入准备后，填写最新 contract_id，不要通过改 split_id / schema_version 强行升级旧预测。

# submit.json 已选对题集、类型、相机、Case 数和模型字段。
jq --arg upload_id "$(jq -r '.upload_id' upload.json)" \
   --arg contract_id "$(jq -r '.contract_id' contract.json)" \
   '.upload_id=$upload_id | .contract_id=$contract_id' submit.json > request.json
curl --fail-with-body -sS -H 'Content-Type: application/json' \
  --data-binary @request.json "$EGO_URL/api/hot3d/inspect" > inspect.json
jq '{selection, evaluation_profile, fixture, contract_id}' inspect.json

两套题集共用 /api/hot3d/inspect，按 protocol / split_id 分派。此接口只需题集、来源、expected_count、contract_id、evaluation_profile；可以发送完整请求，但这里不验证全部模型/Pipeline catalog 字段。HTTP 200 返回选择集、实际 profile、fixture、当前 contract_id 和冻结身份。预检查不等于逐帧评分成功，入队与 worker 会继续校验。

5. 不同评测的完整请求示例

以下 JSON 均用于 POST /api/evaluations，最大正文 1 MiB，Content-Type 为 application/json；成功 HTTP 202。所有示例默认创建模型版本、未选择业务 Pipeline。upload_id 是占位值，模型名称/版本说明请按实际填写；contract_id 仅代表此页面渲染时的版本，提交前刷新实时规范。

示例分别展示全题集正式榜和单 Case 临时榜，两者均可按实际需求调整。expected_count 必须与对应 ZIP 完全一致。evaluation_profile 本身可省略并从 ZIP 读取；Agent 显式提供时更易审计，但必须与 ZIP 一致。坐标和 schema_version 属于 ZIP 元数据，不是可通过此请求覆盖的参数。