---

name: optimum description: "Use Hugging Face Optimum for model export routing, accelerated pipeline dispatch, Torch FX graph workflows, GPTQ quantization planning, and utility/config support." disable-model-invocation: true metadata: disco-role: operating license: Apache 2.0

Optimum repo skill

Use this skill when the task involves Hugging Face Optimum: optimum-cli, model export task mapping, accelerated pipeline dispatch to partner packages, Torch FX graph transformations, GPTQ quantization planning, dummy inputs, normalized configs, preprocessing processors, or Optimum base save/load support.

Optimum is a namespace-style extension package around Transformers/Diffusers/TIMM/Sentence-Transformers optimization workflows. This base repository supplies shared CLI routing, exporter/task utilities, FX graph utilities, GPTQ integration code, and cross-package support utilities; many hardware-specific implementations live in partner packages such as optimum-onnx, optimum-intel, optimum-habana, optimum-furiosa, and related distributions.

Start here

1. Confirm the installed package and optional dependency surface before deeper work. Prefer the bundled checker over ad-hoc inline Python so the diagnosis matches this skill's optional-dependency policy:

   python scripts/check_optimum_install.py
   python scripts/check_optimum_install.py --json
   

2. If the task names a CLI command, exporter backend, task mapping, or accelerated pipeline, read sub-skills/exporters-and-cli/SKILL.md.

3. If the task is about Torch FX graph rewrites, reversible transformations, compose, or optional tensor parallelism, read sub-skills/fx-graph-workflows/SKILL.md.

4. If the task is about GPTQ, GPTQQuantizer, GPT-QModel dependency checks, saving/loading quantized weights, or custom CausalLM quantization planning, read sub-skills/gptq-quantization/SKILL.md.

5. If the task is about dummy input generators, normalized configs, task processors, run configs, BaseConfig, OptimizedModel, or support utilities, read sub-skills/utilities-and-configs/SKILL.md.

6. For cross-cutting installation, import, partner package, or backend failures, read references/troubleshooting.md.

7. Before assuming this skill matches a different checkout, read references/repo-provenance.md.

Installation and minimal check

Base install:

python -m pip install optimum
python - <<'PY'
from importlib.metadata import version
import optimum.version as ov
print(version("optimum"), ov.__version__)
PY
optimum-cli --help
optimum-cli env

Common optional surfaces:

• ONNX export / ONNX Runtime accelerated pipelines: install the corresponding optimum-onnx or optimum[onnx] / optimum[onnxruntime] distribution path documented for the target workflow.
• OpenVINO accelerated pipelines: install the optimum-intel[openvino] path for OpenVINO-backed model classes and pipeline dispatch.
• GPTQ quantization: install gptqmodel>=7.0.0 and usually accelerate, then verify GPU/backend readiness before running quantization.
• Preprocessing task processors: some imports require torchvision, Pillow, and/or datasets even when the base package import succeeds.
• Tensor parallelism: treat as an advanced CUDA/distributed workflow; match the repository's tested Python/torch stack before relying on it.

Route map

User intent	Read	Safe bundled check
Diagnose optimum-cli, optimum-cli env, missing export onnx, partner CLI registration	sub-skills/exporters-and-cli/	python sub-skills/exporters-and-cli/scripts/probe_optimum_cli.py --run-env
Query task names, synonyms, exporter backend config constructors, or custom backend registration	sub-skills/exporters-and-cli/	python sub-skills/exporters-and-cli/scripts/tasks_manager_probe.py --json
Use optimum.pipelines.pipeline(..., accelerator="ort"/"ov")	sub-skills/exporters-and-cli/	python scripts/check_optimum_install.py --json plus partner-specific imports
Apply or write Torch FX transformations	sub-skills/fx-graph-workflows/	python sub-skills/fx-graph-workflows/scripts/fx_transform_smoke.py --check-compose
Plan tensor parallelism	sub-skills/fx-graph-workflows/	No default native run; first verify Python, CUDA, NCCL, torch.compile, and distributed process groups
Plan GPTQ quantization or load saved GPTQ weights	sub-skills/gptq-quantization/	python sub-skills/gptq-quantization/scripts/gptq_availability_probe.py --json
Generate dummy tensors or standardize config fields	sub-skills/utilities-and-configs/	python sub-skills/utilities-and-configs/scripts/utils_smoke.py
Diagnose utility/preprocessing/config issues	sub-skills/utilities-and-configs/ and root troubleshooting	python sub-skills/utilities-and-configs/scripts/utils_smoke.py --check-task-processors

Boundaries and cautions

• Do not assume base optimum contains every hardware backend. Missing partner subcommands or model classes are often install/routing issues, not source bugs.
• Do not run Hub model downloads, native export/pipeline tests, full GPTQ quantization, tensor-parallel distributed tests, training, or dataset downloads unless the user explicitly authorizes network/hardware/time requirements.
• A CPU import proves only base package availability. It does not prove ONNX Runtime, OpenVINO, GPTQ kernels, CUDA tensor parallelism, or partner package execution.
• Use bundled scripts for safe local diagnostics before inventing one-off probes. They are designed to run from arbitrary current directories and do not depend on the original repository checkout.
• Keep task-specific details in the nearest sub-skill. Root guidance should only route, install, and triage.