[zhenshanx-nv]

Background

families/sam3 builds facebook/sam3 (text-prompted segmentation) as a bundle of TensorRT plans: CLIP text encoder, ViT-L vision plan, detector core and video tracker plans, batch 1, fp32 only (fp16 islands in the vision and core plans). No FP8 or NVFP4 checkpoint of SAM3 exists, so FP8 self-quantization (build-time FP8 weights, ModelOpt-calibrated static activation scales) was built and measured on TensorRT 11.4 (B200, B300) and 11.1. FP8 does not pay for this family: only the text encoder keeps the mask quality, and it is about 8% of a request, so a request is 1.02x faster (text encoder 1.4x, bundle 31% smaller); a plain fp16 text plan is faster than the FP8 one. FP8 of the vision plan, where the time is, lowers mask IoU against PyTorch from 0.9975 to 0.96 for at most 1.11x. This change adds a README for the family that records the study, like the sam (#1986) and yolov10 (#2093) studies, so that it does not have to be repeated. The FP8 code is not part of this change.

Exit Criteria

• The README records the recipe, the method, request and text encoder speed on B200 and B300 (TensorRT 11.4) and B300 (11.1), plan and bundle size, mask quality against PyTorch fp32 with the default bundle as floor, the vision plan ablation, why there is no gain, NVFP4, a TensorRT build note, what was not tried and when to revisit.
• No code, test, manifest or bundle change; builds are unchanged.
• Non-goals: shipping FP8 or NVFP4 builds, an FP8 manifest or CI case.

Implementation

• families/sam3/README.md (new): a short family description and the section "FP8 quantization study (not shipped)": summary and decision, recipe, method, results (speed, size, quality, kernels, vision ablation), why there is no gain, NVFP4, TensorRT note, what was not tried, when to revisit.

Recipe that was measured (code kept out of the repository):

• FP8 for q, k, v, out_proj, fc1 and fc2 of the 24 text encoder blocks (96 modules); embeddings, norms, attention matmuls, text_projection, the vision plan, the core and the tracker plans unchanged.
• Weights: per-tensor scale amax / 448 at build time. Activations: static per-tensor scales from ModelOpt FP8_DEFAULT_CFG (max) on the PyTorch text encoder with 304 prompts. fp16 Dequantize inside the fp32 text plan.

Why no gain: the text encoder is about 8% of a request (a free text encoder would give at most 1.08x), it is launch bound at 32 tokens, and fp16 alone (0.77 to 0.81 ms) beats FP8 (0.91 to 1.01 ms). The vision plan does not hold mask quality in FP8 with any subset of projections.

Change categories

• Model or runtime behavior
• Public API
• ABI
• Bundle or artifact format
• Dependencies
• Documentation only
• CI or developer tooling

Validation

Commands and Results

python3 -m tools.model_ci validate
python3 -m pytest tools/tests/test_architecture.py tools/tests/test_public_source_hygiene.py -q
python3 tools/pr_metadata.py validate --event <event.json>   # Pull-request metadata is complete.
git diff --check

Documentation only.

Check	Result
python3 -m tools.model_ci validate	pass
pytest tools/tests/test_architecture.py tools/tests/test_public_source_hygiene.py (CPU)	62 passed
Markdown check of the README (table column counts)	pass
git diff --check	pass
python3 tools/pr_metadata.py validate on this description	pass

The numbers in the README come from the local study and are not re-run by this change (batch 1, request = text + vision + core in one CUDA graph, median of 9 interleaved rounds; x is default time over FP8 time):

GPU	TensorRT	request default ms	request FP8 ms	x	text default / FP8 / fp16 control ms	mask IoU vs PyTorch default / FP8
B200	11.4	18.601	18.215	1.02	1.385 / 1.005 / 0.806	0.9992 / 0.9981
B300	11.4	17.118	16.759	1.02	1.314 / 0.932 / 0.767	0.9975 / 0.9973
B300	11.1	17.181	16.735	1.03	1.352 / 0.913 / 0.786	0.9988 / 0.9987

Text plan 1348.7 to 485.5 MiB, bundle 2769.3 to 1905.9 MiB (-31%). 361 held-out prompt and image pairs (100 COCO validation images); no NaN or Inf in any build, on 304 prompts plus the held-out phrases through the text plan, or on five stress images. Vision plan FP8 (B300, 11.4): 1.11x for that plan, mask IoU 0.9606 against 0.9975.

Hardware, Environment, and Revisions

• Repository: this commit on top of upstream/main at 5801406c. The sam3 family code is unchanged since the study code base.
• Checkpoint: facebook/sam3 at 3c879f39826c281e95690f02c7821c4de09afae7 (manifest revision).
• Data: detection-datasets/coco validation, 400 images at a fixed stride; 100 held-out images for evaluation; calibration used text prompts only.
• Study: B200 and B300, one GPU per job, all variants built and timed in that job; TensorRT 11.4.0.106 (target) and 11.1.0.106, torch 2.14.0 (CUDA 13), Transformers 5.17.0, ModelOpt 0.46.1. Reference: PyTorch fp32 Sam3Model. The vision ablation and NVFP4 numbers come from an earlier B300 run on the same family code.

Not Run / Remaining Gaps

• No code was run for this change; the study cannot be rerun from this repository because the FP8 code was not merged.
• Not measured: percentile or entropy calibration and per-channel weights for the vision plan, batch greater than 1, the tracker plans, H100, the native runtime with an FP8 bundle, other SAM3 checkpoints, a segmentation benchmark against ground truth.
• No problem on main was found. A TensorRT 11.4 build failure of a scratch FP8 text graph in fp16 (FP8 Quantize after the fused attention) is recorded in the README; it does not affect the family's builds.

Contributor Self-Review

• I have completed a self-review of this change.

Notes For Future Readers

• Suggested review order: "Summary and decision", "Why there is no gain", "When to revisit".
• Revisit FP8 when the family gets an fp16 text or vision plan (FP8 must then beat those), or when a recipe keeps the vision plan at the mask-quality floor with a clear speedup.

Risk level

• Low
• Medium
• High

Risk rationale: documentation only; one README added, no code, build, bundle or test change.

🤖 Generated with Claude Code

[coderabbitai]

Warning

Review limit reached

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.

Next included review available in 24 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used all 12 included reviews currently available.

Learn how review limits work.

Review configuration:

Run configuration

• Source mode: Auto
• Repository: NVIDIA/TensorRT-Model-Connect
• Branch: main
• File: .coderabbit.yaml
• Commit: 5801406
• Layers: Repository YAML
• Review profile: CHILL
• Plan: Enterprise
• Run ID: d60e9a7f-0252-486a-9f6b-92d2118d2162

Commits

Reviewing files that changed from the base of the PR and between 5801406 and 517c913.

Files selected for processing: 1

• families/sam3/README.md