transformers.js项目中本地模型与WASM文件在Create React App中的配置指南

在基于Create React App（CRA）的项目中使用transformers.js时，开发者常会遇到本地模型和WASM文件加载失败的问题。本文将深入分析问题根源并提供完整的解决方案。

问题现象分析

当尝试在CRA项目中配置transformers.js使用本地模型时，开发者通常会遇到以下典型错误：

SyntaxError: Unexpected token '<', "<!DOCTYPE "... is not valid JSON

这个错误表明系统正在尝试解析HTML文件作为JSON，通常发生在文件路径配置不正确时。错误的核心原因是文件路径映射关系未正确建立。

完整解决方案

1. 环境配置

首先需要进行正确的环境变量设置：

env.allowRemoteModels = false;
env.allowLocalModels = true;
env.backends.onnx.wasm.wasmPaths = process.env.PUBLIC_URL + "/dictation/";
env.localModelPath = process.env.PUBLIC_URL + "/dictation/models/";

2. 关键目录结构

解决方案的核心在于保持与model_id完全一致的目录结构。例如，当使用以下模型ID时：

this.model_id = "onnx-community/whisper-base";

对应的目录结构必须为：

public/
  dictation/
    models/
      onnx-community/
        whisper-base/
          config.json
          generation_config.json
          preprocessor_config.json
          tokenizer_config.json
          tokenizer.json
          onnx/
            decoder_model_merged_q4.onnx
            encoder_model.onnx
    ort-wasm-simd-threaded.jsep.wasm

3. WASM文件处理

对于WASM文件的本地加载，需要注意：

1. 确保文件路径与env.backends.onnx.wasm.wasmPaths配置完全匹配
2. WASM文件应直接放置在配置的路径下，不需要额外子目录
3. 在CRA中，所有静态资源都应放在public目录下

技术原理

这种目录结构要求源于transformers.js的内部实现机制。系统会根据model_id自动构建完整的文件路径，因此必须保持严格的对应关系。当model_id包含组织名（如onnx-community）时，必须在本地目录结构中完整重现这一层级。

最佳实践建议

1. 始终检查model_id与实际目录结构的对应关系
2. 对于自定义训练模型，保持相同的目录组织方式
3. 在开发过程中，使用浏览器开发者工具检查网络请求，确认文件加载路径是否正确
4. 考虑在项目文档中明确记录模型目录结构规范

通过遵循这些指导原则，开发者可以顺利在CRA项目中实现transformers.js的完全本地化部署，无需依赖外部CDN资源，同时为后续模型定制化开发奠定基础。