自由维度覆盖

ONNX 模型通过自由维度支持动态输入形状。自由维度允许模型在该维度上接受不同大小的输入。例如，输入形状为 [batch, 3, height, width] 的模型可以处理任意数量、任意尺寸的 RGB 图像（3 个通道）。

虽然这很灵活，但当你的应用使用一致的输入尺寸时，可以通过固定这些维度来优化性能。例如，如果你的 WebNN 应用始终只处理单张 224×224 的图像，就可以使用 freeDimensionOverrides 选项，将自由维度从 [batch, 3, height, width] 覆盖为 [1, 3, 224, 224]。该配置会把输入维度锁定为特定值，从而有可能提升模型性能。

在 Transformers.js 3.5.0+ 中设置自由维度覆盖

在 Transformers.js  3.5.0 或更高版本中处理动态形状时，你可以通过以下方法之一指定自由维度覆盖，按优先级排列：

1. 直接在代码中使用 freeDimensionOverrides
2. 在模型的 config.json 文件中，transformers.js_config 的 device_config 层级
3. 在模型的 config.json 文件中，transformers.js_config 的模型层级

将使用第一个提供了有效覆盖的方法，靠前的方法优先于靠后的方法。

优先级 1

在代码中通过 Transformers.js 设置 freeDimensionOverrides。

import * as transformers from '@huggingface/transformers';
 
const path = 'Xenova/resnet-50';
const options = {
  device: "webnn-gpu", // webnn, webnn-cpu, webnn-npu
  dtype: "fp32",
  session_options: {
    freeDimensionOverrides: {
      batch: 1,
      height: 224,
      width: 224
    }
  }
}
 
const classifier = await transformers.pipeline('image-classification', path, options);

优先级 2

在 Hugging Face 模型的 config.json 文件中，将 free_dimension_overrides 设置在 transformers.js_config 的 device_config 层级，例如 Xenova/mobileclip_s0 

{
  "transformers.js_config": {
    "device_config": {
      "webnn-gpu": {
        "dtype": "fp16",
        "free_dimension_overrides": {
          "batch": 1,
          "height": 224,
          "width": 224
        }
      }
    }
  }
}

优先级 3

在 Hugging Face 模型的 config.json 文件中，将 free_dimension_overrides 设置在 transformers.js_config 的模型层级，例如 Xenova/mobileclip_s0 

{
  "transformers.js_config": {
    "device": "webnn-gpu",
    "dtype": "fp16",
    "free_dimension_overrides": {
      "batch": 1,
      "height": 224,
      "width": 224
    }
  }
}

符号维度

没有符号维度的示例模型

带有三个符号维度的示例模型，名称分别为 batch_size、height 和 width

WebNN 执行提供程序需要通过 freeDimensionOverrides 为所有符号维度指定固定的整数值，以避免回退。

其他资源

• Transformers.js - Free dimension overrides - Support device-level configuration across all devices