fvcore 文档¶

Detectron2依赖于fvcore中的实用工具。我们在此包含了部分fvcore文档以便于参考。

fvcore.nn¶

fvcore.nn.activation_count(model: torch.nn.Module, inputs: Tuple[Any, …], supported_ops: Optional[Dict[str, Callable[[List[Any], List[Any]], Union[Counter[str], numbers.Number]]]] = None) → Tuple[DefaultDict[str, float], Counter[str]][源代码]¶

给定一个模型及其输入，计算该模型的总激活次数。

Parameters

model (nn.Module) – 用于计算激活次数的模型。
inputs (tuple) - 传递给model用于计算激活的输入。输入需要是元组形式。
supported_ops (dict(str,Callable) or None) - 为额外操作提供额外的处理程序，或覆盖现有的卷积和矩阵乘法处理程序。键是操作符名称，值是一个接收操作输入和输出的函数。

Returns

tuple[defaultdict, Counter] –

一个记录每个操作的: 激活次数（百万级）的字典，以及一个记录不支持操作数量的计数器。

class fvcore.nn.ActivationCountAnalysis(model: torch.nn.Module, inputs: Union[torch.Tensor, Tuple[torch.Tensor, …]])[源代码]¶

基类: fvcore.nn.jit_analysis.JitModelAnalysis

提供对通过使用PyTorch的JIT追踪功能追踪模型获得的每个子模块模型激活次数的访问。默认情况下，包含针对卷积和点积运算符的标准激活计数器。

可以通过使用.set_op_handle(name, func)方法来添加额外操作符的句柄，或覆盖默认的句柄。详情请参阅该方法文档。

可以获取激活计数如下：

.total(module_name=""): 模块的总激活次数
.by_operator(module_name=""): 模块的激活计数，作为不同操作符类型的计数器
.by_module(): 所有子模块的激活次数计数器
.by_module_and_operator(): 按不同操作符类型的计数器子类索引的字典

如果一个操作符在模块的__call__方法内部执行，则被视为属于该模块。请注意，这不包括对模块其他方法的调用或显式调用module.forward(...)。

示例用法：

>>> import torch.nn as nn
>>> import torch
>>> class TestModel(nn.Module):
...     def __init__(self):
...        super().__init__()
...        self.fc = nn.Linear(in_features=1000, out_features=10)
...        self.conv = nn.Conv2d(
...            in_channels=3, out_channels=10, kernel_size=1
...        )
...        self.act = nn.ReLU()
...    def forward(self, x):
...        return self.fc(self.act(self.conv(x)).flatten(1))

>>> model = TestModel()
>>> inputs = (torch.randn((1,3,10,10)),)
>>> acts = ActivationCountAnalysis(model, inputs)
>>> acts.total()
1010
>>> acts.total("fc")
10
>>> acts.by_operator()
Counter({"conv" : 1000, "addmm" : 10})
>>> acts.by_module()
Counter({"" : 1010, "fc" : 10, "conv" : 1000, "act" : 0})
>>> acts.by_module_and_operator()
{"" : Counter({"conv" : 1000, "addmm" : 10}),
 "fc" : Counter({"addmm" : 10}),
 "conv" : Counter({"conv" : 1000}),
 "act" : Counter()
}

__init__(model: torch.nn.Module, inputs: Union[torch.Tensor, Tuple[torch.Tensor, …]]) → None [源代码]¶

Parameters

model – 要分析的模型
inputs – 模型用于分析的输入数据。

