Transformers.js v4 ModelRegistry 完整指南：在 pipeline 加载前掌控模型资源预检与缓存管理

本指南深入讲解 Transformers.js v4 新增的 ModelRegistry 预检 API。它能够在调用 pipeline() 之前，先解析模型所需的全部文件、估算下载体积、查询缓存状态并精确清理缓存，是构建可预期加载体验（下载估算、离线优先、带宽可控）的关键能力。读完本文，你将掌握 ModelRegistry 的五个核心方法、推荐工作流与离线门控等实战模式，并理解它与 env 配置、progress_callback 的协作方式。

本文基于当前仓库 skills/transformers-js/references/MODEL_REGISTRY.md 编写，并融合同目录下 PIPELINE_OPTIONS.md、CONFIGURATION.md、CACHE.md 与 SKILL.md 中的相关说明。该 Skill 对应的核心项目为 Hugging Face 官方 Transformers.js 库，覆盖浏览器与 Node.js、Bun、Deno 等运行时。

为什么需要 ModelRegistry：从"黑盒加载"到"可预期加载"

在 Transformers.js v4 之前，调用 pipeline(task, modelId, options) 时，模型资源的发现、下载与缓存完全发生在库内部：用户只知道"加载完成或报错"，无法提前知道会下载哪些文件、总共多大、是否已缓存、是否重复占带宽。

ModelRegistry 为模型资产提供了一套 preflight（预检）API，让你在真正调用 pipeline() 之前就能够：

• 检查初始化该 pipeline 所需的文件清单；
• 估算总下载体积，提前给出准确的下载提示；
• 检查所需文件是否已在缓存中，支撑 offline-first 流程；
• 精确清除某个 pipeline 元组对应的缓存资产，避免误删其他模型；
• 查询模型可用的精度/量化格式，动态选择最优运行配置。

正如 SKILL.md 中"ModelRegistry (v4)"一节所总结的：ModelRegistry 让你在加载 pipeline 之前获得模型资产的可见性与控制力——估算下载体积、检查缓存状态、查看可用 dtype、清理指定 task/model/options 元组对应的缓存产物。

基本用法：与 pipeline() 一致的 task/model/options 三元组

ModelRegistry 从 @huggingface/transformers 导入，并且与 pipeline() 使用完全相同的 task、modelId 与 options 参数：

import { ModelRegistry } from '@huggingface/transformers';

典型的三元组如下：

const task = 'feature-extraction';
const modelId = 'onnx-community/all-MiniLM-L6-v2-ONNX';
const modelOptions = { dtype: 'fp32' };

这意味着：你在 pipeline() 里怎么写，就照原样传给 ModelRegistry，预检结果与真实加载行为一致。modelOptions 中像 dtype 这样的字段会直接影响文件解析结果（不同量化精度对应不同的 ONNX 权重文件），因此预检与加载必须保持同一份参数。

核心 API 详解

ModelRegistry 共提供五个核心方法，下面逐一说明其签名、返回值与适用场景。

1. get_pipeline_files(task, modelId, modelOptions)：解析文件清单

返回初始化该 pipeline 配置所需的全部文件列表：

const files = await ModelRegistry.get_pipeline_files(task, modelId, modelOptions);
// 示例返回：['config.json', 'onnx/model.onnx', 'tokenizer.json', ...]

返回值是一个字符串数组，其中既包含模型权重文件，也包含配置与分词器文件。例如一个特征提取（feature-extraction）任务通常需要 config.json、tokenizer.json、tokenizer_config.json 以及 onnx/ 目录下的权重文件；具体清单取决于任务类型与模型仓库结构。

核心用途：构建预检检查与下载清单（download manifest），例如在 UI 上列出"即将下载 N 个文件"。

2. get_file_metadata(modelId, file)：获取单文件元数据

返回单个文件的元数据（可用时包含文件大小）：

const metadata = await ModelRegistry.get_file_metadata(modelId, 'onnx/model.onnx');
console.log(metadata);

将文件清单与元数据结合，即可计算总传输体积、识别体积最大的构件。这是实现"准确的下载估算"的基础能力。

3. is_pipeline_cached(task, modelId, modelOptions)：检查缓存状态

检查指定 pipeline 元组所需的文件是否已全部存在于缓存中：

const cached = await ModelRegistry.is_pipeline_cached(task, modelId, modelOptions);
console.log(cached ? 'Ready offline' : 'Needs download');

返回布尔值。核心用途：作为离线模式的开关依据，以及跳过不必要的预下载步骤。

4. clear_pipeline_cache(task, modelId, modelOptions)：清除指定元组缓存

清除特定 pipeline 元组对应的缓存资产：

await ModelRegistry.clear_pipeline_cache(task, modelId, modelOptions);

