跳至内容

参考资料 ultralytics/engine/model.py

备注

该文件可在https://github.com/ultralytics/ultralytics/blob/main/ ultralytics/engine/model .py。如果您发现问题,请通过提交 Pull Request🛠️ 帮助修复。谢谢🙏!



ultralytics.engine.model.Model

垒球 Module

基类,用于实现YOLO 模型,统一不同模型类型的应用程序接口。

该类为与YOLO 模型相关的各种操作(如训练、验证、预测、导出和基准测试)提供了一个通用接口、 验证、预测、输出和基准测试。它可处理不同类型的模型,包括从本地文件、 它可处理不同类型的模型,包括从本地文件、Ultralytics HUB 或Triton 服务器加载的模型。该类设计灵活,可 可针对不同任务和模型配置进行扩展。

参数

名称 类型 说明 默认值
model Union[str, Path]

要加载或创建的模型的路径或名称。这可以是本地文件 路径、Ultralytics HUB 中的模型名称或Triton 服务器模型。默认为 "yolov8n.pt"。

'yolov8n.pt'
task Any

与YOLO 模型相关的任务类型。可用于指定模型的 应用领域,如对象检测、分割等。默认为 "无"。

None
verbose bool

如果为 "true",则在模型运行过程中启用冗长输出。默认为 "假"。

False

属性

名称 类型 说明
callbacks dict

模型运行过程中各种事件的回调函数字典。

predictor BasePredictor

用于进行预测的预测对象。

model Module

PyTorch 。

trainer BaseTrainer

用于训练模型的训练器对象。

ckpt dict

如果模型是从 *.pt 文件加载的,则为检查点数据。

cfg str

从 *.yaml 文件加载的模型配置。

ckpt_path str

检查点文件的路径。

overrides dict

模型配置的重载字典。

metrics dict

最新的培训/验证指标。

session HUBTrainingSession

Ultralytics HUB 会议(如适用)。

task str

模型的任务类型。

model_name str

模型的名称。

方法

名称 说明
__call__

预测方法的别名,使模型实例可被调用。

_new

根据配置文件初始化一个新模型。

_load

从检查点文件加载模型。

_check_is_pytorch_model

确保模型是PyTorch 模型。

reset_weights

将模型权重重置为初始状态。

load

从指定文件加载模型权重。

save

将模型的当前状态保存到文件中。

info

记录或返回有关模型的信息。

fuse

融合 Conv2d 和 BatchNorm2d 层,优化推理。

predict

执行物体检测预测。

track

执行物体跟踪。

val

在数据集上验证模型。

benchmark

在各种输出格式上对模型进行基准测试。

export

将模型导出为不同格式。

train

在数据集上训练模型。

tune

执行超参数调整。

_apply

对模型的张量应用一个函数。

add_callback

为事件添加回调函数。

clear_callback

清除事件的所有回调。

reset_callbacks

将所有回调重置为默认函数。

_get_hub_session

检索或创建Ultralytics HUB 会话。

is_triton_model

检查模型是否是Triton Server 模型。

is_hub_model

检查模型是否是Ultralytics HUB 模型。

_reset_ckpt_args

加载PyTorch 模型时重置检查点参数。

_smart_load

根据模型任务加载相应模块。

task_map

提供从模型任务到相应类的映射。

加薪:

类型 说明
FileNotFoundError

如果指定的模型文件不存在或无法访问。

ValueError

如果模型文件或配置无效或不支持。

ImportError

如果未安装特定模型类型(如HUB SDK)所需的依赖项。

TypeError

如果模型在需要时不是PyTorch 模型。

AttributeError

如果所需的属性或方法未实施或不可用。

NotImplementedError

如果不支持特定型号任务或模式。