We will trace the execution of model.forward(inputs). This means inputs have to be tensors or tuple of tensors (see https://pytorch.org/docs/stable/generated/torch.jit.trace.html#torch.jit.trace). In order to trace other methods or unsupported input types, you may need to implement a wrapper module.

ancestor_mode(mode: str) → T¶

设置如何确定运算符的祖先模块。必须是"owner"或"caller"之一。

"caller"：一个属于所有模块的操作符，当该操作符被调用时，当前正在执行forward()。
"owner"：一个操作符属于调用该操作符时正在执行forward()的最后一个模块，加上该模块的递归父模块。如果一个模块有多个父模块（例如共享模块），则只会选择其中一个。

在大多数情况下，模块仅调用其拥有的子模块，因此两种选项的效果相同。在某些边缘情况下，此选项会影响结果的层级结构，但不会影响总数统计。

by_module() → Counter[str]¶

返回所有子模块的统计信息，这些信息是在所有操作符上聚合的。

Returns: Counter(str) – 按子模块名称分组的统计计数器

by_module_and_operator() → Dict[str, Counter[str]]¶

返回所有子模块的统计信息，按每个子模块的操作符类型分开。操作符句柄决定了与每种操作符类型关联的名称。

Returns: dict(str, Counter(str)) – 每个子模块和每个运算符的统计信息。按子模块名称分组，然后按运算符名称分组。

by_operator(module_name: str = '') → Counter[str]¶

返回按操作符类型分组的请求模块的统计信息。操作符句柄决定了与每种操作符类型相关联的名称。

Parameters: module_name (str) – 要获取数据的子模块。默认为整个模型。
Returns: Counter(str) – 每个运算符的统计信息。

canonical_module_name(name: str) → str ¶

返回给定name的规范模块名称，如果模块是共享的，该名称可能与给定的name不同。这是在使用.by_module()和.by_module_and_operator()输出统计信息时将用作键的名称。

Parameters: name (str) – 要查找规范名称的模块名称。
Returns: str – 该模块的规范名称。

clear_op_handles() → fvcore.nn.jit_analysis.JitModelAnalysis¶: 清除当前设置的所有操作符句柄。

copy(new_model: Optional[torch.nn.Module] = None, new_inputs: Union[None, torch.Tensor, Tuple[torch.Tensor, …]] = None) → fvcore.nn.jit_analysis.JitModelAnalysis¶

返回一个JitModelAnalysis对象的副本，保留所有设置，但应用于新模型或新输入。

Parameters

new_model (nn.Module 或 None) - 用于新JitModelAnalysis的新模型。如果为None，则使用原始模型。
new_inputs (typing.Tuple[object, ..] or None) - 用于新JitModelAnalysis的新输入。如果为None，则使用原始输入。

Returns

JitModelAnalysis – 新型模型分析对象

set_op_handle(*args, **kwargs: Optional[Callable[[List[Any], List[Any]], Union[Counter[str], numbers.Number]]]) → fvcore.nn.jit_analysis.JitModelAnalysis¶

设置额外的操作符句柄，或替换现有的句柄。

Parameters

args – 操作符名称与句柄的(str, Handle)键值对。
kwargs – 从操作符名称到句柄的映射。

如果句柄是None，该操作将被显式忽略。否则，句柄应是一个用于从运算符计算所需统计量的函数。该函数必须接受两个参数，即运算符的输入和输出，形式为list(torch._C.Value)。该函数应返回一个包含每个运算符统计数据的计数器对象。

示例

handlers = {"aten::linear": my_handler}
counter.set_op_handle("aten::matmul", None, "aten::bmm", my_handler2)
       .set_op_handle(**handlers)

total(module_name: str = '') → int ¶

返回所请求模块中所有操作符的总体汇总统计信息。

Parameters: module_name (str) – 要获取数据的子模块。默认为整个模型。
Returns: int – 聚合统计量。

tracer_warnings(mode: str) → T¶

设置在图谱追踪计算统计量时打印哪些警告。共有三种模式，默认为'no_tracer_warning'。允许的值为：

'all' : 保留跟踪过程中产生的所有警告
'no_tracer_warning' : 仅抑制 torch.jit.TracerWarning
'none' : 在追踪过程中抑制所有警告

Parameters: mode (str) – 警告模式，取上述值之一。

uncalled_modules() → Set[str]¶

返回一组在图形追踪过程中从未被调用的子模块。这可能是因为它们未被使用，或者是因为它们通过直接调用.forward()或其他Python方法被访问。在后一种情况下，统计信息不会归属于该子模块，但这些统计信息仍会包含在父模块中。

Returns

set(str) –

在模型跟踪过程中从未被调用的子模块名称集合

uncalled_modules_warnings(enabled: bool) → T¶

设置是否显示未调用子模块的警告。默认为true。如果子模块在跟踪过程中从未被调用，则被视为“未调用”。这可能是因为它实际上未被使用，或者是因为它是通过调用.forward()或模块的其他方法来访问的。无论此设置如何，都可以从uncalled_modules()获取未调用模块的集合。

Parameters: enabled (bool) – 设置为'True'以显示警告。

unsupported_ops(module_name: str = '') → Counter[str]¶

列出遇到但因无可用操作符处理程序而不支持的运算符数量。不包括明确忽略的运算符。

Parameters: module_name (str) – 要列出不支持操作（ops）的子模块。默认为整个模型。
Returns: Counter(str) – 每个不受支持运算符的出现次数。

unsupported_ops_warnings(enabled: bool) → T¶

设置是否显示不支持的操作符警告。默认为True。无论此设置如何，都可以通过unsupported_ops()获取不支持的操作符计数。

Parameters: enabled (bool) - 设置为'True'以显示不支持的运算符警告。

fvcore.nn.flop_count(model: torch.nn.Module, inputs: Tuple[Any, …], supported_ops: Optional[Dict[str, Callable[[List[Any], List[Any]], Union[Counter[str], numbers.Number]]]] = None) → Tuple[DefaultDict[str, float], Counter[str]][源代码]¶

给定一个模型及其输入，计算该模型中每个算子的Gflops（十亿次浮点运算）。

Parameters

model (nn.Module) - 用于计算浮点运算次数的模型。
inputs (tuple) - 传递给model用于计算浮点运算次数的输入。输入需要是元组形式。
supported_ops (dict(str,Callable) or None) - 为额外操作提供额外的处理程序，或覆盖现有的卷积、矩阵乘法和einsum操作的处理程序。键是运算符名称，值是一个接收操作输入和输出的函数。我们将一次乘加运算计为一次FLOP。

Returns

tuple[defaultdict, Counter] –

一个记录每种操作: 浮点运算次数的字典，以及一个记录不支持操作数量的计数器。

class fvcore.nn.FlopCountAnalysis(model: torch.nn.Module, inputs: Union[torch.Tensor, Tuple[torch.Tensor, …]])[源代码]¶

基类: fvcore.nn.jit_analysis.JitModelAnalysis

提供通过使用PyTorch的JIT追踪功能对模型进行跟踪获得的每个子模块浮点运算次数的访问。默认情况下，包含一些常见运算符的标准浮点运算计数器。请注意：

Flop 不是一个明确定义的概念。我们只是提供我们最佳的估算。

我们将一次融合乘加运算计为一次浮点运算。

可以通过使用.set_op_handle(name, func)方法来添加额外操作符的句柄，或覆盖默认的句柄。详情请参阅该方法文档。

浮点运算次数可以这样获取：

.total(module_name=""): 该模块的总浮点运算次数
.by_operator(module_name=""): 模块的浮点运算次数统计，以不同运算符类型为键的计数器形式呈现
.by_module(): 所有子模块的浮点运算次数计数器
.by_module_and_operator(): 按不同操作符类型的Counters后代索引的字典

如果一个操作符在模块的__call__方法内部执行，则被视为属于该模块。请注意，这不包括对模块其他方法的调用或显式调用module.forward(...)。

示例用法：

>>> import torch.nn as nn
>>> import torch
>>> class TestModel(nn.Module):
...    def __init__(self):
...        super().__init__()
...        self.fc = nn.Linear(in_features=1000, out_features=10)
...        self.conv = nn.Conv2d(
...            in_channels=3, out_channels=10, kernel_size=1
...        )
...        self.act = nn.ReLU()
...    def forward(self, x):
...        return self.fc(self.act(self.conv(x)).flatten(1))

>>> model = TestModel()
>>> inputs = (torch.randn((1,3,10,10)),)
>>> flops = FlopCountAnalysis(model, inputs)
>>> flops.total()
13000
>>> flops.total("fc")
10000
>>> flops.by_operator()
Counter({"addmm" : 10000, "conv" : 3000})
>>> flops.by_module()
Counter({"" : 13000, "fc" : 10000, "conv" : 3000, "act" : 0})
>>> flops.by_module_and_operator()
{"" : Counter({"addmm" : 10000, "conv" : 3000}),
 "fc" : Counter({"addmm" : 10000}),
 "conv" : Counter({"conv" : 3000}),
 "act" : Counter()
}

__init__(model: torch.nn.Module, inputs: Union[torch.Tensor, Tuple[torch.Tensor, …]]) → None [源代码]¶

Parameters

model – 要分析的模型
inputs – 模型用于分析的输入数据。

We will trace the execution of model.forward(inputs). This means inputs have to be tensors or tuple of tensors (see https://pytorch.org/docs/stable/generated/torch.jit.trace.html#torch.jit.trace). In order to trace other methods or unsupported input types, you may need to implement a wrapper module.

ancestor_mode(mode: str) → T¶

设置如何确定运算符的祖先模块。必须是"owner"或"caller"之一。

"调用者"：属于当前正在执行forward()的所有模块的操作符，在操作符被调用时。
"owner"：一个操作符属于最后执行forward()的模块，加上该模块的递归父模块。如果一个模块有多个父模块（例如共享模块），只会选择其中一个。

在大多数情况下，模块仅调用其拥有的子模块，因此两种选项的效果相同。在某些边缘情况下，此选项会影响结果的层级结构，但不会影响总数统计。

by_module() → Counter[str]¶

返回所有子模块的统计信息，这些信息是在所有操作符上聚合的。

Returns: Counter(str) – 按子模块名称分组的统计计数器

by_module_and_operator() → Dict[str, Counter[str]]¶

返回所有子模块的统计信息，按每个子模块的操作符类型分开。操作符句柄决定了与每种操作符类型关联的名称。

Returns: dict(str, Counter(str)) – 每个子模块和每个运算符的统计信息。按子模块名称分组，然后按运算符名称分组。

by_operator(module_name: str = '') → Counter[str]¶

返回按操作符类型分组的请求模块的统计信息。操作符句柄决定了与每种操作符类型相关联的名称。

Parameters: module_name (str) – 要获取数据的子模块。默认为整个模型。
Returns: Counter(str) – 每个运算符的统计信息。

canonical_module_name(name: str) → str ¶

返回给定name的规范模块名称，如果模块是共享的，该名称可能与给定的name不同。这是在使用.by_module()和.by_module_and_operator()输出统计信息时将用作键的名称。

Parameters: name (str) – 要查找规范名称的模块名称。
Returns: str – 该模块的规范名称。

clear_op_handles() → fvcore.nn.jit_analysis.JitModelAnalysis¶: 清除当前设置的所有操作符句柄。

copy(new_model: Optional[torch.nn.Module] = None, new_inputs: Union[None, torch.Tensor, Tuple[torch.Tensor, …]] = None) → fvcore.nn.jit_analysis.JitModelAnalysis¶

返回一个JitModelAnalysis对象的副本，保留所有设置，但应用于新模型或新输入。

Parameters

new_model (nn.Module 或 None) - 用于新JitModelAnalysis的新模型。如果为None，则使用原始模型。
new_inputs (typing.Tuple[object, ..] or None) - 用于新JitModelAnalysis的新输入。如果为None，则使用原始输入。

Returns

JitModelAnalysis – 新型模型分析对象

set_op_handle(*args, **kwargs: Optional[Callable[[List[Any], List[Any]], Union[Counter[str], numbers.Number]]]) → fvcore.nn.jit_analysis.JitModelAnalysis¶

设置额外的操作符句柄，或替换现有的句柄。

Parameters

args – 操作符名称与处理函数的(str, Handle)键值对。
kwargs – 从操作符名称到句柄的映射。

如果句柄为None，则该操作将被显式忽略。否则，句柄应为一个用于计算算子所需统计量的函数。该函数必须接收两个参数，即算子的输入和输出，参数形式为list(torch._C.Value)。该函数应返回一个包含每个算子统计数据的计数器对象。

示例

handlers = {"aten::linear": my_handler}
counter.set_op_handle("aten::matmul", None, "aten::bmm", my_handler2)
       .set_op_handle(**handlers)

total(module_name: str = '') → int ¶

返回所请求模块中所有操作符的总体汇总统计信息。

Parameters: module_name (str) – 要获取数据的子模块。默认为整个模型。
Returns: int – 聚合统计量。

tracer_warnings(mode: str) → T¶

设置在图谱追踪计算统计量时打印哪些警告。共有三种模式，默认为'no_tracer_warning'。允许的值为：

'all' : 保留跟踪过程中产生的所有警告
'no_tracer_warning' : 仅抑制torch.jit.TracerWarning
'none' : 在追踪过程中抑制所有警告

Parameters: mode (str) – 警告模式，取上述值之一。

uncalled_modules() → Set[str]¶

返回一组在图形追踪过程中从未被调用的子模块。这可能是因为它们未被使用，或者是因为它们通过直接调用.forward()或其他Python方法访问。在后一种情况下，统计信息不会归属于该子模块，但这些统计信息仍会包含在父模块中。

Returns

set(str) –

在模型跟踪过程中从未被调用的子模块名称集合

uncalled_modules_warnings(enabled: bool) → T¶

设置是否显示未调用子模块的警告。默认为true。如果子模块在跟踪过程中从未被调用，则被视为“未调用”。这可能是因为它实际上未被使用，或者是因为它是通过调用.forward()或模块的其他方法来访问的。无论此设置如何，都可以从uncalled_modules()获取未调用模块的集合。

Parameters: enabled (bool) – 设置为'True'以显示警告。

unsupported_ops(module_name: str = '') → Counter[str]¶

列出遇到但因无可用操作符处理程序而不支持的运算符数量。不包括明确忽略的运算符。

Parameters: module_name (str) – 要列出不支持操作（ops）的子模块。默认为整个模型。
Returns: Counter(str) – 每个不受支持运算符的出现次数。

unsupported_ops_warnings(enabled: bool) → T¶

设置是否显示不支持的操作符警告。默认为True。无论此设置如何，都可以通过unsupported_ops()获取不支持的操作符计数。

Parameters: enabled (bool) – 设置为'True'以显示不支持的运算符警告。

fvcore.nn.sigmoid_focal_loss(inputs: torch.Tensor, targets: torch.Tensor, alpha: float = - 1, gamma: float = 2, reduction: str = 'none') → torch.Tensor [源代码]¶

RetinaNet用于密集检测的损失函数：https://arxiv.org/abs/1708.02002。 :param inputs: 任意形状的浮点张量。

每个示例的预测结果。

Parameters

targets –

一个与inputs形状相同的浮点张量。存储每个输入元素的二元
分类标签

(0表示负类，1表示正类)。
alpha – (可选) 取值范围在(0,1)之间的权重因子，用于平衡正负样本。默认值 = -1 (无权重)。
gamma – 调节因子(1 - p_t)的指数，用于平衡简单样本与困难样本。
reduction – 'none' | 'mean' | 'sum' 'none': 不对输出进行任何缩减。 'mean': 输出将被平均。 'sum': 输出将被求和。

Returns

应用了归约选项的损失张量。

fvcore.nn.sigmoid_focal_loss_star(inputs: torch.Tensor, targets: torch.Tensor, alpha: float = - 1, gamma: float = 1, reduction: str = 'none') → torch.Tensor [源代码]¶

RetinaNet论文附录中描述的FL*：https://arxiv.org/abs/1708.02002。 :param inputs: 任意形状的浮点张量。

每个示例的预测结果。

Parameters

targets –

一个与inputs形状相同的浮点张量。存储每个输入元素的二元
分类标签

(0表示负类，1表示正类)。
alpha – (可选) 范围在(0,1)之间的权重因子，用于平衡正负样本。默认值 = -1 (无权重)。
gamma – FL*中描述的Gamma参数。默认值为1（无权重）。
reduction – 'none' | 'mean' | 'sum' 'none': 不对输出应用任何缩减。 'mean': 输出将被平均。 'sum': 输出将被求和。

Returns

应用了归约选项的损失张量。

fvcore.nn.giou_loss(boxes1: torch.Tensor, boxes2: torch.Tensor, reduction: str = 'none', eps: float = 1e-07) → torch.Tensor [源代码]¶

广义交并比损失 (Hamid Rezatofighi 等人) https://arxiv.org/abs/1902.09630

梯度友好的IoU损失函数，额外添加了一个惩罚项：当边界框不重叠时该惩罚项非零，并随其最小外接框的尺寸变化。此损失函数是对称的，因此boxes1和boxes2参数可以互换使用。

Parameters

boxes1 (Tensor) - 以XYXY格式表示的框位置，形状为(N, 4)或(4,)。
boxes2 (Tensor) - 以XYXY格式表示的框位置，形状为(N, 4)或(4,)。
reduction – ‘none’ | ‘mean’ | ‘sum’ ‘none’: 不对输出进行任何缩减。 ‘mean’: 输出将被平均。 ‘sum’: 输出将被求和。
eps (float) – 防止除以零的小数值

fvcore.nn.parameter_count(model: torch.nn.Module) → DefaultDict[str, int][源代码]¶

统计模型及其子模块的参数数量。

Parameters: model – 一个torch模块
Returns: 字典（字符串->整数） - 键可以是参数名称或模块名称。值表示该参数中的元素数量，或该模块所有参数中的元素总数。键“”对应模型参数的总数。

fvcore.nn.parameter_count_table(model: torch.nn.Module, max_depth: int = 3) → str [源代码]¶

以美观的表格形式展示模型（及其子模块或参数）的参数数量。效果如下所示：

| name                            | #elements or shape   |
|:--------------------------------|:---------------------|
| model                           | 37.9M                |
|  backbone                       |  31.5M               |
|   backbone.fpn_lateral3         |   0.1M               |
|    backbone.fpn_lateral3.weight |    (256, 512, 1, 1)  |
|    backbone.fpn_lateral3.bias   |    (256,)            |
|   backbone.fpn_output3          |   0.6M               |
|    backbone.fpn_output3.weight  |    (256, 256, 3, 3)  |
|    backbone.fpn_output3.bias    |    (256,)            |
|   backbone.fpn_lateral4         |   0.3M               |
|    backbone.fpn_lateral4.weight |    (256, 1024, 1, 1) |
|    backbone.fpn_lateral4.bias   |    (256,)            |
|   backbone.fpn_output4          |   0.6M               |
|    backbone.fpn_output4.weight  |    (256, 256, 3, 3)  |
|    backbone.fpn_output4.bias    |    (256,)            |
|   backbone.fpn_lateral5         |   0.5M               |
|    backbone.fpn_lateral5.weight |    (256, 2048, 1, 1) |
|    backbone.fpn_lateral5.bias   |    (256,)            |
|   backbone.fpn_output5          |   0.6M               |
|    backbone.fpn_output5.weight  |    (256, 256, 3, 3)  |
|    backbone.fpn_output5.bias    |    (256,)            |
|   backbone.top_block            |   5.3M               |
|    backbone.top_block.p6        |    4.7M              |
|    backbone.top_block.p7        |    0.6M              |
|   backbone.bottom_up            |   23.5M              |
|    backbone.bottom_up.stem      |    9.4K              |
|    backbone.bottom_up.res2      |    0.2M              |
|    backbone.bottom_up.res3      |    1.2M              |
|    backbone.bottom_up.res4      |    7.1M              |
|    backbone.bottom_up.res5      |    14.9M             |
|    ......                       |    .....             |

Parameters

model – 一个torch模块
max_depth (int) – 递归打印子模块或参数的最大深度

Returns

str – 要打印的表格

fvcore.nn.get_bn_modules(model: torch.nn.Module) → List[torch.nn.Module][源代码]¶

找出所有处于训练模式的批归一化（BN）模块。有关此搜索包含的所有模块列表，请参阅 fvcore.precise_bn.BN_MODULE_TYPES。

Parameters: model (nn.Module) – 一个可能包含BN模块的模型。
Returns: list[nn.Module] – 模型中的所有BN模块。

fvcore.nn.update_bn_stats(model: torch.nn.Module, data_loader: Iterable[Any], num_iters: int = 200, progress: Optional[str] = None) → None [源代码]¶

重新计算并更新批归一化统计量以提高其精确度。在训练过程中，批归一化统计量和权重在每次迭代后都会发生变化，因此移动平均无法准确反映当前模型的实际统计量。此函数通过固定权重重新计算批归一化统计量，使移动平均更加精确。具体而言，它计算每批均值/方差的真实平均值，而非移动平均值。详情请参阅论文《重新思考批归一化中的批次》第3节。

Parameters

model (nn.Module) –
需要重新计算批量归一化统计数据的模型。

请注意：
1. 本函数不会改变给定模型的训练模式。用户需自行将需要精确批量归一化的层设置为训练模式，然后再调用此函数。
2. 如果模型除批量归一化外还包含其他有状态的层（即在前向迭代中状态可能发生变化的层），请谨慎使用。本函数会改变这些层的状态。如需保持其状态不变，您需要传入不包含这些层的子模块，或提前备份状态。
data_loader (iterator) - 一个迭代器。生成数据作为模型的输入。
num_iters (int) – 计算统计所需的迭代次数。
progress – 无或"tqdm"。如果设置，将使用tqdm来报告进度。

fvcore.nn.flop_count_str(flops: fvcore.nn.flop_count.FlopCountAnalysis, activations: Optional[fvcore.nn.activation_count.ActivationCountAnalysis] = None) → str [源代码]¶

计算模型在给定输入下的参数量和浮点运算次数，并返回一个包含每个子模块参数量和浮点运算次数的模型字符串表示。该字符串的结构类似于str(model)的输出，但如果模块的默认字符串表示已被重写，则不能保证形式完全相同。如果模块的参数量和浮点运算次数为零，为简洁起见将不显示统计信息。

追踪器只有在模块被直接调用时才能记录其作用范围，这意味着显式调用.forward()或模块的其他Python函数所产生的浮点运算（和激活）将不会被归因于该模块。从未被调用的模块将在其浮点运算统计中显示为"N/A"；这表明它们要么未被使用，要么由于这个原因缺少统计信息。任何此类浮点运算仍会被计入父模块。

示例：

>>> import torch
>>> import torch.nn as nn

>>> class InnerNet(nn.Module):
...     def __init__(self):
...         super().__init__()
...         self.fc1 = nn.Linear(10,10)
...         self.fc2 = nn.Linear(10,10)
...     def forward(self, x):
...         return self.fc1(self.fc2(x))

>>> class TestNet(nn.Module):
...     def __init__(self):
...         super().__init__()
...         self.fc1 = nn.Linear(10,10)
...         self.fc2 = nn.Linear(10,10)
...         self.inner = InnerNet()
...     def forward(self, x):
...         return self.fc1(self.fc2(self.inner(x)))

>>> inputs = torch.randn((1,10))
>>> print(flop_count_str(FlopCountAnalysis(model, inputs)))
TestNet(
  #params: 0.44K, #flops: 0.4K
  (fc1): Linear(
    in_features=10, out_features=10, bias=True
    #params: 0.11K, #flops: 100
  )
  (fc2): Linear(
    in_features=10, out_features=10, bias=True
    #params: 0.11K, #flops: 100
  )
  (inner): InnerNet(
    #params: 0.22K, #flops: 0.2K
    (fc1): Linear(
      in_features=10, out_features=10, bias=True
      #params: 0.11K, #flops: 100
    )
    (fc2): Linear(
      in_features=10, out_features=10, bias=True
      #params: 0.11K, #flops: 100
    )
  )
)

Parameters

flops (FlopCountAnalysis) – 浮点运算计数对象
activations (bool) - 如果提供，每层的激活值也将被计算并包含在表示中。

Returns

str – 包含参数数量和浮点运算次数的模型字符串表示。

fvcore.nn.flop_count_table(flops: fvcore.nn.flop_count.FlopCountAnalysis, max_depth: int = 3, activations: Optional[fvcore.nn.activation_count.ActivationCountAnalysis] = None, show_param_shapes: bool = True) → str [源代码]¶

将模型的每个模块参数和浮点运算次数(FLOPs)格式化为表格形式。显示效果如下所示：

| model                            | #parameters or shape   | #flops    |
|:---------------------------------|:-----------------------|:----------|
| model                            | 34.6M                  | 65.7G     |
|  s1                              |  15.4K                 |  4.32G    |
|   s1.pathway0_stem               |   9.54K                |   1.23G   |
|    s1.pathway0_stem.conv         |    9.41K               |    1.23G  |
|    s1.pathway0_stem.bn           |    0.128K              |           |
|   s1.pathway1_stem               |   5.9K                 |   3.08G   |
|    s1.pathway1_stem.conv         |    5.88K               |    3.08G  |
|    s1.pathway1_stem.bn           |    16                  |           |
|  s1_fuse                         |  0.928K                |  29.4M    |
|   s1_fuse.conv_f2s               |   0.896K               |   29.4M   |
|    s1_fuse.conv_f2s.weight       |    (16, 8, 7, 1, 1)    |           |
|   s1_fuse.bn                     |   32                   |           |
|    s1_fuse.bn.weight             |    (16,)               |           |
|    s1_fuse.bn.bias               |    (16,)               |           |
|  s2                              |  0.226M                |  7.73G    |
|   s2.pathway0_res0               |   80.1K                |   2.58G   |
|    s2.pathway0_res0.branch1      |    20.5K               |    0.671G |
|    s2.pathway0_res0.branch1_bn   |    0.512K              |           |
|    s2.pathway0_res0.branch2      |    59.1K               |    1.91G  |
|   s2.pathway0_res1.branch2       |   70.4K                |   2.28G   |
|    s2.pathway0_res1.branch2.a    |    16.4K               |    0.537G |
|    s2.pathway0_res1.branch2.a_bn |    0.128K              |           |
|    s2.pathway0_res1.branch2.b    |    36.9K               |    1.21G  |
|    s2.pathway0_res1.branch2.b_bn |    0.128K              |           |
|    s2.pathway0_res1.branch2.c    |    16.4K               |    0.537G |
|    s2.pathway0_res1.branch2.c_bn |    0.512K              |           |
|   s2.pathway0_res2.branch2       |   70.4K                |   2.28G   |
|    s2.pathway0_res2.branch2.a    |    16.4K               |    0.537G |
|    s2.pathway0_res2.branch2.a_bn |    0.128K              |           |
|    s2.pathway0_res2.branch2.b    |    36.9K               |    1.21G  |
|    s2.pathway0_res2.branch2.b_bn |    0.128K              |           |
|    s2.pathway0_res2.branch2.c    |    16.4K               |    0.537G |
|    s2.pathway0_res2.branch2.c_bn |    0.512K              |           |
|    ............................. |    ......              |    ...... |

Parameters

flops (FlopCountAnalysis) – 浮点运算计数对象
max_depth (int) – 表格中包含的子模块最大深度。默认为3。
activations (ActivationCountAnalysis 或 None) - 如果提供，将激活计数作为表格中的附加列包含。
show_param_shapes (bool) - 如果为True，参数形状将被包含在表格中。默认为True。

Returns

str - 格式化后的表格。

示例：

print(flop_count_table(FlopCountAnalysis(model, inputs)))

fvcore.nn.smooth_l1_loss(input: torch.Tensor, target: torch.Tensor, beta: float, reduction: str = 'none') → torch.Tensor [源代码]¶

在Fast R-CNN论文中定义的平滑L1损失函数：

              | 0.5 * x ** 2 / beta   if abs(x) < beta
smoothl1(x) = |
              | abs(x) - 0.5 * beta   otherwise,

其中 x = 输入 - 目标。

Smooth L1损失与Huber损失相关，其定义为：

           | 0.5 * x ** 2                  if abs(x) < beta
huber(x) = |
           | beta * (abs(x) - 0.5 * beta)  otherwise

平滑L1损失等同于huber(x)/beta。这会导致以下差异：

当 beta 趋近于 0 时，Smooth L1 损失会收敛为 L1 损失，而 Huber 损失会收敛为恒定的 0 损失。

当 beta 趋近于正无穷时，Smooth L1 收敛为一个恒定的 0 损失，而 Huber 损失收敛为 L2 损失。

对于Smooth L1损失函数，当beta变化时，损失函数的L1段保持恒定的斜率为1。而对于Huber损失函数，L1段的斜率则为beta。

平滑L1损失可以视为精确的L1损失，但将abs(x) < beta的部分替换为二次函数，使得在abs(x) = beta处其斜率为1。这个二次函数段在x=0附近平滑了L1损失。

Parameters

input (Tensor) - 任意形状的输入张量
target (Tensor) - 与输入形状相同的目标值张量
beta (float) - L1到L2的转换点。当beta值小于1e-5时，将计算L1损失。
reduction – ‘none’ | ‘mean’ | ‘sum’ ‘none’: 不对输出进行任何缩减。 ‘mean’: 输出将被平均。 ‘sum’: 输出将被求和。

Returns

应用了缩减选项后的损失值。

注意

PyTorch’s builtin “Smooth L1 loss” implementation does not actually implement Smooth L1 loss, nor does it implement Huber loss. It implements the special case of both in which they are equal (beta=1). See: https://pytorch.org/docs/stable/nn.html#torch.nn.SmoothL1Loss.

fvcore.nn.c2_msra_fill(module: torch.nn.Module) → None [源代码]¶

使用Caffe2中实现的"MSRAFill"初始化module.weight。同时将module.bias初始化为0。

Parameters: module (torch.nn.Module) – 要初始化的模块。

fvcore.nn.c2_xavier_fill(module: torch.nn.Module) → None [源代码]¶

使用Caffe2中实现的"XavierFill"初始化module.weight。同时将module.bias初始化为0。

Parameters: 模块 (torch.nn.Module) – 需要初始化的模块。

fvcore.common¶

class fvcore.common.checkpoint.Checkpointer(model: torch.nn.Module, save_dir: str = '', *, save_to_disk: bool = True, **checkpointables: Any)[源代码]¶

基类: object

一个可以保存/加载模型以及其他可检查点对象的检查点工具。

__init__(model: torch.nn.Module, save_dir: str = '', *, save_to_disk: bool = True, **checkpointables: Any) → None [源代码]¶

Parameters

model (nn.Module) – 模型。
save_dir (str) – 用于保存和查找检查点的目录。
save_to_disk (bool) - 如果为True，则将检查点保存到磁盘，否则禁用此检查点的保存功能。
checkpointables (object) – 任何可检查点对象，即具有state_dict()和load_state_dict()方法的对象。例如，可以像Checkpointer(model, "dir", optimizer=optimizer)这样使用。

add_checkpointable(key: str, checkpointable: Any) → None [源代码]¶

为这个检查点跟踪器添加可检查点对象。

Parameters

key (str) - 用于保存对象的键
checkpointable - 任何具有state_dict()和 load_state_dict()方法的对象

save(name: str, **kwargs: Any) → None [源代码]¶

将模型和可检查点内容转储到文件。

Parameters

name (str) – 文件名。
kwargs (dict) - 要保存的额外任意数据。

load(path: str, checkpointables: Optional[List[str]] = None) → Dict[str, Any][源代码]¶

从给定的检查点加载。

Parameters

path (str) – 检查点(checkpoint)的路径或URL。如果为空，则不会加载任何内容。
checkpointables (list) - 要加载的可检查点名称列表。如果未指定（None），将加载所有可能的可检查点。

Returns

dict – 从检查点加载的未处理的额外数据。例如，那些通过save(**extra_data)()保存的数据。

has_checkpoint() → bool [源代码]¶

Returns: bool - 目标目录中是否存在检查点。

get_checkpoint_file() → str [源代码]¶

Returns: str - 目标目录中最新的检查点文件。

get_all_checkpoint_files() → List[str][源代码]¶

Returns

列表 –

目标目录中所有可用的检查点文件(.pth文件): 目录。

resume_or_load(path: str, *, resume: bool = True) → Dict[str, Any][源代码]¶

如果resume为True，该方法会尝试从最后一个检查点恢复（如果存在）。否则，从给定路径加载检查点。这在重新启动中断的训练任务时非常有用。

Parameters

path (str) – 检查点文件的路径。
resume (bool) - 如果为True，则从最后一个检查点恢复（如果存在）并加载模型以及所有可检查点内容。否则仅加载模型而不加载任何可检查点内容。

Returns

与 load() 相同。

tag_last_checkpoint(last_filename_basename: str) → None [源代码]¶

标记最后一个检查点。

Parameters: last_filename_basename (str) – 最后一个文件名的基本名称。

class fvcore.common.checkpoint.PeriodicCheckpointer(checkpointer: fvcore.common.checkpoint.Checkpointer, period: int, max_iter: Optional[int] = None, max_to_keep: Optional[int] = None, file_prefix: str = 'model')[源代码]¶

基类: object

定期保存检查点。当调用.step(iteration)时，如果迭代次数是周期的整数倍或达到max_iter，它将在给定的检查点上执行checkpointer.save。

checkpointer¶

底层检查点对象

Type: Checkpointer

__init__(checkpointer: fvcore.common.checkpoint.Checkpointer, period: int, max_iter: Optional[int] = None, max_to_keep: Optional[int] = None, file_prefix: str = 'model') → None [源代码]¶

Parameters

checkpointer – 用于保存检查点的检查点对象。
period (int) - 保存检查点的周期。
max_iter (int) – 最大迭代次数。达到该值时，将保存名为"{file_prefix}_final"的检查点。
max_to_keep (int) – 要保留的最新检查点的最大数量，之前的检查点将被删除
file_prefix (str) – 检查点文件名的前缀

step(iteration: int, **kwargs: Any) → None [源代码]¶

在给定的迭代中执行适当的操作。

Parameters

iteration (int) – 当前迭代次数，范围在[0, max_iter-1]之间。
kwargs (Any) – 要保存的额外数据，与 Checkpointer.save()中的相同。

save(name: str, **kwargs: Any) → None [源代码]¶

参数与Checkpointer.save()相同。使用此方法可在计划外手动保存检查点。

Parameters

name (str) – 文件名。
kwargs (Any) – 要保存的额外数据，与 Checkpointer.save()中的相同。

class fvcore.common.config.CfgNode(init_dict=None, key_list=None, new_allowed=False)[源代码]¶

基类: yacs.config.CfgNode

我们自己对yacs.config.CfgNode的扩展版本。它包含以下额外功能：

merge_from_file() 方法支持 "_BASE_" 键，它允许新的 CfgNode 从基础配置文件中继承所有属性。
以“COMPUTED_”开头的键被视为仅插入的"计算"属性。无论CfgNode是否被冻结，都可以插入这些属性。
当设置“allow_unsafe=True”时，该功能支持评估配置中表达式的pyyaml标签。示例参见https://pyyaml.org/wiki/PyYAMLDocumentation#yaml-tags-and-python-types。请注意这可能导致任意代码执行：在手动检查文件内容前，切勿加载来自不可信源的配置文件。

classmethod load_yaml_with_base(filename: str, allow_unsafe: bool = False) → Dict[str, Any][源代码]¶

Just like yaml.load(open(filename)), but inherit attributes from its: _BASE_.

Parameters

filename (str 或 类文件对象) – 当前配置的文件名或文件。将用于查找基础配置文件。
allow_unsafe (bool) – 是否允许使用yaml.unsafe_load加载配置文件。

Returns

(字典) – 加载的yaml文件

merge_from_file(cfg_filename: str, allow_unsafe: bool = False) → None [源代码]¶

从给定的yaml文件合并配置。

Parameters

cfg_filename – yaml配置文件的文件名。
allow_unsafe – 是否允许使用yaml.unsafe_load加载配置文件。

merge_from_other_cfg(cfg_other: fvcore.common.config.CfgNode) → Callable[], None][源代码]¶

Parameters: cfg_other (CfgNode) – 要合并的配置。

merge_from_list(cfg_list: List[str]) → Callable[], None][源代码]¶

