设备、dtype 与量化选择 ​

1. dtype 与文件名后缀 ​

utils/dtypes.js 将逻辑 dtype 映射到 ONNX 文件名后缀，例如：

• fp32 → 无后缀（model.onnx）；
• q8 → _quantized（model_quantized.onnx）；
• q4 → _q4；
• fp16 → _fp16。

export const DATA_TYPES = Object.freeze({
    auto: 'auto',
    fp32: 'fp32',
    fp16: 'fp16',
    q8: 'q8',
    ...
    q4: 'q4',
    ...
});
...
export const DEFAULT_DTYPE_SUFFIX_MAPPING = Object.freeze({
    [DATA_TYPES.fp32]: '',
    [DATA_TYPES.fp16]: '_fp16',
    ...
    [DATA_TYPES.q8]: '_quantized',
    [DATA_TYPES.q4]: '_q4',

依据：Hub 上同一架构常 多份 ONNX，用后缀约定实现 单一 API 切换精度/量化。

2. 设备默认 dtype：wasm → q8 ​

DEFAULT_DEVICE_DTYPE_MAPPING 对 wasm 默认 q8，其余未指定时多为 fp32。这与 WASM 算力与内存 相匹配：量化显著减小模型体积与内存带宽。

3. selectDtype：auto、按文件覆盖、回退 ​

• 支持 字符串 或 按 onnx 文件名映射的对象（多 session 模型常用）；
• auto 时读 config 里的 transformers.js_config.dtype 等；
• 找不到键时回退 设备默认 并可 warn 提示。

4. WebGPU fp16 能力探测 ​

使用 navigator.gpu.requestAdapter() 检查 shader-f16 feature；不支持则 直接抛错（与半精度内核相关）。代码中引用 ORT PR 讨论，表明这是 随 ORT/WebGPU 演进 的区域。

export const isWebGpuFp16Supported = (function () {
    ...
    return async function () {
        if (cachedResult === undefined) {
            ...
                try {
                    const adapter = await navigator.gpu.requestAdapter();
                    cachedResult = adapter.features.has('shader-f16');

5. session.js 中的设备与 KV cache dtype ​

getSession 内：

• selectDevice 解析 options.device 与 config['transformers.js_config']；
• kv_cache_dtype 可设为 float32 / float16（多量化权重仍用 fp16/fp32 存 KV 是常见策略）；
• WebNN 若未配置 free_dimension_overrides 会 warn（动态 shape 支持不完善时性能差）。

6. WebGPU：preferredOutputLocation ​

当启用 cache 配置且设备为 webgpu 时，对 present.* 输出设置 gpu-buffer，减少 GPU↔CPU 往返，利于自回归生成。

if (cache_config && selectedDevice === 'webgpu' && kv_cache_dtype_config !== false) {
        const shapes = getCacheShapes(options.config, {
            prefix: 'present',
            session_name,
        });
        if (Object.keys(shapes).length > 0 && !isONNXProxy()) {
            const preferredOutputLocation = {};
            for (const key in shapes) {
                preferredOutputLocation[key] = 'gpu-buffer';
            }
            session_options.preferredOutputLocation = preferredOutputLocation;
        }
    }

7. 优化手段（可落地） ​

下一篇：PreTrainedModel、生成与 KV Cache