Transformers.js在Next.js应用路由中的WASM回退问题解析

问题背景

在使用Transformers.js库结合Next.js（基于app路由）开发AI应用时，开发者可能会遇到一个典型错误："Cannot read properties of undefined (reading 'create')"，随后系统会回退到WASM模式。这个问题通常发生在尝试构建模型会话时，表明底层运行环境配置存在问题。

错误分析

从错误堆栈可以观察到几个关键点：

1. 错误发生在constructSession函数中，表明模型会话初始化失败
2. 系统自动回退到WASM模式作为备选方案
3. 调用链涉及HuggingFaceEmbedding和VectorStoreIndex等组件

根本原因

这个问题通常由以下几个因素导致：

1. Webpack配置问题：Next.js默认的Webpack配置可能无法正确处理Transformers.js所需的ONNX运行时依赖
2. 环境不匹配：服务器端和客户端环境差异导致模块加载失败
3. 构建目标限制：默认配置可能不包含必要的Node.js polyfill

解决方案

1. 明确区分运行环境

Transformers.js在浏览器和服务器的运行方式不同。在Next.js中，必须明确区分：

• 客户端组件：使用WASM后端，适合轻量级推理
• 服务端组件：可以使用ONNX运行时，获得更好性能

2. 完善Webpack配置

修改next.config.js以正确处理相关依赖：

module.exports = {
  webpack: (config, { isServer }) => {
    // 忽略特定模块
    config.resolve.alias = {
      ...config.resolve.alias,
      "sharp$": false,
      "onnxruntime-node$": false,
    }
    
    // 添加必要的polyfill
    config.resolve.fallback = {
      ...config.resolve.fallback,
      "fs": false,
      "path": false,
      "os": false,
    }
    
    return config
  }
}

3. 环境变量配置

确保正确设置环境变量，特别是：

process.env.NEXT_PUBLIC_USE_WASM = "true" // 强制使用WASM模式

4. 代码结构调整

将Transformers.js相关逻辑分离：

• 创建专用的API路由处理模型加载和推理
• 前端组件只负责交互和结果展示
• 考虑使用Edge Functions处理轻量级推理任务

最佳实践建议

1. 模型选择：在浏览器环境中优先选择量化的小型模型
2. 错误处理：实现完善的错误捕获和回退机制
3. 性能监控：添加加载指示器和性能指标
4. 缓存策略：实现模型缓存减少重复加载
5. 渐进增强：先加载轻量模型，再根据需要加载更复杂模型

总结

Transformers.js在Next.js应用中的集成需要特别注意环境差异和构建配置。通过合理区分客户端和服务端逻辑、完善Webpack配置以及采用渐进增强策略，可以有效地解决WASM回退问题，构建稳定高效的AI应用。

对于生产环境，建议进一步考虑模型分片加载、流式响应和服务端缓存等高级优化技术，以提升用户体验和应用性能。