Parameters: cfg_list (list) – 要合并的配置列表。

class fvcore.common.history_buffer.HistoryBuffer(max_length: int = 1000000)[源代码]¶

基类: object

跟踪一系列标量值，并提供对滑动窗口平滑值或序列全局平均值的访问。

__init__(max_length: int = 1000000) → None [源代码]¶

Parameters: max_length – 缓冲区可存储的最大值数量。当缓冲区容量耗尽时，旧值将被移除。

update(value: float, iteration: Optional[float] = None) → None [源代码]¶: 添加在特定迭代中产生的新标量值。如果缓冲区的长度超过self._max_length，最旧的元素将从缓冲区中移除。

latest() → float [源代码]¶: 返回添加到缓冲区的最新标量值。

median(window_size: int) → float [源代码]¶: 返回缓冲区中最近window_size个数值的中位数。

avg(window_size: int) → float [源代码]¶: 返回缓冲区中最近window_size个值的平均值。

global_avg() → float [源代码]¶: 返回缓冲区中所有元素的平均值。请注意，这包括由于缓冲区存储空间有限而被移除的元素。

values() → List[Tuple[float, float]][源代码]¶

Returns: list[(number, iteration)] – 当前缓冲区的内容。

class fvcore.common.param_scheduler.ParamScheduler[源代码]¶