源代码 ultralytics/engine/model.py
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
class Model(nn.Module):
    """
    A base class for implementing YOLO models, unifying APIs across different model types.

    This class provides a common interface for various operations related to YOLO models, such as training,
    validation, prediction, exporting, and benchmarking. It handles different types of models, including those
    loaded from local files, Ultralytics HUB, or Triton Server. The class is designed to be flexible and
    extendable for different tasks and model configurations.

    Args:
        model (Union[str, Path], optional): Path or name of the model to load or create. This can be a local file
            path, a model name from Ultralytics HUB, or a Triton Server model. Defaults to 'yolov8n.pt'.
        task (Any, optional): The task type associated with the YOLO model. This can be used to specify the model's
            application domain, such as object detection, segmentation, etc. Defaults to None.
        verbose (bool, optional): If True, enables verbose output during the model's operations. Defaults to False.

    Attributes:
        callbacks (dict): A dictionary of callback functions for various events during model operations.
        predictor (BasePredictor): The predictor object used for making predictions.
        model (nn.Module): The underlying PyTorch model.
        trainer (BaseTrainer): The trainer object used for training the model.
        ckpt (dict): The checkpoint data if the model is loaded from a *.pt file.
        cfg (str): The configuration of the model if loaded from a *.yaml file.
        ckpt_path (str): The path to the checkpoint file.
        overrides (dict): A dictionary of overrides for model configuration.
        metrics (dict): The latest training/validation metrics.
        session (HUBTrainingSession): The Ultralytics HUB session, if applicable.
        task (str): The type of task the model is intended for.
        model_name (str): The name of the model.

    Methods:
        __call__: Alias for the predict method, enabling the model instance to be callable.
        _new: Initializes a new model based on a configuration file.
        _load: Loads a model from a checkpoint file.
        _check_is_pytorch_model: Ensures that the model is a PyTorch model.
        reset_weights: Resets the model's weights to their initial state.
        load: Loads model weights from a specified file.
        save: Saves the current state of the model to a file.
        info: Logs or returns information about the model.
        fuse: Fuses Conv2d and BatchNorm2d layers for optimized inference.
        predict: Performs object detection predictions.
        track: Performs object tracking.
        val: Validates the model on a dataset.
        benchmark: Benchmarks the model on various export formats.
        export: Exports the model to different formats.
        train: Trains the model on a dataset.
        tune: Performs hyperparameter tuning.
        _apply: Applies a function to the model's tensors.
        add_callback: Adds a callback function for an event.
        clear_callback: Clears all callbacks for an event.
        reset_callbacks: Resets all callbacks to their default functions.
        _get_hub_session: Retrieves or creates an Ultralytics HUB session.
        is_triton_model: Checks if a model is a Triton Server model.
        is_hub_model: Checks if a model is an Ultralytics HUB model.
        _reset_ckpt_args: Resets checkpoint arguments when loading a PyTorch model.
        _smart_load: Loads the appropriate module based on the model task.
        task_map: Provides a mapping from model tasks to corresponding classes.

    Raises:
        FileNotFoundError: If the specified model file does not exist or is inaccessible.
        ValueError: If the model file or configuration is invalid or unsupported.
        ImportError: If required dependencies for specific model types (like HUB SDK) are not installed.
        TypeError: If the model is not a PyTorch model when required.
        AttributeError: If required attributes or methods are not implemented or available.
        NotImplementedError: If a specific model task or mode is not supported.
    """

    def __init__(
        self,
        model: Union[str, Path] = "yolov8n.pt",
        task: str = None,
        verbose: bool = False,
    ) -> None:
        """
        Initializes a new instance of the YOLO model class.

        This constructor sets up the model based on the provided model path or name. It handles various types of model
        sources, including local files, Ultralytics HUB models, and Triton Server models. The method initializes several
        important attributes of the model and prepares it for operations like training, prediction, or export.

        Args:
            model (Union[str, Path], optional): The path or model file to load or create. This can be a local
                file path, a model name from Ultralytics HUB, or a Triton Server model. Defaults to 'yolov8n.pt'.
            task (Any, optional): The task type associated with the YOLO model, specifying its application domain.
                Defaults to None.
            verbose (bool, optional): If True, enables verbose output during the model's initialization and subsequent
                operations. Defaults to False.

        Raises:
            FileNotFoundError: If the specified model file does not exist or is inaccessible.
            ValueError: If the model file or configuration is invalid or unsupported.
            ImportError: If required dependencies for specific model types (like HUB SDK) are not installed.
        """
        super().__init__()
        self.callbacks = callbacks.get_default_callbacks()
        self.predictor = None  # reuse predictor
        self.model = None  # model object
        self.trainer = None  # trainer object
        self.ckpt = None  # if loaded from *.pt
        self.cfg = None  # if loaded from *.yaml
        self.ckpt_path = None
        self.overrides = {}  # overrides for trainer object
        self.metrics = None  # validation/training metrics
        self.session = None  # HUB session
        self.task = task  # task type
        self.model_name = model = str(model).strip()  # strip spaces

        # Check if Ultralytics HUB model from https://hub.ultralytics.com
        if self.is_hub_model(model):
            # Fetch model from HUB
            checks.check_requirements("hub-sdk>0.0.2")
            self.session = self._get_hub_session(model)
            model = self.session.model_file

        # Check if Triton Server model
        elif self.is_triton_model(model):
            self.model = model
            self.task = task
            return

        # Load or create new YOLO model
        model = checks.check_model_file_from_stem(model)  # add suffix, i.e. yolov8n -> yolov8n.pt
        if Path(model).suffix in (".yaml", ".yml"):
            self._new(model, task=task, verbose=verbose)
        else:
            self._load(model, task=task)

        self.model_name = model

    def __call__(
        self,
        source: Union[str, Path, int, list, tuple, np.ndarray, torch.Tensor] = None,
        stream: bool = False,
        **kwargs,
    ) -> list:
        """
        An alias for the predict method, enabling the model instance to be callable.

        This method simplifies the process of making predictions by allowing the model instance to be called directly
        with the required arguments for prediction.

        Args:
            source (str | Path | int | PIL.Image | np.ndarray, optional): The source of the image for making
                predictions. Accepts various types, including file paths, URLs, PIL images, and numpy arrays.
                Defaults to None.
            stream (bool, optional): If True, treats the input source as a continuous stream for predictions.
                Defaults to False.
            **kwargs (dict): Additional keyword arguments for configuring the prediction process.

        Returns:
            (List[ultralytics.engine.results.Results]): A list of prediction results, encapsulated in the Results class.
        """
        return self.predict(source, stream, **kwargs)

    @staticmethod
    def _get_hub_session(model: str):
        """Creates a session for Hub Training."""
        from ultralytics.hub.session import HUBTrainingSession

        session = HUBTrainingSession(model)
        return session if session.client.authenticated else None

    @staticmethod
    def is_triton_model(model: str) -> bool:
        """Is model a Triton Server URL string, i.e. <scheme>://<netloc>/<endpoint>/<task_name>"""
        from urllib.parse import urlsplit

        url = urlsplit(model)
        return url.netloc and url.path and url.scheme in {"http", "grpc"}

    @staticmethod
    def is_hub_model(model: str) -> bool:
        """Check if the provided model is a HUB model."""
        return any(
            (
                model.startswith(f"{HUB_WEB_ROOT}/models/"),  # i.e. https://hub.ultralytics.com/models/MODEL_ID
                [len(x) for x in model.split("_")] == [42, 20],  # APIKEY_MODELID
                len(model) == 20 and not Path(model).exists() and all(x not in model for x in "./\\"),  # MODELID
            )
        )

    def _new(self, cfg: str, task=None, model=None, verbose=False) -> None:
        """
        Initializes a new model and infers the task type from the model definitions.

        Args:
            cfg (str): model configuration file
            task (str | None): model task
            model (BaseModel): Customized model.
            verbose (bool): display model info on load
        """
        cfg_dict = yaml_model_load(cfg)
        self.cfg = cfg
        self.task = task or guess_model_task(cfg_dict)
        self.model = (model or self._smart_load("model"))(cfg_dict, verbose=verbose and RANK == -1)  # build model
        self.overrides["model"] = self.cfg
        self.overrides["task"] = self.task

        # Below added to allow export from YAMLs
        self.model.args = {**DEFAULT_CFG_DICT, **self.overrides}  # combine default and model args (prefer model args)
        self.model.task = self.task

    def _load(self, weights: str, task=None) -> None:
        """
        Initializes a new model and infers the task type from the model head.

        Args:
            weights (str): model checkpoint to be loaded
            task (str | None): model task
        """
        suffix = Path(weights).suffix
        if suffix == ".pt":
            self.model, self.ckpt = attempt_load_one_weight(weights)
            self.task = self.model.args["task"]
            self.overrides = self.model.args = self._reset_ckpt_args(self.model.args)
            self.ckpt_path = self.model.pt_path
        else:
            weights = checks.check_file(weights)
            self.model, self.ckpt = weights, None
            self.task = task or guess_model_task(weights)
            self.ckpt_path = weights
        self.overrides["model"] = weights
        self.overrides["task"] = self.task

    def _check_is_pytorch_model(self) -> None:
        """Raises TypeError is model is not a PyTorch model."""
        pt_str = isinstance(self.model, (str, Path)) and Path(self.model).suffix == ".pt"
        pt_module = isinstance(self.model, nn.Module)
        if not (pt_module or pt_str):
            raise TypeError(
                f"model='{self.model}' should be a *.pt PyTorch model to run this method, but is a different format. "
                f"PyTorch models can train, val, predict and export, i.e. 'model.train(data=...)', but exported "
                f"formats like ONNX, TensorRT etc. only support 'predict' and 'val' modes, "
                f"i.e. 'yolo predict model=yolov8n.onnx'.\nTo run CUDA or MPS inference please pass the device "
                f"argument directly in your inference command, i.e. 'model.predict(source=..., device=0)'"
            )

    def reset_weights(self) -> "Model":
        """
        Resets the model parameters to randomly initialized values, effectively discarding all training information.

        This method iterates through all modules in the model and resets their parameters if they have a
        'reset_parameters' method. It also ensures that all parameters have 'requires_grad' set to True, enabling them
        to be updated during training.

        Returns:
            self (ultralytics.engine.model.Model): The instance of the class with reset weights.

        Raises:
            AssertionError: If the model is not a PyTorch model.
        """
        self._check_is_pytorch_model()
        for m in self.model.modules():
            if hasattr(m, "reset_parameters"):
                m.reset_parameters()
        for p in self.model.parameters():
            p.requires_grad = True
        return self

    def load(self, weights: Union[str, Path] = "yolov8n.pt") -> "Model":
        """
        Loads parameters from the specified weights file into the model.

        This method supports loading weights from a file or directly from a weights object. It matches parameters by
        name and shape and transfers them to the model.

        Args:
            weights (str | Path): Path to the weights file or a weights object. Defaults to 'yolov8n.pt'.

        Returns:
            self (ultralytics.engine.model.Model): The instance of the class with loaded weights.

        Raises:
            AssertionError: If the model is not a PyTorch model.
        """
        self._check_is_pytorch_model()
        if isinstance(weights, (str, Path)):
            weights, self.ckpt = attempt_load_one_weight(weights)
        self.model.load(weights)
        return self

    def save(self, filename: Union[str, Path] = "saved_model.pt") -> None:
        """
        Saves the current model state to a file.

        This method exports the model's checkpoint (ckpt) to the specified filename.

        Args:
            filename (str | Path): The name of the file to save the model to. Defaults to 'saved_model.pt'.

        Raises:
            AssertionError: If the model is not a PyTorch model.
        """
        self._check_is_pytorch_model()
        torch.save(self.ckpt, filename)

    def info(self, detailed: bool = False, verbose: bool = True):
        """
        Logs or returns model information.

        This method provides an overview or detailed information about the model, depending on the arguments passed.
        It can control the verbosity of the output.

        Args:
            detailed (bool): If True, shows detailed information about the model. Defaults to False.
            verbose (bool): If True, prints the information. If False, returns the information. Defaults to True.

        Returns:
            (list): Various types of information about the model, depending on the 'detailed' and 'verbose' parameters.

        Raises:
            AssertionError: If the model is not a PyTorch model.
        """
        self._check_is_pytorch_model()
        return self.model.info(detailed=detailed, verbose=verbose)

    def fuse(self):
        """
        Fuses Conv2d and BatchNorm2d layers in the model.

        This method optimizes the model by fusing Conv2d and BatchNorm2d layers, which can improve inference speed.

        Raises:
            AssertionError: If the model is not a PyTorch model.
        """
        self._check_is_pytorch_model()
        self.model.fuse()

    def embed(
        self,
        source: Union[str, Path, int, list, tuple, np.ndarray, torch.Tensor] = None,
        stream: bool = False,
        **kwargs,
    ) -> list:
        """
        Generates image embeddings based on the provided source.

        This method is a wrapper around the 'predict()' method, focusing on generating embeddings from an image source.
        It allows customization of the embedding process through various keyword arguments.

        Args:
            source (str | int | PIL.Image | np.ndarray): The source of the image for generating embeddings.
                The source can be a file path, URL, PIL image, numpy array, etc. Defaults to None.
            stream (bool): If True, predictions are streamed. Defaults to False.
            **kwargs (dict): Additional keyword arguments for configuring the embedding process.

        Returns:
            (List[torch.Tensor]): A list containing the image embeddings.

        Raises:
            AssertionError: If the model is not a PyTorch model.
        """
        if not kwargs.get("embed"):
            kwargs["embed"] = [len(self.model.model) - 2]  # embed second-to-last layer if no indices passed
        return self.predict(source, stream, **kwargs)

    def predict(
        self,
        source: Union[str, Path, int, list, tuple, np.ndarray, torch.Tensor] = None,
        stream: bool = False,
        predictor=None,
        **kwargs,
    ) -> list:
        """
        Performs predictions on the given image source using the YOLO model.

        This method facilitates the prediction process, allowing various configurations through keyword arguments.
        It supports predictions with custom predictors or the default predictor method. The method handles different
        types of image sources and can operate in a streaming mode. It also provides support for SAM-type models
        through 'prompts'.

        The method sets up a new predictor if not already present and updates its arguments with each call.
        It also issues a warning and uses default assets if the 'source' is not provided. The method determines if it
        is being called from the command line interface and adjusts its behavior accordingly, including setting defaults
        for confidence threshold and saving behavior.

        Args:
            source (str | int | PIL.Image | np.ndarray, optional): The source of the image for making predictions.
                Accepts various types, including file paths, URLs, PIL images, and numpy arrays. Defaults to ASSETS.
            stream (bool, optional): Treats the input source as a continuous stream for predictions. Defaults to False.
            predictor (BasePredictor, optional): An instance of a custom predictor class for making predictions.
                If None, the method uses a default predictor. Defaults to None.
            **kwargs (dict): Additional keyword arguments for configuring the prediction process. These arguments allow
                for further customization of the prediction behavior.

        Returns:
            (List[ultralytics.engine.results.Results]): A list of prediction results, encapsulated in the Results class.

        Raises:
            AttributeError: If the predictor is not properly set up.
        """
        if source is None:
            source = ASSETS
            LOGGER.warning(f"WARNING ⚠️ 'source' is missing. Using 'source={source}'.")

        is_cli = (sys.argv[0].endswith("yolo") or sys.argv[0].endswith("ultralytics")) and any(
            x in sys.argv for x in ("predict", "track", "mode=predict", "mode=track")
        )

        custom = {"conf": 0.25, "save": is_cli, "mode": "predict"}  # method defaults
        args = {**self.overrides, **custom, **kwargs}  # highest priority args on the right
        prompts = args.pop("prompts", None)  # for SAM-type models

        if not self.predictor:
            self.predictor = predictor or self._smart_load("predictor")(overrides=args, _callbacks=self.callbacks)
            self.predictor.setup_model(model=self.model, verbose=is_cli)
        else:  # only update args if predictor is already setup
            self.predictor.args = get_cfg(self.predictor.args, args)
            if "project" in args or "name" in args:
                self.predictor.save_dir = get_save_dir(self.predictor.args)
        if prompts and hasattr(self.predictor, "set_prompts"):  # for SAM-type models
            self.predictor.set_prompts(prompts)
        return self.predictor.predict_cli(source=source) if is_cli else self.predictor(source=source, stream=stream)

    def track(
        self,
        source: Union[str, Path, int, list, tuple, np.ndarray, torch.Tensor] = None,
        stream: bool = False,
        persist: bool = False,
        **kwargs,
    ) -> list:
        """
        Conducts object tracking on the specified input source using the registered trackers.

        This method performs object tracking using the model's predictors and optionally registered trackers. It is
        capable of handling different types of input sources such as file paths or video streams. The method supports
        customization of the tracking process through various keyword arguments. It registers trackers if they are not
        already present and optionally persists them based on the 'persist' flag.

        The method sets a default confidence threshold specifically for ByteTrack-based tracking, which requires low
        confidence predictions as input. The tracking mode is explicitly set in the keyword arguments.

        Args:
            source (str, optional): The input source for object tracking. It can be a file path, URL, or video stream.
            stream (bool, optional): Treats the input source as a continuous video stream. Defaults to False.
            persist (bool, optional): Persists the trackers between different calls to this method. Defaults to False.
            **kwargs (dict): Additional keyword arguments for configuring the tracking process. These arguments allow
                for further customization of the tracking behavior.

        Returns:
            (List[ultralytics.engine.results.Results]): A list of tracking results, encapsulated in the Results class.

        Raises:
            AttributeError: If the predictor does not have registered trackers.
        """
        if not hasattr(self.predictor, "trackers"):
            from ultralytics.trackers import register_tracker

            register_tracker(self, persist)
        kwargs["conf"] = kwargs.get("conf") or 0.1  # ByteTrack-based method needs low confidence predictions as input
        kwargs["mode"] = "track"
        return self.predict(source=source, stream=stream, **kwargs)

    def val(
        self,
        validator=None,
        **kwargs,
    ):
        """
        Validates the model using a specified dataset and validation configuration.

        This method facilitates the model validation process, allowing for a range of customization through various
        settings and configurations. It supports validation with a custom validator or the default validation approach.
        The method combines default configurations, method-specific defaults, and user-provided arguments to configure
        the validation process. After validation, it updates the model's metrics with the results obtained from the
        validator.

        The method supports various arguments that allow customization of the validation process. For a comprehensive
        list of all configurable options, users should refer to the 'configuration' section in the documentation.

        Args:
            validator (BaseValidator, optional): An instance of a custom validator class for validating the model. If
                None, the method uses a default validator. Defaults to None.
            **kwargs (dict): Arbitrary keyword arguments representing the validation configuration. These arguments are
                used to customize various aspects of the validation process.

        Returns:
            (dict): Validation metrics obtained from the validation process.

        Raises:
            AssertionError: If the model is not a PyTorch model.
        """
        custom = {"rect": True}  # method defaults
        args = {**self.overrides, **custom, **kwargs, "mode": "val"}  # highest priority args on the right

        validator = (validator or self._smart_load("validator"))(args=args, _callbacks=self.callbacks)
        validator(model=self.model)
        self.metrics = validator.metrics
        return validator.metrics

    def benchmark(
        self,
        **kwargs,
    ):
        """
        Benchmarks the model across various export formats to evaluate performance.

        This method assesses the model's performance in different export formats, such as ONNX, TorchScript, etc.
        It uses the 'benchmark' function from the ultralytics.utils.benchmarks module. The benchmarking is configured
        using a combination of default configuration values, model-specific arguments, method-specific defaults, and
        any additional user-provided keyword arguments.

        The method supports various arguments that allow customization of the benchmarking process, such as dataset
        choice, image size, precision modes, device selection, and verbosity. For a comprehensive list of all
        configurable options, users should refer to the 'configuration' section in the documentation.

        Args:
            **kwargs (dict): Arbitrary keyword arguments to customize the benchmarking process. These are combined with
                default configurations, model-specific arguments, and method defaults.

        Returns:
            (dict): A dictionary containing the results of the benchmarking process.

        Raises:
            AssertionError: If the model is not a PyTorch model.
        """
        self._check_is_pytorch_model()
        from ultralytics.utils.benchmarks import benchmark

        custom = {"verbose": False}  # method defaults
        args = {**DEFAULT_CFG_DICT, **self.model.args, **custom, **kwargs, "mode": "benchmark"}
        return benchmark(
            model=self,
            data=kwargs.get("data"),  # if no 'data' argument passed set data=None for default datasets
            imgsz=args["imgsz"],
            half=args["half"],
            int8=args["int8"],
            device=args["device"],
            verbose=kwargs.get("verbose"),
        )

    def export(
        self,
        **kwargs,
    ):
        """
        Exports the model to a different format suitable for deployment.

        This method facilitates the export of the model to various formats (e.g., ONNX, TorchScript) for deployment
        purposes. It uses the 'Exporter' class for the export process, combining model-specific overrides, method
        defaults, and any additional arguments provided. The combined arguments are used to configure export settings.

        The method supports a wide range of arguments to customize the export process. For a comprehensive list of all
        possible arguments, refer to the 'configuration' section in the documentation.

        Args:
            **kwargs (dict): Arbitrary keyword arguments to customize the export process. These are combined with the
                model's overrides and method defaults.

        Returns:
            (object): The exported model in the specified format, or an object related to the export process.

        Raises:
            AssertionError: If the model is not a PyTorch model.
        """
        self._check_is_pytorch_model()
        from .exporter import Exporter

        custom = {"imgsz": self.model.args["imgsz"], "batch": 1, "data": None, "verbose": False}  # method defaults
        args = {**self.overrides, **custom, **kwargs, "mode": "export"}  # highest priority args on the right
        return Exporter(overrides=args, _callbacks=self.callbacks)(model=self.model)

    def train(
        self,
        trainer=None,
        **kwargs,
    ):
        """
        Trains the model using the specified dataset and training configuration.

        This method facilitates model training with a range of customizable settings and configurations. It supports
        training with a custom trainer or the default training approach defined in the method. The method handles
        different scenarios, such as resuming training from a checkpoint, integrating with Ultralytics HUB, and
        updating model and configuration after training.

        When using Ultralytics HUB, if the session already has a loaded model, the method prioritizes HUB training
        arguments and issues a warning if local arguments are provided. It checks for pip updates and combines default
        configurations, method-specific defaults, and user-provided arguments to configure the training process. After
        training, it updates the model and its configurations, and optionally attaches metrics.

        Args:
            trainer (BaseTrainer, optional): An instance of a custom trainer class for training the model. If None, the
                method uses a default trainer. Defaults to None.
            **kwargs (dict): Arbitrary keyword arguments representing the training configuration. These arguments are
                used to customize various aspects of the training process.

        Returns:
            (dict | None): Training metrics if available and training is successful; otherwise, None.

        Raises:
            AssertionError: If the model is not a PyTorch model.
            PermissionError: If there is a permission issue with the HUB session.
            ModuleNotFoundError: If the HUB SDK is not installed.
        """
        self._check_is_pytorch_model()
        if hasattr(self.session, "model") and self.session.model.id:  # Ultralytics HUB session with loaded model
            if any(kwargs):
                LOGGER.warning("WARNING ⚠️ using HUB training arguments, ignoring local training arguments.")
            kwargs = self.session.train_args  # overwrite kwargs

        checks.check_pip_update_available()

        overrides = yaml_load(checks.check_yaml(kwargs["cfg"])) if kwargs.get("cfg") else self.overrides
        custom = {"data": DEFAULT_CFG_DICT["data"] or TASK2DATA[self.task]}  # method defaults
        args = {**overrides, **custom, **kwargs, "mode": "train"}  # highest priority args on the right
        if args.get("resume"):
            args["resume"] = self.ckpt_path

        self.trainer = (trainer or self._smart_load("trainer"))(overrides=args, _callbacks=self.callbacks)
        if not args.get("resume"):  # manually set model only if not resuming
            self.trainer.model = self.trainer.get_model(weights=self.model if self.ckpt else None, cfg=self.model.yaml)
            self.model = self.trainer.model

            if SETTINGS["hub"] is True and not self.session:
                # Create a model in HUB
                try:
                    self.session = self._get_hub_session(self.model_name)
                    if self.session:
                        self.session.create_model(args)
                        # Check model was created
                        if not getattr(self.session.model, "id", None):
                            self.session = None
                except (PermissionError, ModuleNotFoundError):
                    # Ignore PermissionError and ModuleNotFoundError which indicates hub-sdk not installed
                    pass

        self.trainer.hub_session = self.session  # attach optional HUB session
        self.trainer.train()
        # Update model and cfg after training
        if RANK in (-1, 0):
            ckpt = self.trainer.best if self.trainer.best.exists() else self.trainer.last
            self.model, _ = attempt_load_one_weight(ckpt)
            self.overrides = self.model.args
            self.metrics = getattr(self.trainer.validator, "metrics", None)  # TODO: no metrics returned by DDP
        return self.metrics

    def tune(
        self,
        use_ray=False,
        iterations=10,
        *args,
        **kwargs,
    ):
        """
        Conducts hyperparameter tuning for the model, with an option to use Ray Tune.

        This method supports two modes of hyperparameter tuning: using Ray Tune or a custom tuning method.
        When Ray Tune is enabled, it leverages the 'run_ray_tune' function from the ultralytics.utils.tuner module.
        Otherwise, it uses the internal 'Tuner' class for tuning. The method combines default, overridden, and
        custom arguments to configure the tuning process.

        Args:
            use_ray (bool): If True, uses Ray Tune for hyperparameter tuning. Defaults to False.
            iterations (int): The number of tuning iterations to perform. Defaults to 10.
            *args (list): Variable length argument list for additional arguments.
            **kwargs (dict): Arbitrary keyword arguments. These are combined with the model's overrides and defaults.

        Returns:
            (dict): A dictionary containing the results of the hyperparameter search.

        Raises:
            AssertionError: If the model is not a PyTorch model.
        """
        self._check_is_pytorch_model()
        if use_ray:
            from ultralytics.utils.tuner import run_ray_tune

            return run_ray_tune(self, max_samples=iterations, *args, **kwargs)
        else:
            from .tuner import Tuner

            custom = {}  # method defaults
            args = {**self.overrides, **custom, **kwargs, "mode": "train"}  # highest priority args on the right
            return Tuner(args=args, _callbacks=self.callbacks)(model=self, iterations=iterations)

    def _apply(self, fn) -> "Model":
        """Apply to(), cpu(), cuda(), half(), float() to model tensors that are not parameters or registered buffers."""
        self._check_is_pytorch_model()
        self = super()._apply(fn)  # noqa
        self.predictor = None  # reset predictor as device may have changed
        self.overrides["device"] = self.device  # was str(self.device) i.e. device(type='cuda', index=0) -> 'cuda:0'
        return self

    @property
    def names(self) -> list:
        """
        Retrieves the class names associated with the loaded model.

        This property returns the class names if they are defined in the model. It checks the class names for validity
        using the 'check_class_names' function from the ultralytics.nn.autobackend module.

        Returns:
            (list | None): The class names of the model if available, otherwise None.
        """
        from ultralytics.nn.autobackend import check_class_names

        return check_class_names(self.model.names) if hasattr(self.model, "names") else None

    @property
    def device(self) -> torch.device:
        """
        Retrieves the device on which the model's parameters are allocated.

        This property is used to determine whether the model's parameters are on CPU or GPU. It only applies to models
        that are instances of nn.Module.

        Returns:
            (torch.device | None): The device (CPU/GPU) of the model if it is a PyTorch model, otherwise None.
        """
        return next(self.model.parameters()).device if isinstance(self.model, nn.Module) else None

    @property
    def transforms(self):
        """
        Retrieves the transformations applied to the input data of the loaded model.

        This property returns the transformations if they are defined in the model.

        Returns:
            (object | None): The transform object of the model if available, otherwise None.
        """
        return self.model.transforms if hasattr(self.model, "transforms") else None

    def add_callback(self, event: str, func) -> None:
        """
        Adds a callback function for a specified event.

        This method allows the user to register a custom callback function that is triggered on a specific event during
        model training or inference.

        Args:
            event (str): The name of the event to attach the callback to.
            func (callable): The callback function to be registered.

        Raises:
            ValueError: If the event name is not recognized.
        """
        self.callbacks[event].append(func)

    def clear_callback(self, event: str) -> None:
        """
        Clears all callback functions registered for a specified event.

        This method removes all custom and default callback functions associated with the given event.

        Args:
            event (str): The name of the event for which to clear the callbacks.

        Raises:
            ValueError: If the event name is not recognized.
        """
        self.callbacks[event] = []

    def reset_callbacks(self) -> None:
        """
        Resets all callbacks to their default functions.

        This method reinstates the default callback functions for all events, removing any custom callbacks that were
        added previously.
        """
        for event in callbacks.default_callbacks.keys():
            self.callbacks[event] = [callbacks.default_callbacks[event][0]]

    @staticmethod
    def _reset_ckpt_args(args: dict) -> dict:
        """Reset arguments when loading a PyTorch model."""
        include = {"imgsz", "data", "task", "single_cls"}  # only remember these arguments when loading a PyTorch model
        return {k: v for k, v in args.items() if k in include}

    # def __getattr__(self, attr):
    #    """Raises error if object has no requested attribute."""
    #    name = self.__class__.__name__
    #    raise AttributeError(f"'{name}' object has no attribute '{attr}'. See valid attributes below.\n{self.__doc__}")

    def _smart_load(self, key: str):
        """Load model/trainer/validator/predictor."""
        try:
            return self.task_map[self.task][key]
        except Exception as e:
            name = self.__class__.__name__
            mode = inspect.stack()[1][3]  # get the function name.
            raise NotImplementedError(
                emojis(f"WARNING ⚠️ '{name}' model does not support '{mode}' mode for '{self.task}' task yet.")
            ) from e

    @property
    def task_map(self) -> dict:
        """
        Map head to model, trainer, validator, and predictor classes.

        Returns:
            task_map (dict): The map of model task to mode classes.
        """
        raise NotImplementedError("Please provide task map for your model!")

