huggingface/optimum · 上手攻略

• 仓库：huggingface/optimum
• 链接：https://github.com/huggingface/optimum
• 分类：llm-infra（硬件优化与推理加速工具）
• 作者：spark
• 更新：2026-07-30

是什么

huggingface/optimum 是 Hugging Face 推出的 Transformers / Diffusers / TIMM / Sentence-Transformers 的硬件优化扩展库。它把"同一套 HF 模型"映射到多种推理后端与训练硬件上，让用户用同一份 API 跑出"在目标硬件上的极限性能"——既负责 导出（ONNX、OpenVINO、ExecuTorch、TensorRT-LLM、Quanto 等格式），也负责 跑（在 ONNX Runtime、OpenVINO、Intel Gaudi、AWS Trainium/Inferentia、NVIDIA、AMD、FuriosaAI 等硬件上做优化的 Trainer 与 inference 类）。

可以理解为：Hugging Face 官方在 transformers 与"硬件供应商 SDK"之间插的一层薄抽象。原仓库现在按"加速器"分子仓库拆分：optimum-onnx、optimum-intel（OpenVINO/NNCF）、optimum-executorch、optimum-habana、optimum-neuron、optimum-nvidia、optimum-quanto、optimum-amd、optimum-furiosa。主仓库本体的 pip install optimum 给你的是 exporter 接口与最薄的安装面，真正的"在哪家硬件上跑"由对应的子包提供。

仓库维护节奏跟 HF 自身的节奏：每个 minor 版本基本同步对齐 transformers 主线版本号，extras 矩阵会因为新硬件加入频繁改动。新人第一次接触，常用套路是先把主仓库 README 表格读完，再跳到目标硬件子仓库；二者越走越像"姊妹站"，体感上不必再区分主仓。

解决什么问题

直接拿 transformers 跑模型会遇到三个老问题：

1. 推理性能被通用 PyTorch "底子"吃掉：FP16/BF16 已经不够，量化、kernel fusion、KV-cache 优化、算子替换需要硬件 SDK 才能开满；而硬件 SDK 各自一套导入语法，散乱得难复现。
2. 训练侧在大模型 / 大 batch 下 OOM / 偏慢：Trainer 默认走 PyTorch，硬件专属的"分布式 + 优化器 + kernel"组合得自己拼。
3. 跨硬件迁移成本高：写一段代码今天在 A100 上跑得通，明天换 H100、Habana、Trainium，又得改一遍 forward / data loader / checkpoint 保存。

optimum 用三个动作解决：

• 统一导出器（exporters）：一份 optimum-cli 命令就能把任意 HF Transformers 模型导出到目标硬件格式。
• 统一推理类（ORTModelForXXX、OVModelForXXX、...）：用法与 AutoModelFor* 几乎一致，差别在后端类型。
• 统一训练侧 Trainer 包装（Trainer + accelerate）：在硬件专属 backend 上复用 HF Trainer 的接口与训练循环。

快速安装

主包按需带 extras，对应不同硬件后端：

# 最小安装：只拿到 exporters 与 CLI
pip install optimum

# ONNX + ONNX Runtime
pip install --upgrade --upgrade-strategy eager optimum[onnxruntime]

# OpenVINO（Intel CPU/iGPU/dGPU）
pip install --upgrade --upgrade-strategy eager optimum[openvino]

# AMD Instinct / Ryzen AI NPU
pip install --upgrade --upgrade-strategy eager optimum[amd]

# Intel Gaudi HPU
pip install --upgrade --upgrade-strategy eager optimum[habana]

# AWS Trainium / Inferentia
pip install --upgrade --upgrade-strategy eager optimum[neuronx]

# FuriosaAI RNGD
pip install --upgrade --upgrade-strategy eager optimum[furiosa]

# NVIDIA TensorRT-LLM：走官方 Docker 镜像，自带 CUDA/TensorRT/TRT-LLM
docker run -it --gpus all --ipc host huggingface/optimum-nvidia

# ExecuTorch（端侧部署，PyTorch 原生）
pip install optimum-executorch@git+https://github.com/huggingface/optimum-executorch.git

# 想装最新开发版：
pip install git+https://github.com/huggingface/optimum.git
pip install optimum[onnxruntime]@git+https://github.com/huggingface/optimum.git