基类: object

参数调度器的基类。参数调度器定义了从[0, 1)范围内的进度值到某个数值(例如学习率)的映射关系。

WHERE_EPSILON = 1e-06¶

__call__(where: float) → float [源代码]¶

获取训练时给定点的参数值。

我们根据训练完成的进度百分比更新参数（如学习率）。这使得调度器无需关心具体运行的精确长度（例如120个周期与90个周期），只要参数应更新的相对进度相同即可。不过，这假设训练的总长度是已知的。

Parameters: where – 一个介于[0,1)之间的浮点数，表示训练进度

class fvcore.common.param_scheduler.ConstantParamScheduler(value: float)[源代码]¶

基类: fvcore.common.param_scheduler.ParamScheduler

返回参数的常量值。

WHERE_EPSILON = 1e-06¶

class fvcore.common.param_scheduler.CosineParamScheduler(start_value: float, end_value: float)[源代码]¶

基类: fvcore.common.param_scheduler.ParamScheduler

基于起始值和结束值的余弦衰减或余弦预热调度方案。该调度方案根据训练进度的比例进行更新。该方案在《SGDR: 带热重启的随机梯度下降》(https://arxiv.org/abs/1608.03983)中提出。请注意，这个类仅实现了SGDR中的余弦退火部分，而不包含重启功能。

示例

CosineParamScheduler(start_value=0.1, end_value=0.0001)

WHERE_EPSILON = 1e-06¶

class fvcore.common.param_scheduler.ExponentialParamScheduler(start_value: float, decay: float)[源代码]¶

基类: fvcore.common.param_scheduler.ParamScheduler

由起始值和衰减参数化的指数调度方案。该调度方案根据训练进度的比例where进行更新，计算公式为param_t = start_value * (decay ** where)。

示例

对应一个递减的调度计划，其值范围在[2.0, 0.04)之间。

WHERE_EPSILON = 1e-06¶

class fvcore.common.param_scheduler.LinearParamScheduler(start_value: float, end_value: float)[源代码]¶

基类: fvcore.common.param_scheduler.ParamScheduler

在start_value和end_value之间对参数进行线性插值。根据起始值和结束值，既可用于预热也可用于衰减。默认情况下，该调度会在每次训练步骤后更新。

示例

LinearParamScheduler(start_value=0.0001, end_value=0.01)

对应一个线性递增的计划，取值范围在[0.0001, 0.01)之间

WHERE_EPSILON = 1e-06¶

class fvcore.common.param_scheduler.CompositeParamScheduler(schedulers: Sequence[fvcore.common.param_scheduler.ParamScheduler], lengths: List[float], interval_scaling: Sequence[str])[源代码]¶

基类: fvcore.common.param_scheduler.ParamScheduler

由中间调度器组成的复合参数调度器。接收一个调度器列表和一个对应每个调度器运行训练时长百分比的长度列表。调度器按顺序运行。长度列表中的所有值之和应为1.0。

每个调度器还对应一个间隔比例参数。如果间隔比例设为'fixed'，中间调度器运行时不会对时间进行任何重新缩放。如果间隔比例设为'rescaled'，中间调度器运行时将确保每个调度器的起止值与单独运行时保持一致。所有调度器的默认设置均为'rescaled'。

示例

schedulers = [
  ConstantParamScheduler(value=0.42),
  CosineParamScheduler(start_value=0.42, end_value=1e-4)
]
CompositeParamScheduler(
  schedulers=schedulers,
  interval_scaling=['rescaled', 'rescaled'],
  lengths=[0.3, 0.7])

参数值在前[0%, 30%)的训练步骤中为0.42，然后在[30%, 100%)的训练过程中将从0.42余弦衰减至0.0001。

WHERE_EPSILON = 1e-06¶

class fvcore.common.param_scheduler.MultiStepParamScheduler(values: List[float], num_updates: Optional[int] = None, milestones: Optional[List[int]] = None)[源代码]¶

基类: fvcore.common.param_scheduler.ParamScheduler

接收一个预定义的参数值调度表，以及一组代表每个范围上限（不包含）的轮次或步骤列表。

示例

MultiStepParamScheduler(
  values=[0.1, 0.01, 0.001, 0.0001],
  milestones=[30, 60, 80, 120]
)

那么参数值将在0-29周期时为0.1，30-59周期时为0.01，60-79周期时为0.001，80-120周期时为0.0001。请注意，值的长度必须等于里程碑长度加一。

__init__(values: List[float], num_updates: Optional[int] = None, milestones: Optional[List[int]] = None) → None [源代码]¶

Parameters

values – 每个范围内的参数值
num_updates – 最后一个范围的结束。如果为None，将使用milestones[-1]
milestones - 每个区间的边界值。如果为None，则会均匀分割num_updates

例如，以下所有组合都定义了相同的调度器：

更新次数=90，里程碑=[30, 60]，数值=[1, 0.1, 0.01]
更新次数=90, 数值=[1, 0.1, 0.01]
里程碑=[30, 60, 90], 值=[1, 0.1, 0.01]
里程碑=[3, 6, 9], 数值=[1, 0.1, 0.01] (参数调度器具有尺度不变性)

WHERE_EPSILON = 1e-06¶

class fvcore.common.param_scheduler.StepParamScheduler(num_updates: Union[int, float], values: List[float])[源代码]¶

基类: fvcore.common.param_scheduler.ParamScheduler

为参数值采用固定调度表。如果固定调度表的长度小于周期数，则这些周期将在参数调度表中均匀分配。默认情况下，每次训练周期后都会更新调度表。

示例

StepParamScheduler(values=[0.1, 0.01, 0.001, 0.0001], num_updates=120)

那么参数值将在0-29周期时为0.1，30-59周期时为0.01，60-89周期时为0.001，90-119周期时为0.0001。

WHERE_EPSILON = 1e-06¶

class fvcore.common.param_scheduler.StepWithFixedGammaParamScheduler(base_value: float, num_decays: int, gamma: float, num_updates: int)[源代码]¶

基类: fvcore.common.param_scheduler.ParamScheduler

按照相等的步数衰减参数值gamma，以达到指定的总衰减次数。

示例

StepWithFixedGammaParamScheduler(
  base_value=0.1, gamma=0.1, num_decays=3, num_updates=120)

那么参数值将在0-29周期时为0.1，30-59周期时为0.01，60-89周期时为0.001，90-119周期时为0.0001。

WHERE_EPSILON = 1e-06¶

class fvcore.common.param_scheduler.PolynomialDecayParamScheduler(base_value: float, power: float)[源代码]¶

基类: fvcore.common.param_scheduler.ParamScheduler

根据一个固定幂次的多项式函数，在每个训练周期后衰减参数值。默认情况下，该调度会在每个训练步骤后更新。

示例

PolynomialDecayParamScheduler(base_value=0.1, power=0.9)

那么参数值在第0轮时为0.1，第1轮时为0.099，依此类推。

WHERE_EPSILON = 1e-06¶

class fvcore.common.registry.Registry(*args, **kwds)[源代码]¶

基类: collections.abc.Iterable, typing.Generic

提供名称到对象映射的注册表，以支持第三方用户的自定义模块。

要创建一个注册表（例如骨干网络注册表）：

BACKBONE_REGISTRY = Registry('BACKBONE')

注册一个对象：

@BACKBONE_REGISTRY.register()
class MyBackbone():
    ...

或者：

BACKBONE_REGISTRY.register(MyBackbone)

__init__(name: str) → None [源代码]¶

Parameters: name (str) – 该注册表的名称

register(obj: Any = None) → Any[源代码]¶: 将给定对象以名称obj.__name__进行注册。可用作装饰器或非装饰器。使用方法请参阅本类的文档字符串。

get(name: str) → Any[源代码]¶

class fvcore.common.timer.Timer[源代码]¶

基类: object

一个计时器，用于计算自计时器启动/重置以来经过的时间。

reset() → None [源代码]¶: 重置计时器。

pause() → None [源代码]¶: 暂停计时器。

is_paused() → bool [源代码]¶

Returns: bool - 计时器当前是否处于暂停状态

resume() → None [源代码]¶: 恢复计时器。

seconds() → float [源代码]¶

Returns

(浮点数) –

自计时器启动/重置以来的总秒数，: 不包括计时器暂停的时间。

avg_seconds() → float [源代码]¶

Returns: (float) - 每次启动/重置与暂停之间的平均秒数。