optimum
Use Hugging Face Optimum for model export routing, accelerated pipeline dispatch, Torch FX graph workflows, GPTQ quantization planning, and utility/config support.
- License 许可
- Apache-2.0
- 最近更新
- 2026-09-03
- Stars
- ★ 351
- Forks
- 27
01 前言 Front Matter
- name
- optimum
- license
- Apache 2.0
- metadata
- { "disco-role": "operating" }
- 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
02 资源文件 4
- 参考文档references/repo-provenance.md2.6 KB
- 参考文档references/repo-routing-metadata.json437 B
- 参考文档references/troubleshooting.md4.2 KB
- 脚本scripts/check_optimum_install.py5.8 KB
03 SKILL.md 正文
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
-
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 -
If the task names a CLI command, exporter backend, task mapping, or accelerated pipeline, read
sub-skills/exporters-and-cli/SKILL.md. -
If the task is about Torch FX graph rewrites, reversible transformations,
compose, or optional tensor parallelism, readsub-skills/fx-graph-workflows/SKILL.md. -
If the task is about GPTQ,
GPTQQuantizer, GPT-QModel dependency checks, saving/loading quantized weights, or custom CausalLM quantization planning, readsub-skills/gptq-quantization/SKILL.md. -
If the task is about dummy input generators, normalized configs, task processors, run configs,
BaseConfig,OptimizedModel, or support utilities, readsub-skills/utilities-and-configs/SKILL.md. -
For cross-cutting installation, import, partner package, or backend failures, read
references/troubleshooting.md. -
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-onnxoroptimum[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.0and usuallyaccelerate, then verify GPU/backend readiness before running quantization. - Preprocessing task processors: some imports require
torchvision, Pillow, and/ordatasetseven 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
optimumcontains 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.
04 同仓库更多 Skills
passnet-triton-opt
Make a single PassNet Triton kernel fast AND numerically faithful: performance model (when a replacement can win at all), block/grid/warp tuning, autotune policy, launch overhead, and per-op numeric recipes to pass the dtype baseline tolerances. Use when a pass matches and is correct but speedup below expected, or when correctness fails by small numeric margins.
passnet-solve
END-TO-END playbook for solving one PassNet sample: analyze the computation graphs, decide the optimization strategy (what to fuse, what to replace, what to leave alone), drive the iteration loop, and maximize the sample score. This is the ENTRY skill — invoke it first for any PassNet optimization task; it tells you when to use passnet-pattern-fusion, passnet-triton-opt and passnet-feedback.
passnet-skill
PassNet GPU kernel optimization via compiler passes. Design and implement Triton-based optimization passes, create pass files under ./pass_dir/, self-evaluate with pass_evaluator, and iterate to maximize GPU speedup.
passnet-pattern-fusion
Author PassNet pass files: write patterns that actually MATCH the FX graph, pick fusion regions (which ops to absorb into one Triton kernel), and structure multi-pass submissions with the mandatory shared-dispatch architecture. Use when creating or fixing pattern()/replacement_args()/replacement_func() files, when a pass "failed to match", or when deciding how to fuse multiple kernels/ops.
passnet-orchestrate
Round/batch planning and decision support for PassNet graph optimization. Use for multi-sample triage, worker allocation, eval-budget policy, and post-eval keep/revert decisions. For solving one concrete sample end to end, use passnet-solve as the entry skill; consult this skill only when you need broader planning or a specific decision gate.
passnet-feedback
Fast, deterministic feedback for PassNet work: pre-flight pattern/match verification WITHOUT burning a GPU evaluation, per-node bottleneck analysis of a sample's graphs, and eval-log parsing into per-variant status + estimated score + failure classification. Use BEFORE every GPU evaluation (check_pattern), at the START of a sample (analyze_graph), and AFTER every evaluation (parse_eval_log).