device: torch.device property

读取分配模型参数的设备。

此属性用于确定模型参数是在 CPU 还是 GPU 上运行。它只适用于 的实例。

返回:

类型 说明
device | None

如果是PyTorch 机型,则为该机型的设备(CPU/GPU),否则为 "无"。

names: list property

读取与加载模型相关的类名。

如果模型中定义了类名,该属性会返回类名。It checks the class names for validity 使用ultralytics.nn.autobackend 模块中的 "check_class_names "函数检查类名的有效性。

返回:

类型 说明
list | None

模型的类名(如果有),否则为 "无"。

task_map: dict property

将头部映射到模型、训练器、验证器和预测器类。

返回:

名称 类型 说明
task_map dict

模式任务到模式类别的映射。

transforms property

读取应用于加载模型输入数据的转换。

如果模型中定义了变换,该属性会返回变换。

返回:

类型 说明
object | None

模型的变换对象(如果有),否则为 "无"。

__call__(source=None, stream=False, **kwargs)

预测方法的别名,使模型实例可被调用。

该方法简化了预测过程,允许直接调用模型实例 预测所需的参数。

参数

名称 类型 说明 默认值
source str | Path | int | Image | ndarray

用于预测的图像来源 预测的图像来源。接受各种类型,包括文件路径、URL、PIL 图像和 numpy 数组。 默认为 "无"。