⚠️ 命令里的具体 extras 名（optimum[onnxruntime] vs optimum[onnx-runtime-gpu] 等）以仓库 README 当前表为准；版本号变化时 pip 自带的 resolver 经常装出冲突，建议显式 --upgrade-strategy eager。

核心用法

1) 命令行导出 ONNX

optimum-cli export onnx \
    --model bert-base-uncased \
    --task text-classification \
    ./onnx-bert/

输出目录里有 model.onnx + tokenizer + 配置文件，可直接走 ONNX Runtime。

对应 Python API：

from optimum.onnxruntime import ORTModelForSequenceClassification
from transformers import AutoTokenizer

model  = ORTModelForSequenceClassification.from_pretrained("./onnx-bert/")
tok    = AutoTokenizer.from_pretrained("./onnx-bert/")
inputs = tok("I love this library!", return_tensors="pt")
logits = model(**inputs).logits     # 与 transformers 接口一致

2) 量化（ONNX Runtime 路径，静态/动态/INT8 都支持）

optimum-cli onnxruntime quantize \
    --avx2 \
    -m ./onnx-bert/ \
    -o ./onnx-bert-int8/

OpenVINO 路径走 optimum-cli export openvino + NNCF 量化文档：

pip install optimum[openvino]
optimum-cli export openvino \
    --model bert-base-uncased \
    --task text-classification \
    ./ov-bert/

optimum-cli export openvino \
    --model bert-base-uncased --task text-classification \
    ./ov-bert-int8/ --weight-format int8

加载类同样替换：

from optimum.intel import OVModelForSequenceClassification
model = OVModelForSequenceClassification.from_pretrained("./ov-bert-int8/")

3) Quanto 量化（PyTorch-native 量化后端）

from transformers import AutoModelForCausalLM, AutoTokenizer
from optimum.quanto import quantize, qint8
import torch

model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen2.5-0.5B-Instruct", torch_dtype=torch.float16)
quantize(model, weights=qint8, activations=qint8)
# 然后照常 model.generate(...)

Quanto 适合"我不想导出 ONNX / OpenVINO，就是想要 PyTorch native 量化"的场景；模型兼容性最广，量化质量略低于 NNCF INT8。

4) Inferentia2 / Trainium2（AWS Neuron）

from optimum.neuron import NeuronModelForCausalLM

model = NeuronModelForCausalLM.from_pretrained(
    "aws-neuron/Llama-3.2-1B-Instruct-neuron",
    export=True,          # 第一次会把 HF 模型编译成 .neuron
    neuron_core="trn1",
)

训练侧：

from optimum.neuron import NeuronTrainer
trainer = NeuronTrainer(
    model=model,
    args=training_args,
    train_dataset=ds["train"],
    eval_dataset=ds["validation"],
    tokenizer=tok,
)
trainer.train()

5) Intel Gaudi（HPU）训练加速

pip install --upgrade --upgrade-strategy eager optimum[habana]

直接在 transformers.Trainer 之上的 wrapper，在 Gaudi1/2/3 上跑 BF16 + HPU 算子，整段 data loader 不动；细节请看 optimum-habana/examples。

6) 其它

• FuriosaAI：通过 optimum[furiosa] 可以把 BERT/Llama 类模型导出到 Furiosa RNGD NPU。
• ExecuTorch：optimum-cli export executorch + optimum-executorch 仓库，能把 Transformer 直接转成 PyTorch 端侧 runtime，落地到 Android / iOS / 嵌入式 Linux。
• TensorRT-LLM：通过 huggingface/optimum-nvidia Docker 镜像与配套 optimum-cli export tflite 风格的命令做导出 + 编译。

典型适用场景

• 跨硬件可复现的模型发布：ML 团队想"同一份 checkpoint 在 A100、H100、Habana、Inferentia 上都能跑"，用 optimum 的统一 export + 子包后端就是当下成本最低的路。
• INT8/INT4 量化上线：从 ONNX Runtime 静态量化、OpenVINO/NNCF 权重量化到 Quanto weight-only 都能复用同一份 ONNX / HF 流水线。
• 生产 latency 调优：把线上 PyTorch FP16 推理换成 ORTModel + 量化，常见提速 1.3–2×，体积压 2–4×。
• 服务端硬件解耦：例如 Ingest 阶段选 ONNX Runtime + OpenVINO；上线到 Intel CPU 集群几乎不需改代码。
• NLP/视觉 Trainer 复用：Habana / Trainium 上的 Trainer 与 transformers Trainer 同步增改；新模型出来跟着 HF 同步加 SFT/PEFT，不必卡在硬件专有 SDK 上。
• 端侧 / 边缘部署：ExecuTorch 路径把 BERT/TinyLlama 烧到手机 / IoT，再用 NNCF 做量化。

