{"record":{"id":"b722f466ce6152d8","repo":"ultralytics/ultralytics","slug":"please-use-the-corresponding-methods-in-sam2videop","errorCode":null,"errorMessage":"Please use the corresponding methods in SAM2VideoPredictor for inference.See notebooks/video_predictor_example.ipynb for an example.","messagePattern":"Please use the corresponding methods in SAM2VideoPredictor for inference\\.See notebooks/video_predictor_example\\.ipynb for an example\\.","errorType":"exception","errorClass":"NotImplementedError","httpStatus":null,"severity":"error","filePath":"ultralytics/models/sam/modules/sam.py","lineNumber":352,"sourceCode":"        # Model compilation\n        if compile_image_encoder:\n            # Compile the forward function (not the full module) to allow loading checkpoints.\n            LOGGER.info(\"Image encoder compilation is enabled. First forward pass will be slow.\")\n            self.image_encoder.forward = torch.compile(\n                self.image_encoder.forward,\n                mode=\"max-autotune\",\n                fullgraph=True,\n                dynamic=False,\n            )\n\n    @property\n    def device(self):\n        \"\"\"Return the device on which the model's parameters are stored.\"\"\"\n        return next(self.parameters()).device\n\n    def forward(self, *args, **kwargs):\n        \"\"\"Process image and prompt inputs to generate object masks and scores in video sequences.\"\"\"\n        raise NotImplementedError(\n            \"Please use the corresponding methods in SAM2VideoPredictor for inference.\"\n            \"See notebooks/video_predictor_example.ipynb for an example.\"\n        )\n\n    def _build_sam_heads(self):\n        \"\"\"Build SAM-style prompt encoder and mask decoder for image segmentation tasks.\"\"\"\n        self.sam_prompt_embed_dim = self.hidden_dim\n        self.sam_image_embedding_size = self.image_size // self.backbone_stride\n\n        # Build PromptEncoder and MaskDecoder from SAM (hyperparameters like `mask_in_chans=16` are from SAM code)\n        self.sam_prompt_encoder = PromptEncoder(\n            embed_dim=self.sam_prompt_embed_dim,\n            image_embedding_size=(\n                self.sam_image_embedding_size,\n                self.sam_image_embedding_size,\n            ),\n            input_image_size=(self.image_size, self.image_size),\n            mask_in_chans=16,","sourceCodeStart":334,"sourceCodeEnd":370,"githubUrl":"https://github.com/ultralytics/ultralytics/blob/0449ea011cfd6c9a0d50a0bf1043aca5190cd476/ultralytics/models/sam/modules/sam.py#L334-L370","documentation":"NotImplementedError from SAM2VideoPredictor.forward(): video segmentation models in the SAM2 family do not support plain tensor forward passes — video inference is stateful (per-frame memory, per-object prompts, propagation), so __call__/forward is intentionally disabled and the message directs users to the dedicated streaming API (init_state, add_new_points_or_box, propagate_in_video) shown in the official video predictor notebook.","triggerScenarios":"Calling model(frames_tensor) or model(image, prompts) directly on a SAM2VideoPredictor instance — e.g. reusing generic inference code that treats every ultralytics model as callable.","commonSituations":"Plugging a SAM2 video model into code written for image models; wrapper frameworks that abstract inference as forward(); copy-pasting image-SAM usage onto the video predictor.","solutions":["Use the stateful API: state = predictor.init_state(video_path); predictor.add_new_points_or_box(state, frame_idx=0, obj_id=1, points=..., labels=...); then iterate predictor.propagate_in_video(state).","For single images, use the image predictor (SAM/SAM2 image model) instead of the video predictor.","In the ultralytics facade, use model(source=video_path) track/predict paths which drive these methods internally rather than raw forward."],"exampleFix":"# before\nout = sam2_video_predictor(frame_tensor, points)  # NotImplementedError\n\n# after\nstate = sam2_video_predictor.init_state(\"video.mp4\")\nsam2_video_predictor.add_new_points_or_box(state, frame_idx=0, obj_id=1, points=np.array([[500, 375]]), labels=np.array([1]))\nfor out_frame_idx, out_obj_ids, out_mask_logits in sam2_video_predictor.propagate_in_video(state):\n    ...","handlingStrategy":"type-guard","validationCode":"from ultralytics.models.sam.modules.sam import SAM2VideoPredictor\n\ndef is_video_predictor(predictor) -> bool:\n    return isinstance(predictor, SAM2VideoPredictor)\n\nif is_video_predictor(model):\n    raise TypeError(\"video predictors need the stateful API, not forward()\")","typeGuard":"from ultralytics.models.sam.modules.sam import SAM2VideoPredictor\n\ndef uses_stateful_api(model) -> bool:\n    \"\"\"True for models that must be driven via init_state/add_prompts/propagate.\"\"\"\n    return isinstance(model, SAM2VideoPredictor)","tryCatchPattern":null,"preventionTips":["Never call SAM2VideoPredictor instances as functions; route them through init_state + add_new_points_or_box + propagate_in_video.","Keep separate code paths for image SAM (callable) and video SAM2 (stateful).","Reference the SAM2 video_predictor notebook for the canonical interaction order."],"tags":["sam","sam2","video","api-misuse","not-implemented"],"backgroundTag":null,"analyzedSha":"0449ea011cfd6c9a0d50a0bf1043aca5190cd476","analyzedAt":"2026-08-15T02:34:13.413Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}