None
stream bool

如果为 True,则在预测时将输入源视为连续流。 默认为 "假"。

False
**kwargs dict

用于配置预测过程的附加关键字参数。

{}

返回:

类型 说明
List[Results]

预测结果列表,封装在结果类中。

源代码 ultralytics/engine/model.py
def __call__(
    self,
    source: Union[str, Path, int, list, tuple, np.ndarray, torch.Tensor] = None,
    stream: bool = False,
    **kwargs,
) -> list:
    """
    An alias for the predict method, enabling the model instance to be callable.

    This method simplifies the process of making predictions by allowing the model instance to be called directly
    with the required arguments for prediction.

    Args:
        source (str | Path | int | PIL.Image | np.ndarray, optional): The source of the image for making
            predictions. Accepts various types, including file paths, URLs, PIL images, and numpy arrays.
            Defaults to None.
        stream (bool, optional): If True, treats the input source as a continuous stream for predictions.
            Defaults to False.
        **kwargs (dict): Additional keyword arguments for configuring the prediction process.

    Returns:
        (List[ultralytics.engine.results.Results]): A list of prediction results, encapsulated in the Results class.
    """
    return self.predict(source, stream, **kwargs)

__init__(model='yolov8n.pt', task=None, verbose=False)

初始化YOLO 模型类的新实例。

