# How to Export OpenMed Models to CoreML Format for iOS Deployment

> Export OpenMed models to CoreML format for seamless iOS deployment. Learn how to convert HuggingFace token-classification models to mlpackage files for iOS 16 and macOS 13.

- Repository: [Maziyar Panahi/openmed](https://github.com/maziyarpanahi/openmed)
- Tags: how-to-guide
- Published: 2026-06-11

---

**OpenMed provides a dedicated CoreML conversion utility that transforms HuggingFace token‑classification models into `.mlpackage` files ready for iOS 16 and macOS 13 deployment.**

OpenMed ships with a specialized conversion pipeline implemented in [`openmed/coreml/convert.py`](https://github.com/maziyarpanahi/openmed/blob/main/openmed/coreml/convert.py) that enables you to export models to CoreML format with minimal configuration. The utility handles everything from model acquisition and Torch JIT tracing to metadata injection, producing optimized packages compatible with Apple’s Neural Engine.

## Core Conversion Pipeline

The conversion workflow in [`openmed/coreml/convert.py`](https://github.com/maziyarpanahi/openmed/blob/main/openmed/coreml/convert.py) proceeds through seven distinct stages to ensure accurate and efficient model export.

### Dependency Loading

The conversion function lazily imports `torch`, `coremltools`, and the HuggingFace libraries (`AutoTokenizer`, `AutoModelForTokenClassification`). If any dependencies are missing, the utility raises an informative `ImportError` specifying the required installation command: `pip install openmed[coreml]`.

### Model and Tokenizer Acquisition

The target model is fetched from the HuggingFace Hub using the provided `model_id` and cached locally in an optional directory. The tokenizer is instantiated with the same `model_id` to ensure vocabulary alignment.

### Wrapper Creation

A thin `torch.nn.Module` wrapper named `TokenClassificationWrapper` is defined to return only the raw logits from the underlying model. This strips away the richer `ModelOutput` object that would otherwise complicate the tracing process.

### Torch JIT Tracing

A dummy input sentence is tokenized respecting the `max_seq_length` parameter with appropriate padding and truncation. The wrapper is then traced with `torch.jit.trace`, producing a static TorchScript graph that CoreML can ingest.

### CoreML Conversion

The `coremltools.convert` function receives the traced module along with typed input specifications for `input_ids` and `attention_mask`. The `compute_precision` argument determines hardware targeting:

- **`float16`** – Optimizes for Apple Neural Engine (ANE)
- **`float32`** – Falls back to CPU execution

The conversion pins a minimum deployment target of iOS 16.

### Metadata Injection

Human‑readable fields (`short_description`, `author`, `license`) and custom metadata entries (`id2label`, `num_labels`, `max_seq_length`, `source_model`) are attached to the resulting `mlmodel`. This makes the package self‑describing and easier to integrate downstream.

### Package Saving

The finalized `mlmodel` is persisted to the user‑specified `output_path`. For convenience, a companion `*_id2label.json` file is emitted alongside the package to preserve label mappings.

## Public API Reference

The conversion module exposes two primary callables:

- **`convert(model_id, output_path, max_seq_length=512, compute_precision="float16", cache_dir=None) → Path`** – Performs the full conversion workflow described above.
- **`main()`** – A thin command‑line wrapper that parses arguments and forwards them to `convert`.

Both are importable via `from openmed.coreml import convert` and covered by unit tests in [`tests/unit/coreml/test_coreml_convert.py`](https://github.com/maziyarpanahi/openmed/blob/main/tests/unit/coreml/test_coreml_convert.py).

## Usage Examples

### Command-Line Interface

Run the conversion directly from a terminal with the optional extra dependency installed:

```bash
python -m openmed.coreml.convert \
    --model OpenMed/OpenMed-PII-SuperClinical-Small-44M-v1 \
    --output ./OpenMedPIISmall.mlpackage \
    --max-seq-length 256 \
    --precision float16

```

### Programmatic Integration

Integrate the conversion into your Python workflow:

```python
from pathlib import Path
from openmed.coreml.convert import convert

# Convert a HuggingFace model to a CoreML package

coreml_path: Path = convert(
    model_id="OpenMed/OpenMed-PII-SuperClinical-Small-44M-v1",
    output_path=Path("./OpenMedPIISmall.mlpackage"),
    max_seq_length=256,
    compute_precision="float16",   # use Neural Engine; switch to "float32" for CPU

)

print(f"CoreML package saved at {coreml_path}")

```

### Inspecting Generated Metadata

After conversion, verify the embedded metadata:

```python
import coremltools as ct

mlmodel = ct.models.MLModel(str(coreml_path))
print("Description:", mlmodel.short_description)
print("Author:", mlmodel.author)
print("Custom metadata:", mlmodel.user_defined_metadata)

```

## Summary

- OpenMed provides a complete CoreML export pipeline in [`openmed/coreml/convert.py`](https://github.com/maziyarpanahi/openmed/blob/main/openmed/coreml/convert.py) for token‑classification models.
- The `convert()` function handles the entire workflow from model fetching to `.mlpackage` generation.
- Use `compute_precision="float16"` for Neural Engine optimization or `"float32"` for CPU compatibility.
- Minimum deployment targets are iOS 16 and macOS 13.
- Label mappings and model metadata are preserved in both the package and a companion JSON file.

## Frequently Asked Questions

### What is the minimum iOS version required for OpenMed CoreML models?

According to the source code in [`openmed/coreml/convert.py`](https://github.com/maziyarpanahi/openmed/blob/main/openmed/coreml/convert.py), the conversion pipeline pins a minimum deployment target of iOS 16 and macOS 13. This ensures compatibility with the CoreML features used during the conversion process.

### How do I configure the export for CPU-only inference instead of the Neural Engine?

Pass `compute_precision="float32"` to the `convert()` function or the `--precision float32` flag in the CLI. The default value of `"float16"` optimizes for the Apple Neural Engine, while `"float32"` forces CPU execution and may offer better compatibility for certain model architectures.

### Where are the label mappings stored after conversion?

The label mappings (`id2label`) are stored in two locations: embedded within the `.mlpackage` itself in the `user_defined_metadata` field, and written to a companion JSON file named `*_id2label.json` in the same directory as the output package. This redundancy ensures easy access for iOS application development.

### What dependencies are required to export models to CoreML format?

The conversion requires `torch`, `coremltools`, and the HuggingFace `transformers` library. Install the optional extra dependency group using `pip install openmed[coreml]`. If dependencies are missing, the utility raises an `ImportError` with specific installation instructions.