核心用途：缓存失效（invalidation）、测试环境重置、空间回收。它只删除与该三元组匹配的缓存项，不会波及其他模型，这一点在下面的实战示例中会进一步展开。

5. get_available_dtypes(modelId)：查询可用精度/量化格式

返回该模型可用的精度与量化格式：

const dtypes = await ModelRegistry.get_available_dtypes(modelId);
// 示例返回：['fp32', 'fp16', 'q4', 'q4f16']

核心用途：根据运行环境（CPU/GPU、内存、带宽）动态选择最优运行时画像，在"质量 vs 速度 vs 内存"之间做取舍。关于各 dtype 的含义，可对照 PIPELINE_OPTIONS.md 中数据类型的说明：fp32 全精度（最大、最准）、fp16 半精度、q8 8 位量化（体积小、速度快）、q4 4 位量化（体积最小、速度最快）。

推荐工作流：构建稳健的加载体验

要让加载过程对用户完全可预期，建议按以下 6 步组织流程：

1. 解析并确定最终的 task/model/options 三元组；
2. 调用 get_pipeline_files(...) 获取文件清单；
3. 逐个文件获取元数据，计算总大小；
4. 调用 is_pipeline_cached(...) 判断是否已缓存；
5. 若未缓存，向用户展示体积与进度预期；
6. 通过 pipeline(...) 加载，并在 progress_callback 中使用 progress_total 事件回报总体进度。

下面是一段完整、可直接运行的实现：

import { ModelRegistry, pipeline } from '@huggingface/transformers';

const task = 'feature-extraction';
const modelId = 'onnx-community/all-MiniLM-L6-v2-ONNX';
const modelOptions = { dtype: 'q8' };

// 第 2 步：解析文件清单
const files = await ModelRegistry.get_pipeline_files(task, modelId, modelOptions);

// 第 3 步：并行获取元数据并累计体积
const metadata = await Promise.all(
  files.map((file) => ModelRegistry.get_file_metadata(modelId, file))
);

const totalBytes = metadata.reduce((sum, item) => sum + (item?.size ?? 0), 0);
const totalMB = (totalBytes / 1024 / 1024).toFixed(2);

// 第 4 步：检查缓存
const cached = await ModelRegistry.is_pipeline_cached(task, modelId, modelOptions);
console.log({ fileCount: files.length, totalMB, cached });

// 第 6 步：加载 pipeline，并用 progress_total 汇报总体进度
const pipe = await pipeline(task, modelId, {
  ...modelOptions,
  progress_callback: (info) => {
    if (info.status === 'progress_total') {
      console.log(`Loading: ${info.progress.toFixed(1)}%`);
    }
  },
});

await pipe.dispose();

注意最后调用了 pipe.dispose()——SKILL.md 强调，所有 pipeline 在使用完毕后必须释放，以回收内存（单个模型可能占用 100MB 到数 GB 资源），这是避免内存泄漏的关键习惯。

关于 progress_total 的补充

在上面的工作流中，第 6 步依赖 progress_callback 与 progress_total 事件。参照 PIPELINE_OPTIONS.md 的定义，ProgressInfo 的 status 可能取值为 'initiate' | 'download' | 'progress' | 'progress_total' | 'done' | 'ready'，其中：

• progress_total：端到端的总进度百分比（0-100），推荐用于用户可见的进度条；
• progress：单文件进度，附带 loaded（已下载字节数）与 total（总字节数），适合做可选的 per-file 细节展示；
• done：单个文件下载完成；
• ready：模型就绪。

也就是说：用户界面只需监听 progress_total 即可覆盖整个加载过程，不需要自己汇总多个文件的进度。

实战示例

示例 1：动态提供 dtype 选择

利用 get_available_dtypes，可以让应用在运行时探测模型实际可用的精度格式，并按优先级自动选择一个（例如优先 q4，否则退回第一个可用项）：

import { ModelRegistry, pipeline } from '@huggingface/transformers';

const task = 'text-generation';
const modelId = 'onnx-community/Qwen2.5-0.5B-Instruct';

const dtypes = await ModelRegistry.get_available_dtypes(modelId);
const preferred = dtypes.includes('q4') ? 'q4' : dtypes[0] ?? 'fp32';

const generator = await pipeline(task, modelId, { dtype: preferred });
// ... 推理 ...
await generator.dispose();

这样既避免硬编码某个可能不存在的 dtype，又能根据模型仓库的实际情况自动落地"小体积优先"或"默认精度优先"的策略。

示例 2：只清除一个 pipeline 缓存条目

clear_pipeline_cache 的粒度是"task/model/options 三元组"，因此可以做到精确失效而不伤及无关模型：

import { ModelRegistry } from '@huggingface/transformers';