此构造函数根据提供的模型路径或名称设置模型。它可处理各种类型的模型 源,包括本地文件、Ultralytics HUB 模型和Triton 服务器模型。该方法初始化模型的几个 初始化模型的几个重要属性,并为训练、预测或导出等操作做好准备。

参数

名称 类型 说明 默认值
model Union[str, Path]

要加载或创建的路径或模型文件。这可以是本地 文件路径、Ultralytics HUB 中的模型名称或Triton 服务器模型。默认为 "yolov8n.pt"。

'yolov8n.pt'
task Any

与YOLO 模型相关联的任务类型,指定其应用领域。 默认为 "无"。

None
verbose bool

如果为 True,则在模型初始化和后续操作中启用冗长输出。 输出。默认为 "假"。

False

加薪:

类型 说明
FileNotFoundError

如果指定的模型文件不存在或无法访问。

ValueError

如果模型文件或配置无效或不支持。

ImportError

如果未安装特定模型类型(如HUB SDK)所需的依赖项。

源代码 ultralytics/engine/model.py
def __init__(
    self,
    model: Union[str, Path] = "yolov8n.pt",
    task: str = None,
    verbose: bool = False,
) -> None:
    """
    Initializes a new instance of the YOLO model class.

    This constructor sets up the model based on the provided model path or name. It handles various types of model
    sources, including local files, Ultralytics HUB models, and Triton Server models. The method initializes several
    important attributes of the model and prepares it for operations like training, prediction, or export.

    Args:
        model (Union[str, Path], optional): The path or model file to load or create. This can be a local
            file path, a model name from Ultralytics HUB, or a Triton Server model. Defaults to 'yolov8n.pt'.
        task (Any, optional): The task type associated with the YOLO model, specifying its application domain.
            Defaults to None.
        verbose (bool, optional): If True, enables verbose output during the model's initialization and subsequent
            operations. Defaults to False.

    Raises:
        FileNotFoundError: If the specified model file does not exist or is inaccessible.
        ValueError: If the model file or configuration is invalid or unsupported.
        ImportError: If required dependencies for specific model types (like HUB SDK) are not installed.
    """
    super().__init__()
    self.callbacks = callbacks.get_default_callbacks()
    self.predictor = None  # reuse predictor
    self.model = None  # model object
    self.trainer = None  # trainer object
    self.ckpt = None  # if loaded from *.pt
    self.cfg = None  # if loaded from *.yaml
    self.ckpt_path = None
    self.overrides = {}  # overrides for trainer object
    self.metrics = None  # validation/training metrics
    self.session = None  # HUB session
    self.task = task  # task type
    self.model_name = model = str(model).strip()  # strip spaces

    # Check if Ultralytics HUB model from https://hub.ultralytics.com
    if self.is_hub_model(model):
        # Fetch model from HUB
        checks.check_requirements("hub-sdk>0.0.2")
        self.session = self._get_hub_session(model)
        model = self.session.model_file

    # Check if Triton Server model
    elif self.is_triton_model(model):
        self.model = model
        self.task = task
        return

    # Load or create new YOLO model
    model = checks.check_model_file_from_stem(model)  # add suffix, i.e. yolov8n -> yolov8n.pt
    if Path(model).suffix in (".yaml", ".yml"):
        self._new(model, task=task, verbose=verbose)
    else:
        self._load(model, task=task)

    self.model_name = model

add_callback(event, func)

为指定事件添加回调函数。

该方法允许用户注册一个自定义回调函数,在模型训练或推理过程中触发特定事件。 回调函数。

参数

名称 类型 说明 默认值
event str

要附加回调的事件名称。

所需
func callable

要注册的回调函数。

所需

加薪:

类型 说明
ValueError

如果事件名称无法识别。

源代码 ultralytics/engine/model.py
def add_callback(self, event: str, func) -> None:
    """
    Adds a callback function for a specified event.

    This method allows the user to register a custom callback function that is triggered on a specific event during
    model training or inference.

    Args:
        event (str): The name of the event to attach the callback to.
        func (callable): The callback function to be registered.

    Raises:
        ValueError: If the event name is not recognized.
    """
    self.callbacks[event].append(func)

benchmark(**kwargs)

在各种输出格式中对模型进行基准测试,以评估性能。

This method assesses the model's performance in different export formats, such asONNX,TorchScript, etc. It uses the 'benchmark' function from theultralytics.utils.benchmarks module.基准配置 using a combination of default configuration values, model-specific arguments, method-specific defaults, and 用户提供的任何附加关键字参数进行配置。

该方法支持各种参数,允许自定义基准测试过程,如数据集 选择、图像大小、精度模式、设备选择和冗余度。有关所有 可配置选项的完整列表,用户应参考文档中的 "配置 "部分。

参数

名称 类型 说明 默认值
**kwargs dict

任意关键字参数,用于定制基准测试过程。这些参数与 默认配置、特定模型参数和方法默认值相结合。

{}

返回:

类型 说明
dict

包含基准测试结果的词典。

加薪:

类型 说明
AssertionError

如果模型不是PyTorch 模型。

源代码 ultralytics/engine/model.py
def benchmark(
    self,
    **kwargs,
):
    """
    Benchmarks the model across various export formats to evaluate performance.

    This method assesses the model's performance in different export formats, such as ONNX, TorchScript, etc.
    It uses the 'benchmark' function from the ultralytics.utils.benchmarks module. The benchmarking is configured
    using a combination of default configuration values, model-specific arguments, method-specific defaults, and
    any additional user-provided keyword arguments.

    The method supports various arguments that allow customization of the benchmarking process, such as dataset
    choice, image size, precision modes, device selection, and verbosity. For a comprehensive list of all
    configurable options, users should refer to the 'configuration' section in the documentation.

    Args:
        **kwargs (dict): Arbitrary keyword arguments to customize the benchmarking process. These are combined with
            default configurations, model-specific arguments, and method defaults.

    Returns:
        (dict): A dictionary containing the results of the benchmarking process.

    Raises:
        AssertionError: If the model is not a PyTorch model.
    """
    self._check_is_pytorch_model()
    from ultralytics.utils.benchmarks import benchmark

    custom = {"verbose": False}  # method defaults
    args = {**DEFAULT_CFG_DICT, **self.model.args, **custom, **kwargs, "mode": "benchmark"}
    return benchmark(
        model=self,
        data=kwargs.get("data"),  # if no 'data' argument passed set data=None for default datasets
        imgsz=args["imgsz"],
        half=args["half"],
        int8=args["int8"],
        device=args["device"],
        verbose=kwargs.get("verbose"),
    )

clear_callback(event)

清除为指定事件注册的所有回调函数。

此方法会删除与给定事件相关的所有自定义和默认回调函数。

参数

名称 类型 说明 默认值
event str

要清除回调的事件名称。

所需

加薪:

类型 说明
ValueError

如果事件名称无法识别。

源代码 ultralytics/engine/model.py
def clear_callback(self, event: str) -> None:
    """
    Clears all callback functions registered for a specified event.

    This method removes all custom and default callback functions associated with the given event.

    Args:
        event (str): The name of the event for which to clear the callbacks.

    Raises:
        ValueError: If the event name is not recognized.
    """
    self.callbacks[event] = []

embed(source=None, stream=False, **kwargs)

根据提供的数据源生成图像嵌入。

该方法是对 "predict() "方法的封装,主要用于从图像源生成嵌入。 它允许通过各种关键字参数自定义嵌入过程。

参数

名称 类型 说明 默认值
source str | int | Image | ndarray

生成嵌入代码的图像源。 来源可以是文件路径、URL、PIL 图像、numpy 数组等。默认为 "无"。

None
stream bool