不太适用：

• 训练超大 LLM（>50B）——仍然应直接走 Megatron-LM / DeepSpeed / Hugging Face accelerate + 自定义 parallel；optimum 的 Trainer 主要解决"已支持硬件上的 Trainer 跑通"，不是分布式训练框架。
• GPU 上追求极限延迟 + 大并发——可以，但在大模型上不如直接上 vLLM / TensorRT-LLM 后端；optimum-nvidia 主要解决"导出 + 烧录"链路。
• 不在 optimum 支持矩阵里的硬件——若写一段对国产 NPU 的推理需求，目前 optimum 没有专项 extras，要么等 PR，要么自己写 Transformers patch。

坑与注意

1. 主包其实只是壳子：pip install optimum 默认不包含任何硬件 SDK。要跑起来必须装 extras；这带来"装得不全就跑不通"的"开发者头三小时浪费"。
2. 拆分到子仓库：原作者在迁移中把 onnx / intel / neuron / etc 分到独立仓库；CI 例子与文档散落各处。找"ONNX 导出报错"时，先去 optimum-onnx 仓库 issue，不要一上来在主仓发。
3. export → inference 的格式不通用：ONNX 走 ORTModel、OpenVINO 走 OVModel；同一份模型不能跨后端直接复用，得各自 export 一次。
4. Transformer 模型本身的算子覆盖：新模型出来后 optimum 跟进会延迟 1–2 个 HF 版本；用刚发布的自定义模型请先查 optima 支持列表，缺算子时会落到 PyTorch fallback。
5. Neuron/ Habana SDK 与 HF 版本强对齐：AWS Neuron SDK / SynapseAI / Gaudi 软件栈对 transformers 版本有强制要求；升级 transformers 前先看 optimum-neuron 发行说明，硬升会撞"训练脚本报错"。
6. 量化质量 ≠ 量化大小：INT8 不总是无损；BERT-base 的 INT8 可接受，小型 LLM 直量化（无 QAT）会有 2–5% perplexity 漂移。建议先 eval 再上 prod。
7. ONNX Runtime GPU 单独装：optimum[onnxruntime] 装的是 CPU 版；GPU 版走 optimum[onnxruntime-gpu]，且要注意 CUDA/cuDNN 版本对齐。
8. TensorRT-LLM 走 Docker：不要在主机直接 pip install tensorrt-llm 试图混装；首选 huggingface/optimum-nvidia 镜像以省一次"cuda vs tensorrt vs python"组合爆炸。
9. CLI 命令路径：ONNX 导出是 optimum-cli export onnx，OpenVINO 导出是 optimum-cli export openvino，看上去统一，其实子命令名差异频繁（optimum-cli onnxruntime quantize、optimum-cli export openvino --weight-format int8），敲错不会立刻报错，只在最后一步报 attribute 错。
10. 文档与版本：HF Docs 上的 optimum 文档定期大改；建议始终跳到对应子包的 release notes 一眼，避免追着 stable 文档被误导到已废弃 API。

与同类对比

一句话推荐结论

如果你写 HF 模型、又要把它部署到非 NVIDIA 硬件（Intel CPU/Gauda、AWS Inferentia/Trainium、AMD、FuriosaAI、ONNX Runtime 通用后端），huggingface/optimum 是当下官方维护、矩阵最广的统一入口——把"导出 → 量化 → 推理/训练"做成可组合的三段式，单一 CLI 与类 API；但要认清：它不是"性能魔法"，只是"少改几行代码就能跑"——上限取决于底层硬件 SDK 自身。

适用画像：MLOps / Serving 工程师，要把同一份 HF checkpoint 发布到 ≥2 种硬件；量化研究人员，要比较 NNCF/Quanto/ORT 三条路径的 INT8 行为；训练侧在 Habana / Trainium 上的 fine-tune 工程师。不适用画像：想做超大规模分布式训练的（请走 accelerate + Megatron-LM），只想在单卡 GPU 上要极限延迟的（请走 vLLM / TensorRT-LLM）。