Transformers.js 是 Hugging Face 生态系统中的一款工具库，可以在浏览器或 Node.js 环境中执行自然语言处理、计算机视觉和音频处理等任务。本文结合一款 Electron 本地翻译应用的项目开发经验，探索 Transformers.js 在真实场景下的落地过程。

环境配置与缓存策略

运行模型前，通常需要配置运行环境，尤其是本地模型文件的存储路径。在离线场景下，开启加载本地缓存文件的选项是必要步骤。项目中将模型统一存放在应用数据目录，并进行了相关配置。

const transformers = await import("@huggingface/transformers");

const cacheDir = path.join(appDataPath, "models-cache");
transformers.env.cacheDir = cacheDir;
transformers.env.allowLocalModels = true;

管道（Pipeline）

管道（Pipeline）是该库最基础的高级 API，负责将数据预处理、模型推理及结果后处理串联在一起。你可以根据需求指定任务名称和模型 ID 来创建管道。

在项目实践中，实例化了一个翻译管道，利用回调函数监听加载进度。使用了 Xenova/nllb-200-distilled-600M 这个多语种翻译大模型。

为了减小模型体积并提升推理速度，通常会使用量化版的模型。在创建 pipeline 时，可以指定 dtype 参数来加载不同的量化精度。

const translator = await transformers.pipeline("translation", "Xenova/nllb-200-distilled-600M", {
  dtype: "q8", // 启用 8-bit 量化
  progress_callback: (progress) => {
    // 将底层进度封装后发送给 UI 层
    updateProgress(progress);
  }
});

执行翻译:

const result = await translator('Hello world', {
  src_lang: 'eng_Latn',
  tgt_lang: 'zho_Hans',
});
console.log(result);

流式输出机制

大语言模型在生成文本时耗时较长，一次性返回结果会导致界面长时间等待。Transformers.js 提供了 TextStreamer 类，用于在模型逐步生成字词的过程中向外输出增量数据。

结合项目的翻译场景，可以通过配置 TextStreamer 跳过特殊字符，并通过回调将最新生成的文本片段发送到 UI。

let streamedText = "";
const streamer = new transformers.TextStreamer(translator.tokenizer, {
  skip_prompt: true,
  skip_special_tokens: true,
  callback_function: (deltaText) => {
    if (!deltaText) return;
    streamedText += deltaText;
    onStreamUpdate({ deltaText, text: streamedText });
  }
});

推理执行与中断控制

执行推理时，需要向实例化的管道传入源数据和对应的配置参数（例如源语言、目标语言及生成的最大长度）。另外，如果需要在生成中途取消任务，可以使用 StoppingCriteriaList 和 InterruptableStoppingCriteria 机制控制生成进程。

在项目的流式翻译链路中，通过组合这些条件选项，实现了由用户触发中断操作的功能。

const stoppingCriteria = new transformers.StoppingCriteriaList();
const interruptable = new transformers.InterruptableStoppingCriteria();
stoppingCriteria.push(interruptable);

const result = await translator("Translate this text", {
  src_lang: "eng_Latn",
  tgt_lang: "zho_Hans",
  max_new_tokens: 256,
  streamer,
  stopping_criteria: stoppingCriteria
});

保存 interruptable 引用，当用户触发取消时执行:

interruptable.interrupt()