如果为 True,预测将以流式传输。Defaults to False.

False
**kwargs dict

用于配置嵌入过程的附加关键字参数。

{}

返回:

类型 说明
List[Tensor]

包含图像嵌入的列表。

加薪:

类型 说明
AssertionError

如果模型不是PyTorch 模型。

源代码 ultralytics/engine/model.py
def embed(
    self,
    source: Union[str, Path, int, list, tuple, np.ndarray, torch.Tensor] = None,
    stream: bool = False,
    **kwargs,
) -> list:
    """
    Generates image embeddings based on the provided source.

    This method is a wrapper around the 'predict()' method, focusing on generating embeddings from an image source.
    It allows customization of the embedding process through various keyword arguments.

    Args:
        source (str | int | PIL.Image | np.ndarray): The source of the image for generating embeddings.
            The source can be a file path, URL, PIL image, numpy array, etc. Defaults to None.
        stream (bool): If True, predictions are streamed. Defaults to False.
        **kwargs (dict): Additional keyword arguments for configuring the embedding process.

    Returns:
        (List[torch.Tensor]): A list containing the image embeddings.

    Raises:
        AssertionError: If the model is not a PyTorch model.
    """
    if not kwargs.get("embed"):
        kwargs["embed"] = [len(self.model.model) - 2]  # embed second-to-last layer if no indices passed
    return self.predict(source, stream, **kwargs)

export(**kwargs)

将模型导出为适合部署的不同格式。

这种方法便于将模型导出为各种格式(如ONNX,TorchScript ),以便部署。 为部署目的。它使用 "Exporter "类来完成导出过程,将模型特定的重载、方法默认值 默认值和提供的任何附加参数。综合参数用于配置导出设置。

该方法支持多种参数,可自定义导出过程。有关所有 参数,请参阅文档中的 "配置 "部分。

参数

名称 类型 说明 默认值
**kwargs dict

用于自定义导出过程的任意关键字参数。这些参数与 模型的重载和方法默认值相结合。

{}

返回:

类型 说明
object

以指定格式导出的模型,或与导出过程相关的对象。

加薪:

类型 说明
AssertionError

如果模型不是PyTorch 模型。

源代码 ultralytics/engine/model.py
def export(
    self,
    **kwargs,
):
    """
    Exports the model to a different format suitable for deployment.

    This method facilitates the export of the model to various formats (e.g., ONNX, TorchScript) for deployment
    purposes. It uses the 'Exporter' class for the export process, combining model-specific overrides, method
    defaults, and any additional arguments provided. The combined arguments are used to configure export settings.

    The method supports a wide range of arguments to customize the export process. For a comprehensive list of all
    possible arguments, refer to the 'configuration' section in the documentation.

    Args:
        **kwargs (dict): Arbitrary keyword arguments to customize the export process. These are combined with the
            model's overrides and method defaults.

    Returns:
        (object): The exported model in the specified format, or an object related to the export process.

    Raises:
        AssertionError: If the model is not a PyTorch model.
    """
    self._check_is_pytorch_model()
    from .exporter import Exporter

    custom = {"imgsz": self.model.args["imgsz"], "batch": 1, "data": None, "verbose": False}  # method defaults
    args = {**self.overrides, **custom, **kwargs, "mode": "export"}  # highest priority args on the right
    return Exporter(overrides=args, _callbacks=self.callbacks)(model=self.model)

fuse()

在模型中融合 Conv2d 和 BatchNorm2d 图层。

这种方法通过融合 Conv2d 层和 BatchNorm2d 层来优化模型,从而提高推理速度。

加薪:

类型 说明
AssertionError

如果模型不是PyTorch 模型。

源代码 ultralytics/engine/model.py
def fuse(self):
    """
    Fuses Conv2d and BatchNorm2d layers in the model.

    This method optimizes the model by fusing Conv2d and BatchNorm2d layers, which can improve inference speed.

    Raises:
        AssertionError: If the model is not a PyTorch model.
    """
    self._check_is_pytorch_model()
    self.model.fuse()

info(detailed=False, verbose=True)

记录或返回模型信息。

该方法根据传递的参数提供有关模型的概述或详细信息。 它可以控制输出的冗长程度。

参数

名称 类型 说明 默认值
detailed bool

如果为 True,则显示模型的详细信息。默认为 "假"。

False
verbose bool

如果为 True,则打印信息。如果为 False,则返回信息。默认为 True。

True

返回:

类型 说明
list

根据 "详细 "和 "冗长 "参数,提供有关模型的各类信息。

加薪:

类型 说明
AssertionError

如果模型不是PyTorch 模型。

源代码 ultralytics/engine/model.py
def info(self, detailed: bool = False, verbose: bool = True):
    """
    Logs or returns model information.

    This method provides an overview or detailed information about the model, depending on the arguments passed.
    It can control the verbosity of the output.

    Args:
        detailed (bool): If True, shows detailed information about the model. Defaults to False.
        verbose (bool): If True, prints the information. If False, returns the information. Defaults to True.

    Returns:
        (list): Various types of information about the model, depending on the 'detailed' and 'verbose' parameters.

    Raises:
        AssertionError: If the model is not a PyTorch model.
    """
    self._check_is_pytorch_model()
    return self.model.info(detailed=detailed, verbose=verbose)

is_hub_model(model) staticmethod

检查所提供的模型是否为HUB 模型。

源代码 ultralytics/engine/model.py
@staticmethod
def is_hub_model(model: str) -> bool:
    """Check if the provided model is a HUB model."""
    return any(
        (
            model.startswith(f"{HUB_WEB_ROOT}/models/"),  # i.e. https://hub.ultralytics.com/models/MODEL_ID
            [len(x) for x in model.split("_")] == [42, 20],  # APIKEY_MODELID
            len(model) == 20 and not Path(model).exists() and all(x not in model for x in "./\\"),  # MODELID
        )
    )

is_triton_model(model) staticmethod

模型是Triton 服务器 URL 字符串,即 :////

源代码 ultralytics/engine/model.py
@staticmethod
def is_triton_model(model: str) -> bool:
    """Is model a Triton Server URL string, i.e. <scheme>://<netloc>/<endpoint>/<task_name>"""
    from urllib.parse import urlsplit

    url = urlsplit(model)
    return url.netloc and url.path and url.scheme in {"http", "grpc"}

load(weights='yolov8n.pt')

将指定权重文件中的参数加载到模型中。

该方法支持从文件或直接从权重对象加载权重。它通过 名称和形状匹配参数,并将它们传输到模型中。

参数

名称 类型 说明 默认值
weights str | Path

权重文件或权重对象的路径。默认为 "yolov8n.pt"。

'yolov8n.pt'

返回:

名称 类型 说明
self Model

已加载权重的类实例。

加薪:

类型 说明
AssertionError

如果模型不是PyTorch 模型。

源代码 ultralytics/engine/model.py
def load(self, weights: Union[str, Path] = "yolov8n.pt") -> "Model":
    """
    Loads parameters from the specified weights file into the model.

    This method supports loading weights from a file or directly from a weights object. It matches parameters by
    name and shape and transfers them to the model.

    Args:
        weights (str | Path): Path to the weights file or a weights object. Defaults to 'yolov8n.pt'.

    Returns:
        self (ultralytics.engine.model.Model): The instance of the class with loaded weights.

    Raises:
        AssertionError: If the model is not a PyTorch model.
    """
    self._check_is_pytorch_model()
    if isinstance(weights, (str, Path)):
        weights, self.ckpt = attempt_load_one_weight(weights)
    self.model.load(weights)
    return self

predict(source=None, stream=False, predictor=None, **kwargs)

使用YOLO 模型对给定的图像源进行预测。

该方法可简化预测过程,允许通过关键字参数进行各种配置。 它支持使用自定义预测器或默认预测器方法进行预测。该方法可处理不同 类型的图像源,并可在流模式下运行。它还通过 "提示 "为SAM 类型的模型提供支持。 类型的模型。

该方法会设置一个新的预测器(如果尚未存在),并在每次调用时更新参数。 如果没有提供 "源",它还会发出警告并使用默认资产。该方法会判断是否 是否从命令行界面调用,并相应调整其行为,包括为置信度阈值和保存行为设置默认值。 置信度阈值和保存行为。

参数

名称 类型 说明 默认值
source str | int | Image | ndarray

用于预测的图像来源。 接受各种类型,包括文件路径、URL、PIL 图像和 numpy 数组。默认为 ASSETS。

None
stream bool

将输入源视为连续流进行预测。默认为 "假"。

False
predictor BasePredictor

用于进行预测的自定义预测器类的实例。 如果为 "无",该方法将使用默认预测器。默认为 "无"。

None
**kwargs dict

用于配置预测过程的附加关键字参数。这些参数允许 进一步定制预测行为。

{}

返回:

类型 说明
List[Results]

预测结果列表,封装在结果类中。

加薪:

类型 说明
AttributeError

如果预测器设置不当。