await ModelRegistry.clear_pipeline_cache(
  'feature-extraction',
  'onnx-community/all-MiniLM-L6-v2-ONNX',
  { dtype: 'fp32' }
);

这会删除 feature-extraction + all-MiniLM-L6-v2-ONNX + { dtype: 'fp32' } 这个组合对应的缓存，而同一个模型的其他 dtype（如 q8）缓存会被保留。这避免了整库清缓存带来的二次下载成本。

示例 3：离线门控（Offline Gate）

结合 is_pipeline_cached、env.allowRemoteModels 与 local_files_only，可以实现严格的离线模式：

import { ModelRegistry, env, pipeline } from '@huggingface/transformers';

const task = 'feature-extraction';
const modelId = 'onnx-community/all-MiniLM-L6-v2-ONNX';
const modelOptions = { dtype: 'q8' };

const cached = await ModelRegistry.is_pipeline_cached(task, modelId, modelOptions);

if (!cached) {
  throw new Error('Model not cached yet. Connect once to download assets.');
}

env.allowRemoteModels = false;
const pipe = await pipeline(task, modelId, { ...modelOptions, local_files_only: true });

这段代码的语义是：模型未缓存就明确报错，提示"需联网下载一次"；已缓存则彻底关闭远程拉取（env.allowRemoteModels = false）并以 local_files_only: true 加载，确保运行期零网络请求。关于这两处配置的更多细节：

• local_files_only: true 禁止一切网络请求，模型必须已存在于缓存或本地路径，否则会抛错；参照 PIPELINE_OPTIONS.md 中 "Local Files Only" 一节；
• env.allowRemoteModels = false 是全局层面的远程模型开关；CONFIGURATION.md 建议在任何模型加载之前完成 env 配置，否则可能不生效。

深入理解：预检结果与真实加载的一致性

ModelRegistry 之所以能与 pipeline() 无缝配合，关键在于二者共享同一套参数模型。以下几点对正确使用很重要：

1. 参数必须原样复用。 预检时使用的 task、modelId、modelOptions 应直接透传给 pipeline()。其中 dtype 决定具体加载哪份 ONNX 权重（fp32、fp16、q8、q4 对应不同文件），revision 决定拉取哪个分支/标签/提交，subfolder 决定文件所在子目录——这些字段改变任何一个，文件清单与缓存键都会变化。

2. 缓存粒度是三元组。 is_pipeline_cached 与 clear_pipeline_cache 的判定/清理范围都是"task/model/options 元组"，而dtype 与 revision 都会影响缓存条目。因此在设计缓存策略时，务必把这两个参数视为缓存键的组成部分。

3. 与缓存机制的衔接。 按 CACHE.md 的说明，Transformers.js 的缓存是自动且默认开启的：浏览器端使用 Cache API，Node.js 端默认写入 ./.cache 目录（可通过 env.cacheDir 修改），目录命名遵循 models--{organization}--{model-name}/ 的模式。is_pipeline_cached 返回"可离线就绪"的前提，正是这些缓存层中已经存在该元组所需的全部文件。

4. 体积估算与进度展示可以互补。 预检阶段用 get_file_metadata 算出总大小（面向"下载前"的信息展示），加载阶段用 progress_total 回报进度（面向"下载中"的进度条），两者组合起来即是完整的加载 UX 闭环。

最佳实践清单

1. 在 pipeline() 之前调用 ModelRegistry：当你需要可预测的下载体验（体积估算、缓存状态、离线门控）时，先预检再加载。
2. 缓存决策按 task/model/options 元组进行：dtype 与 revision 都会影响缓存条目，不要在元组层面做粗粒度的"全清"或"只查模型名"。
3. 用户可见进度优先用 progress_total：per-file 进度（progress 事件）保留为可选细节，避免 UI 复杂度失控。
4. 优先选择性失效：用 clear_pipeline_cache(...) 精确清除指定条目，而不是整库删除缓存。
5. 离线模式三层配合：is_pipeline_cached(...) 判定 + local_files_only: true 防请求 + env.allowRemoteModels = false 全局兜底，三者缺一不可。
6. 用完即释放：加载完成后记得 await pipe.dispose()，避免内存泄漏。

相关文档

• Pipeline Options：pipeline() 的完整选项与 progress_callback 事件定义；
• Configuration Reference：env 对象对本地/远程加载的全局配置（allowRemoteModels、localModelPath、cacheDir 等）；
• Caching Reference：浏览器 Cache API、Node.js 文件系统缓存与自定义缓存实现；
• Main Skill Guide：Transformers.js 的入门用法、支持的模型任务与安装方式（npm install @huggingface/transformers，需 Node.js 18+ 或兼容的 Bun/Deno 运行时 / 现代浏览器）。