How to Export OpenMed Models to CoreML Format for iOS Deployment

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 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 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.

Usage Examples

Command-Line Interface

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

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:

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:

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 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}