源代码 ultralytics/engine/model.py
def predict(
    self,
    source: Union[str, Path, int, list, tuple, np.ndarray, torch.Tensor] = None,
    stream: bool = False,
    predictor=None,
    **kwargs,
) -> list:
    """
    Performs predictions on the given image source using the YOLO model.

    This method facilitates the prediction process, allowing various configurations through keyword arguments.
    It supports predictions with custom predictors or the default predictor method. The method handles different
    types of image sources and can operate in a streaming mode. It also provides support for SAM-type models
    through 'prompts'.

    The method sets up a new predictor if not already present and updates its arguments with each call.
    It also issues a warning and uses default assets if the 'source' is not provided. The method determines if it
    is being called from the command line interface and adjusts its behavior accordingly, including setting defaults
    for confidence threshold and saving behavior.

    Args:
        source (str | int | PIL.Image | np.ndarray, optional): The source of the image for making predictions.
            Accepts various types, including file paths, URLs, PIL images, and numpy arrays. Defaults to ASSETS.
        stream (bool, optional): Treats the input source as a continuous stream for predictions. Defaults to False.
        predictor (BasePredictor, optional): An instance of a custom predictor class for making predictions.
            If None, the method uses a default predictor. Defaults to None.
        **kwargs (dict): Additional keyword arguments for configuring the prediction process. These arguments allow
            for further customization of the prediction behavior.

    Returns:
        (List[ultralytics.engine.results.Results]): A list of prediction results, encapsulated in the Results class.

    Raises:
        AttributeError: If the predictor is not properly set up.
    """
    if source is None:
        source = ASSETS
        LOGGER.warning(f"WARNING ⚠️ 'source' is missing. Using 'source={source}'.")

    is_cli = (sys.argv[0].endswith("yolo") or sys.argv[0].endswith("ultralytics")) and any(
        x in sys.argv for x in ("predict", "track", "mode=predict", "mode=track")
    )

    custom = {"conf": 0.25, "save": is_cli, "mode": "predict"}  # method defaults
    args = {**self.overrides, **custom, **kwargs}  # highest priority args on the right
    prompts = args.pop("prompts", None)  # for SAM-type models

    if not self.predictor:
        self.predictor = predictor or self._smart_load("predictor")(overrides=args, _callbacks=self.callbacks)
        self.predictor.setup_model(model=self.model, verbose=is_cli)
    else:  # only update args if predictor is already setup
        self.predictor.args = get_cfg(self.predictor.args, args)
        if "project" in args or "name" in args:
            self.predictor.save_dir = get_save_dir(self.predictor.args)
    if prompts and hasattr(self.predictor, "set_prompts"):  # for SAM-type models
        self.predictor.set_prompts(prompts)
    return self.predictor.predict_cli(source=source) if is_cli else self.predictor(source=source, stream=stream)

reset_callbacks()

将所有回调重置为默认函数。

此方法会恢复所有事件的默认回调函数,移除之前添加的任何自定义回调函数。 之前添加的自定义回调函数。

源代码 ultralytics/engine/model.py
def reset_callbacks(self) -> None:
    """
    Resets all callbacks to their default functions.

    This method reinstates the default callback functions for all events, removing any custom callbacks that were
    added previously.
    """
    for event in callbacks.default_callbacks.keys():
        self.callbacks[event] = [callbacks.default_callbacks[event][0]]

reset_weights()

将模型参数重置为随机初始值,从而有效地丢弃所有训练信息。

此方法会遍历模型中的所有模块,如果模块有 reset_parameters' 方法的模块,将重置其参数。它还会确保所有参数的 "requires_grad "设置为 True,以便在训练过程中更新参数。 在训练过程中进行更新。

返回:

名称 类型 说明
self Model

重置权重的类实例。

加薪:

类型 说明
AssertionError

如果模型不是PyTorch 模型。

源代码 ultralytics/engine/model.py
def reset_weights(self) -> "Model":
    """
    Resets the model parameters to randomly initialized values, effectively discarding all training information.

    This method iterates through all modules in the model and resets their parameters if they have a
    'reset_parameters' method. It also ensures that all parameters have 'requires_grad' set to True, enabling them
    to be updated during training.

    Returns:
        self (ultralytics.engine.model.Model): The instance of the class with reset weights.

    Raises:
        AssertionError: If the model is not a PyTorch model.
    """
    self._check_is_pytorch_model()
    for m in self.model.modules():
        if hasattr(m, "reset_parameters"):
            m.reset_parameters()
    for p in self.model.parameters():
        p.requires_grad = True
    return self

save(filename='saved_model.pt')

将当前模型状态保存到文件中。

此方法将模型的检查点(ckpt)导出到指定的文件名中。

参数

名称 类型 说明 默认值
filename str | Path

保存模型的文件名。默认为 "saved_model.pt"。

'saved_model.pt'

加薪:

类型 说明
AssertionError

如果模型不是PyTorch 模型。

源代码 ultralytics/engine/model.py
def save(self, filename: Union[str, Path] = "saved_model.pt") -> None:
    """
    Saves the current model state to a file.

    This method exports the model's checkpoint (ckpt) to the specified filename.

    Args:
        filename (str | Path): The name of the file to save the model to. Defaults to 'saved_model.pt'.

    Raises:
        AssertionError: If the model is not a PyTorch model.
    """
    self._check_is_pytorch_model()
    torch.save(self.ckpt, filename)

track(source=None, stream=False, persist=False, **kwargs)

使用已注册的跟踪器对指定输入源进行目标跟踪。

该方法使用模型的预测器和可选的注册跟踪器执行物体跟踪。它 能处理不同类型的输入源,如文件路径或视频流。该方法支持 通过各种关键字参数自定义跟踪过程。如果跟踪器还未 跟踪器,并根据 "持久化 "标志选择性地持久化跟踪器。

该方法专门为基于 ByteTrack 的跟踪设置了一个默认置信度阈值,它需要低置信度预测作为输入。 置信度预测作为输入。跟踪模式在关键字参数中明确设置。

参数

名称 类型 说明 默认值
source str

目标跟踪的输入源。可以是文件路径、URL 或视频流。

None
stream bool

将输入源视为连续视频流。默认为 "假"。

False
persist bool

在不同的方法调用之间持续跟踪器。默认为 "假"。

False
**kwargs dict

用于配置跟踪过程的附加关键字参数。这些参数允许 进一步自定义跟踪行为。

{}

返回:

类型 说明
List[Results]

跟踪结果列表,封装在 Results 类中。

加薪:

类型 说明
AttributeError

如果预测器没有注册跟踪器。

源代码 ultralytics/engine/model.py
def track(
    self,
    source: Union[str, Path, int, list, tuple, np.ndarray, torch.Tensor] = None,
    stream: bool = False,
    persist: bool = False,
    **kwargs,
) -> list:
    """
    Conducts object tracking on the specified input source using the registered trackers.

    This method performs object tracking using the model's predictors and optionally registered trackers. It is
    capable of handling different types of input sources such as file paths or video streams. The method supports
    customization of the tracking process through various keyword arguments. It registers trackers if they are not
    already present and optionally persists them based on the 'persist' flag.

    The method sets a default confidence threshold specifically for ByteTrack-based tracking, which requires low
    confidence predictions as input. The tracking mode is explicitly set in the keyword arguments.

    Args:
        source (str, optional): The input source for object tracking. It can be a file path, URL, or video stream.
        stream (bool, optional): Treats the input source as a continuous video stream. Defaults to False.
        persist (bool, optional): Persists the trackers between different calls to this method. Defaults to False.
        **kwargs (dict): Additional keyword arguments for configuring the tracking process. These arguments allow
            for further customization of the tracking behavior.

    Returns:
        (List[ultralytics.engine.results.Results]): A list of tracking results, encapsulated in the Results class.

    Raises:
        AttributeError: If the predictor does not have registered trackers.
    """
    if not hasattr(self.predictor, "trackers"):
        from ultralytics.trackers import register_tracker

        register_tracker(self, persist)
    kwargs["conf"] = kwargs.get("conf") or 0.1  # ByteTrack-based method needs low confidence predictions as input
    kwargs["mode"] = "track"
    return self.predict(source=source, stream=stream, **kwargs)

train(trainer=None, **kwargs)

使用指定的数据集和训练配置训练模型。

这种方法可通过一系列可定制的设置和配置来促进模型训练。它支持 方法中定义的默认训练方法进行训练。该方法可处理 不同的情况,如从检查点恢复训练、与Ultralytics HUB 集成,以及在训练后更新模型和配置。 训练后更新模型和配置。

当使用Ultralytics HUB 时,如果会话已经加载了模型,该方法会优先使用HUB 训练参数,如果提供了本地参数,则会发出警告。 参数,并在提供本地参数时发出警告。它会检查 pip 更新,并结合默认配置、方法特定的默认值和用户提供的参数。 配置、特定方法的默认值和用户提供的参数来配置训练过程。在 训练后,它会更新模型及其配置,并选择性地附加度量指标。

