Transformers documentation

导出到生产环境

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.23.0).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

导出到生产环境

将 Transformers 模型导出为不同的格式,以适配经过优化的运行时和设备。您可以将同一模型部署到云服务商,或在移动设备和边缘设备上运行。无需针对每个部署环境从头重写模型。您可以自由地在任何推理生态系统中进行部署。

ExecuTorch

ExecuTorch 可在移动设备和边缘设备上运行 PyTorch 模型。它将模型导出为标准化算子组成的计算图,将该计算图编译为 ExecuTorch 程序,并在目标设备上执行。运行时非常轻量,并且会预先计算执行计划。

从源代码安装 Optimum ExecuTorch。

git clone https://github.com/huggingface/optimum-executorch.git
cd optimum-executorch
pip install '.[dev]'

使用 CLI 工具将 Transformers 模型导出为 ExecuTorch。

optimum-cli export executorch \
    --model "Qwen/Qwen3-8B" \
    --task "text-generation" \
    --recipe "xnnpack" \
    --use_custom_sdpa \
    --use_custom_kv_cache \
    --qlinear 8da4w \
    --qembedding 8w \
    --output_dir="hf_smollm2"

运行以下命令以查看所有导出选项。

optimum-cli export executorch --help

ONNX

ONNX 是一种用于描述来自不同框架的模型的通用语言。它将模型表示为由标准化算子构成的图,这些算子具有明确定义的类型、形状和元数据。模型会被序列化为紧凑的 protobuf 文件,可部署到各种经过优化的运行时和引擎中。

Optimum ONNX 使用配置对象将模型导出为 ONNX 格式。它支持多种架构,并且易于扩展。您可以通过 CLI 工具或编程方式导出模型。

安装 Optimum ONNX。

uv pip install optimum-onnx

optimum-cli

使用 --model 参数指定要导出的模型和输出目录。

optimum-cli export onnx --model Qwen/Qwen3-8B Qwen/Qwen3-8b-onnx/

运行以下命令以查看所有可用参数,或参阅 使用 optimum.exporters.onnx 将模型导出为 ONNX 指南以获取更多详细信息。

optimum-cli export onnx --help

要导出本地模型,请将权重文件和分词器文件保存在同一目录中。将该目录路径传递给 --model 参数,并使用 --task 参数来指定 任务。如果未提供 --task,系统将从模型中自动推断任务,或使用没有特定任务头的架构。

optimum-cli export onnx --model path/to/local/model --task text-generation Qwen/Qwen3-8b-onnx/

使用任何支持 ONNX 的 运行时 部署该模型,包括 ONNX Runtime。

from transformers import AutoTokenizer
from optimum.onnxruntime import ORTModelForCausalLM

tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen3-8b-onnx")
model = ORTModelForCausalLM.from_pretrained("Qwen/Qwen3-8b-onnx")
inputs = tokenizer("Plants generate energy through a process known as ", return_tensors="pt")
outputs = model.generate(**inputs)
print(tokenizer.batch_decode(outputs))

optimum.onnxruntime

使用 Optimum ONNX 以编程方式导出 Transformers 模型。使用模型实例化一个 ORTModel,并设置 export=True。使用 save_pretrained 保存 ONNX 模型。

from optimum.onnxruntime import ORTModelForCausalLM
from transformers import AutoTokenizer

ort_model = ORTModelForCausalLM.from_pretrained("Qwen/Qwen3-8b", export=True)
tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen3-8b")

ort_model.save_pretrained("onnx/")
tokenizer.save_pretrained("onnx/")
Update on GitHub