常见问题（精选） ​

架构与定位 ​

Q：Transformers.js 和 Python transformers 是什么关系？底层一样吗？

• API 上追求 任务级对齐（尤其 pipeline）；底层 Python 多为 PyTorch 动态图，JS 侧是 ONNX 静态图 + ONNX Runtime，模型需 Optimum 等工具导出。推理路径、算子支持与数值细节可能不同，需要以 ONNX 为准。

Q：为什么选 ONNX Runtime 而不是 TensorFlow.js / MediaPipe？

• 与 Hugging Face Optimum ONNX 流水线一致，便于复用 Hub 上大量 ONNX 模型；ORT 提供 WASM / WebGPU / WebNN / CUDA 等多 EP，覆盖浏览器与服务器。

Pipeline 与加载 ​

Q：pipeline() 里 tokenizer 和模型是串行还是并行加载？

• 并行：Promise.all 同时 AutoTokenizer.from_pretrained、AutoProcessor.from_pretrained（若需要）与 model.from_pretrained（见 pipelines.js）。

Q：SUPPORTED_TASKS 里的 type: 'text' | 'multimodal' 有什么用？

• 驱动 get_pipeline_files 决定是否探测 tokenizer.json、preprocessor_config.json，避免多余请求与错误假设。

Q：同一任务为什么可能有多个 AutoModel 候选？

• 同一任务在 Python 也对应多种架构（如 ASR 的 Seq2Seq vs CTC）；通过 AutoConfig 的 model_type 在候选数组里 supports() 匹配唯一类。

ONNX 与运行时 ​

Q：浏览器里默认用什么跑推理？

• 默认 EP 在 backends/onnx.js 中浏览器为 wasm；若用户指定 webgpu 等且硬件/浏览器支持，则走对应 EP。

Q：源码里如何解决 Session already started？

• Web 环境用全局 webInferenceChain 将 session.run 串行化；加载 session 用 webInitChain 同理（见 backends/onnx.js）。Node 通常直接 run()。

Q：为什么不大规模用动态 import 切 onnxruntime-node/web？

• 注释说明历史 bundler / top-level await 限制；当前采用 静态 import + 运行时分支。

设备、量化与性能 ​

Q：WASM 默认 dtype 为什么是 q8？

• DEFAULT_DEVICE_DTYPE_MAPPING 将 wasm 默认设为 q8，在算力与内存受限环境下 减小模型与带宽；仍可被用户显式覆盖。

Q：WebGPU 上用 fp16 前要检查什么？

• isWebGpuFp16Supported 检查 adapter 是否支持 shader-f16；不支持则 getSession 抛错，避免错误内核路径。

Q：如何减少多模态模型在「纯文本生成」时的下载量？

• get_pipeline_files 对 text-generation 且存在 getTextOnlySessions 的模型类型时，过滤 onnx 子目录中不需要的 vision/audio 等 session 文件。

模型抽象与生成 ​

Q：PreTrainedModel 如何区分能否 generate？

• MODEL_RUNTIME_CONFIG / MODEL_SESSION_CONFIG 等与 resolveTypeConfig 合并后设置 can_generate、_forward、_prepare_inputs_for_generation。

Q：DynamicCache 是什么？

• 存放 past_key_values.* 张量的类字典结构；dispose 释放 GPU buffer 张量，防止 WebGPU OOM。

Q：交叉架构加载（类名与 config.architectures 不一致）如何处理？

• resolveTypeConfig 检测后用 原生架构 的 session/forward 配置，并启用 textOnly 模式，保证与 ONNX 一致。

开放题 ​

Q：如果要在小程序或极端受限环境部署，你会改库哪一层？

• 合理答题方向：缓存与路径（hub.js/cache）、量化默认值（dtypes）、拆分 Worker + 避免主线程大数组拷贝、缩小 pipeline 默认模型；并承认 Web 推理链串行 对 QPS 的限制。

Q：如何验证与 Python 输出一致？

• 固定 模型 revision、dtype、随机种子、generation_config；对比中间 logits 或最终文本；注意 量化与 fp16 的数值误差。

更多细节请回溯主索引：docs2/readme.md