---

name: optimize-models description: "Guide coremltools model compression and optimization with Core ML package APIs and optional PyTorch optimization APIs." disable-model-invocation: true metadata: disco-role: operating license: BSD 3-Clause

optimize-models

Use this sub-skill when the task is to compress or optimize an already-converted Core ML model, or to choose an optional PyTorch-side optimization flow before Core ML export. It covers weight quantization, activation quantization with calibration data, palettization, pruning, decompression, metadata discovery, and joint compression choices.

Route first

• Need to convert an original TensorFlow, PyTorch, sklearn, XGBoost, LightGBM, LibSVM, MIL, or other source model into Core ML before compression? Route to convert-models.
• Need to load, save, inspect metadata/specs, rename features, or run MLModel.predict() on an artifact? Route to model-io-and-prediction.
• Need to debug MIL graph passes, custom ops, typed execution, or pass pipelines? Route to mil-and-debugging.
• Already have a Core ML mlprogram and want data-free package compression? Stay here and prefer coremltools.optimize.coreml.
• Have a PyTorch model and need calibration-data or fine-tuning/QAT-aware compression before Core ML export? Stay here only if PyTorch and the relevant coremltools.optimize.torch APIs import in the user's environment.

Quick decision rules

1. No training data, Core ML artifact already exists: use coremltools.optimize.coreml functions directly on an MLModel package.
2. Calibration data needed: use Core ML activation quantization only when you can supply Core ML input dictionaries and can run calibration; otherwise use the optional Torch layerwise/calibration APIs on a PyTorch source model.
3. Fine-tuning or QAT required: use optional coremltools.optimize.torch optimizers on the PyTorch model, then convert with convert-models.
4. Need the smallest safe first pass: inspect weights with get_weights_metadata, compress only large weight tensors, and set op_name_configs or op_type_configs to skip fragile layers.
5. Need to validate artifact behavior: inspect compressed/decompressed artifacts with model-io-and-prediction; prediction remains platform-dependent.

Reference map

• API names, config fields, and safe snippets: references/api-reference.md
• End-to-end workflow decision tree: references/workflows.md
• Compression-specific failures and fixes: references/troubleshooting.md
• Local smoke helper: scripts/optimize_coreml_smoke.py

Runtime guardrails

• Do not claim coremltools.optimize.torch works until importing the relevant submodule succeeds with PyTorch installed and version-compatible.
• Core ML package compression APIs operate on mlprogram MLModel objects; if the user has a non-mlprogram or original model object, route to conversion first.
• Activation quantization and Torch calibration flows need representative data. If no data exists, recommend weight-only Core ML compression first.
• Use decompress_weights and metadata/spec inspection to isolate compression-induced failures before changing the original conversion settings.