参数

名称 类型 说明 默认值
trainer BaseTrainer

用于训练模型的自定义训练器类的实例。如果无,该 方法使用默认训练器。默认为 "无"。

None
**kwargs dict

代表训练配置的任意关键字参数。这些参数 用于定制训练过程的各个方面。

{}

返回:

类型 说明
dict | None

如果有培训指标且培训成功,则为培训指标;否则为无。

加薪:

类型 说明
AssertionError

如果模型不是PyTorch 模型。

PermissionError

如果HUB 会话存在权限问题。

ModuleNotFoundError

如果未安装HUB SDK。

源代码 ultralytics/engine/model.py
def train(
    self,
    trainer=None,
    **kwargs,
):
    """
    Trains the model using the specified dataset and training configuration.

    This method facilitates model training with a range of customizable settings and configurations. It supports
    training with a custom trainer or the default training approach defined in the method. The method handles
    different scenarios, such as resuming training from a checkpoint, integrating with Ultralytics HUB, and
    updating model and configuration after training.

    When using Ultralytics HUB, if the session already has a loaded model, the method prioritizes HUB training
    arguments and issues a warning if local arguments are provided. It checks for pip updates and combines default
    configurations, method-specific defaults, and user-provided arguments to configure the training process. After
    training, it updates the model and its configurations, and optionally attaches metrics.

    Args:
        trainer (BaseTrainer, optional): An instance of a custom trainer class for training the model. If None, the
            method uses a default trainer. Defaults to None.
        **kwargs (dict): Arbitrary keyword arguments representing the training configuration. These arguments are
            used to customize various aspects of the training process.

    Returns:
        (dict | None): Training metrics if available and training is successful; otherwise, None.

    Raises:
        AssertionError: If the model is not a PyTorch model.
        PermissionError: If there is a permission issue with the HUB session.
        ModuleNotFoundError: If the HUB SDK is not installed.
    """
    self._check_is_pytorch_model()
    if hasattr(self.session, "model") and self.session.model.id:  # Ultralytics HUB session with loaded model
        if any(kwargs):
            LOGGER.warning("WARNING ⚠️ using HUB training arguments, ignoring local training arguments.")
        kwargs = self.session.train_args  # overwrite kwargs

    checks.check_pip_update_available()

    overrides = yaml_load(checks.check_yaml(kwargs["cfg"])) if kwargs.get("cfg") else self.overrides
    custom = {"data": DEFAULT_CFG_DICT["data"] or TASK2DATA[self.task]}  # method defaults
    args = {**overrides, **custom, **kwargs, "mode": "train"}  # highest priority args on the right
    if args.get("resume"):
        args["resume"] = self.ckpt_path

    self.trainer = (trainer or self._smart_load("trainer"))(overrides=args, _callbacks=self.callbacks)
    if not args.get("resume"):  # manually set model only if not resuming
        self.trainer.model = self.trainer.get_model(weights=self.model if self.ckpt else None, cfg=self.model.yaml)
        self.model = self.trainer.model

        if SETTINGS["hub"] is True and not self.session:
            # Create a model in HUB
            try:
                self.session = self._get_hub_session(self.model_name)
                if self.session:
                    self.session.create_model(args)
                    # Check model was created
                    if not getattr(self.session.model, "id", None):
                        self.session = None
            except (PermissionError, ModuleNotFoundError):
                # Ignore PermissionError and ModuleNotFoundError which indicates hub-sdk not installed
                pass

    self.trainer.hub_session = self.session  # attach optional HUB session
    self.trainer.train()
    # Update model and cfg after training
    if RANK in (-1, 0):
        ckpt = self.trainer.best if self.trainer.best.exists() else self.trainer.last
        self.model, _ = attempt_load_one_weight(ckpt)
        self.overrides = self.model.args
        self.metrics = getattr(self.trainer.validator, "metrics", None)  # TODO: no metrics returned by DDP
    return self.metrics

tune(use_ray=False, iterations=10, *args, **kwargs)

对模型进行超参数调整,可选择使用 Ray Tune。

该方法支持两种超参数调整模式:使用 Ray Tune 或自定义调整方法。 启用 Ray Tune 时,它将利用ultralytics.utils.tuner 模块中的 "run_ray_tune "函数。 否则,它会使用内部的 "调谐器 "类进行调谐。该方法结合默认、重载和自定义参数来配置调谐。 自定义参数来配置调谐过程。

参数

名称 类型 说明 默认值
use_ray bool

如果为 True,则使用 Ray Tune 进行超参数调整。默认为假。

False
iterations int

要执行的调整迭代次数。默认为 10 次。

10
*args list

用于附加参数的长度可变的参数列表。

()
**kwargs dict

任意关键字参数。这些参数与模型的覆盖和默认值相结合。

{}

返回:

类型 说明
dict

包含超参数搜索结果的字典。

加薪:

类型 说明
AssertionError

如果模型不是PyTorch 模型。

源代码 ultralytics/engine/model.py
def tune(
    self,
    use_ray=False,
    iterations=10,
    *args,
    **kwargs,
):
    """
    Conducts hyperparameter tuning for the model, with an option to use Ray Tune.

    This method supports two modes of hyperparameter tuning: using Ray Tune or a custom tuning method.
    When Ray Tune is enabled, it leverages the 'run_ray_tune' function from the ultralytics.utils.tuner module.
    Otherwise, it uses the internal 'Tuner' class for tuning. The method combines default, overridden, and
    custom arguments to configure the tuning process.

    Args:
        use_ray (bool): If True, uses Ray Tune for hyperparameter tuning. Defaults to False.
        iterations (int): The number of tuning iterations to perform. Defaults to 10.
        *args (list): Variable length argument list for additional arguments.
        **kwargs (dict): Arbitrary keyword arguments. These are combined with the model's overrides and defaults.

    Returns:
        (dict): A dictionary containing the results of the hyperparameter search.

    Raises:
        AssertionError: If the model is not a PyTorch model.
    """
    self._check_is_pytorch_model()
    if use_ray:
        from ultralytics.utils.tuner import run_ray_tune

        return run_ray_tune(self, max_samples=iterations, *args, **kwargs)
    else:
        from .tuner import Tuner

        custom = {}  # method defaults
        args = {**self.overrides, **custom, **kwargs, "mode": "train"}  # highest priority args on the right
        return Tuner(args=args, _callbacks=self.callbacks)(model=self, iterations=iterations)

val(validator=None, **kwargs)

使用指定的数据集和验证配置验证模型。

这种方法有助于模型验证过程,可通过各种设置和配置进行定制。 设置和配置进行自定义。它支持使用自定义验证器或默认验证方法进行验证。 该方法结合了默认配置、特定于方法的默认值和用户提供的参数来配置 验证过程。验证完成后,它会根据验证器的结果更新模型的度量指标。 验证器获得的结果更新模型的指标。

该方法支持各种参数,可以自定义验证过程。有关所有可配置选项的 所有可配置选项的完整列表,用户应参考文档中的 "配置 "部分。

参数

名称 类型 说明 默认值
validator BaseValidator

用于验证模型的自定义验证器类的实例。如果 则该方法使用默认验证器。默认为 "无"。

None
**kwargs dict

代表验证配置的任意关键字参数。这些参数 用于定制验证流程的各个方面。

{}

返回:

类型 说明
dict

从验证过程中获得的验证指标。

加薪:

类型 说明
AssertionError

如果模型不是PyTorch 模型。

源代码 ultralytics/engine/model.py
def val(
    self,
    validator=None,
    **kwargs,
):
    """
    Validates the model using a specified dataset and validation configuration.

    This method facilitates the model validation process, allowing for a range of customization through various
    settings and configurations. It supports validation with a custom validator or the default validation approach.
    The method combines default configurations, method-specific defaults, and user-provided arguments to configure
    the validation process. After validation, it updates the model's metrics with the results obtained from the
    validator.

    The method supports various arguments that allow customization of the validation process. For a comprehensive
    list of all configurable options, users should refer to the 'configuration' section in the documentation.

    Args:
        validator (BaseValidator, optional): An instance of a custom validator class for validating the model. If
            None, the method uses a default validator. Defaults to None.
        **kwargs (dict): Arbitrary keyword arguments representing the validation configuration. These arguments are
            used to customize various aspects of the validation process.

    Returns:
        (dict): Validation metrics obtained from the validation process.

    Raises:
        AssertionError: If the model is not a PyTorch model.
    """
    custom = {"rect": True}  # method defaults
    args = {**self.overrides, **custom, **kwargs, "mode": "val"}  # highest priority args on the right

    validator = (validator or self._smart_load("validator"))(args=args, _callbacks=self.callbacks)
    validator(model=self.model)
    self.metrics = validator.metrics
    return validator.metrics





创建于 2023-11-12,更新于 2023-11-25
作者:glenn-jocher(3)