coremlcompiler

package
v0.6.17 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 22, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package coremlcompiler compiles CoreML model packages (.mlpackage) into compiled model bundles (.mlmodelc) without requiring xcrun or Apple's proprietary coremlcompiler binary.

Only mlprogram models (spec version 5+) are supported. Legacy NeuralNetwork models must first be converted to mlprogram format using coremltools (convert_to="mlprogram").

The compilation path converts mlprogram models: the protobuf-encoded MIL program is serialized to MIL text, weights are copied byte-for-byte, and a coremldata.bin header is generated. The result can be loaded directly by CoreML, the ANE runtime, or x/ane.

Three entry points cover different use cases:

Compile takes a .mlpackage directory or .mlmodel file on disk and produces a compiled .mlmodelc bundle. This is the simplest path and handles reading the protobuf, locating weights, and writing all output files:

err := coremlcompiler.Compile("model.mlpackage", "model.mlmodelc")

CompileMLProgram accepts raw model protobuf bytes and a weight directory. Use this when you already have the serialized model in memory or need to supply the weight directory separately:

err := coremlcompiler.CompileMLProgram(protoBytes, weightDir, "model.mlmodelc")

CompileMILText takes pre-built MIL text, a ModelDescription, and an optional weight root directory. Use this when you generate MIL text programmatically rather than decoding it from a protobuf:

err := coremlcompiler.CompileMILText(milText, 8, desc, weightRoot, "model.mlmodelc")

The Go types in this package model the mlprogram subset of the CoreML specification. Fields outside that subset, such as Model.isUpdatable or an input's shape flexibility, cannot be constructed from Go, but a model decoded from wire bytes keeps them and re-encodes them verbatim.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Compile

func Compile(inputPath, outputPath string) error

Compile compiles a CoreML model package (.mlpackage) or model file (.mlmodel) into a compiled bundle (.mlmodelc) at outputPath.

Only mlprogram models (spec version 5+) are supported. Legacy NeuralNetwork models must be converted to the mlprogram format before compilation (e.g. via coremltools.convert with convert_to="mlprogram").

func CompileMILText

func CompileMILText(milText string, specVersion int32, desc ModelDescription, weightRoot, outputPath string) error

CompileMILText compiles an already-emitted mlprogram MIL text into a compiled bundle at outputPath.

desc names the model inputs, outputs, and states stored in coremldata.bin and metadata.json. weightRoot, when non-empty, is copied into the bundle preserving relative paths, so BLOBFILE paths like "@model_path/weights/..." resolve correctly at runtime.

func CompileMLModelAtURL added in v0.5.4

func CompileMLModelAtURL(sourcePath string) (string, error)

CompileMLModelAtURL uses [MLModel compileModelAtURL:error:] to compile a .mlpackage or .mlmodel to a .mlmodelc directory. Only available on darwin.

func CompileMLProgram

func CompileMLProgram(modelProto []byte, weightDir, outputPath string) error

CompileMLProgram compiles an mlprogram model from already-parsed components. This is useful when you have the model proto bytes and weight directory available separately.

func CompileToTemp

func CompileToTemp(inputPath string) (string, error)

CompileToTemp compiles a model to a temporary directory, returning the path to the compiled .mlmodelc bundle. The directory is placed under os.TempDir() and named by a hash of the input path and content for implicit caching.

func EncodeModel added in v0.5.0

func EncodeModel(m *Model) []byte

EncodeModel encodes a Model to protobuf wire format.

The Model type models the mlprogram subset of the CoreML spec. Fields outside that subset cannot be built from Go, but are preserved verbatim on a model that was decoded from wire bytes and are re-emitted after the modeled fields of the message they belong to.

func PackSubByte added in v0.6.17

func PackSubByte(dt BlobDataType, values []int8) ([]byte, error)

PackSubByte packs values of a sub-byte blob element type into the byte payload MILBlob stores. Element i occupies bits [i*bits, (i+1)*bits) of the stream, little-endian within each byte; for widths that do not divide 8 an element straddling a byte boundary continues in the low bits of the next byte. This mirrors MILBlob's PackSubByteVec.

func SanitizeProgram added in v0.6.17

func SanitizeProgram(m *Model)

SanitizeProgram rewrites every function, variable and block name in m's MIL program into a legal MIL identifier, and applies the same rewrite to the matching ModelDescription feature names so the description and the MIL stay in sync. Names that are already valid are left untouched.

func ShouldUseWeightFile added in v0.6.17

func ShouldUseWeightFile(dt DataType, numElements int, specVersion int32) bool

ShouldUseWeightFile reports whether a constant of the given element type and element count belongs in the weight file rather than inline in MIL text. It mirrors coremltools' should_use_weight_file: at least 10 elements and an element type the target specification version stores in a blob.

func ValidateNames added in v0.6.17

func ValidateNames(prog *Program) error

ValidateNames reports the first identifier in prog that is not a legal MIL identifier. Invalid names are emitted verbatim by the MIL text writer and produce a syntactically invalid program that only fails, opaquely, inside Apple's compiler. Use SanitizeProgram to repair them.

func ValidateProgram added in v0.6.17

func ValidateProgram(prog *Program) error

ValidateProgram validates structural requirements of an MIL Program.

func ValidateTensorValue added in v0.6.17

func ValidateTensorValue(dt DataType, tv *TensorValue) error

ValidateTensorValue reports whether tv stores its data in the one field the MIL reader consults for element type dt.

func WriteMILBlob added in v0.5.4

func WriteMILBlob(entries []BlobEntry) (data []byte, offsets []uint64)

WriteMILBlob builds a MIL Blob Storage v2 weight file from the given entries. Returns the complete file bytes and the BLOBFILE offsets (one per entry) that should be used in MIL text.

func WriteMLPackage added in v0.5.0

func WriteMLPackage(dir string, modelProto []byte, weightSrc string) error

WriteMLPackage creates a .mlpackage directory at dir containing the given model protobuf and optional weights. The directory can be read back by readMLPackage or passed to MLModel.compileModelAtURL:.

The layout matches Apple's coremltools format:

dir/
├── Manifest.json
└── Data/
    └── com.apple.CoreML/
        ├── model.mlmodel     (modelProto bytes)
        └── weights/          (copied from weightSrc if provided)

Manifest paths use "com.apple.CoreML/..." (without Data/ prefix); the Data/ directory is implicit when resolving paths on disk.

If weightSrc is a directory, it is treated as the weights directory itself: its contents are copied under weights/ preserving relative paths, so a weightSrc containing weight.bin produces weights/weight.bin and BLOBFILE references of the form @model_path/weights/... resolve. If weightSrc is a single file, it is copied as weights/weight.bin.

Types

type Argument

type Argument struct {
	Bindings []Binding // field 1
}

Argument is an Operation input (list of bindings). Proto: MILSpec.Argument

type ArrayDataType

type ArrayDataType int32

ArrayDataType identifies Core ML multi-array element types.

const (
	ArrayDataTypeInvalid ArrayDataType = 0
	ArrayDataTypeFloat16 ArrayDataType = 65552
	ArrayDataTypeFloat32 ArrayDataType = 65568
	ArrayDataTypeDouble  ArrayDataType = 65600
	ArrayDataTypeInt32   ArrayDataType = 131104
	ArrayDataTypeInt8    ArrayDataType = 131080
)

type ArrayFeatureType

type ArrayFeatureType struct {
	Shape    []int64
	DataType ArrayDataType
	// contains filtered or unexported fields
}

ArrayFeatureType describes a Core ML multi-array feature.

type Binding

type Binding struct {
	Name  string // field 1 (oneof)
	Value *Value // field 2 (oneof)
}

Binding is either a name reference or an inline value. Exactly one of Name and Value is set; if both are, Value wins. Name has no presence bit, so an empty name is indistinguishable from an unset one and is never emitted. Proto: MILSpec.Argument.Binding

type BlobDataType added in v0.5.4

type BlobDataType uint32

BlobDataType identifies element types in MIL blob storage.

const (
	BlobDataTypeFloat16    BlobDataType = 1
	BlobDataTypeFloat32    BlobDataType = 2
	BlobDataTypeUInt8      BlobDataType = 3
	BlobDataTypeInt8       BlobDataType = 4
	BlobDataTypeBFloat16   BlobDataType = 5
	BlobDataTypeInt16      BlobDataType = 6
	BlobDataTypeUInt16     BlobDataType = 7
	BlobDataTypeInt4       BlobDataType = 8
	BlobDataTypeUInt1      BlobDataType = 9
	BlobDataTypeUInt2      BlobDataType = 10
	BlobDataTypeUInt4      BlobDataType = 11
	BlobDataTypeUInt3      BlobDataType = 12
	BlobDataTypeUInt6      BlobDataType = 13
	BlobDataTypeInt32      BlobDataType = 14
	BlobDataTypeUInt32     BlobDataType = 15
	BlobDataTypeFloat8E4M3 BlobDataType = 16
	BlobDataTypeFloat8E5M2 BlobDataType = 17
)

func DataTypeToBlobDataType added in v0.5.4

func DataTypeToBlobDataType(dt DataType) (BlobDataType, error)

MILBlobDataTypeName returns the MIL DataType enum for a BlobDataType.

type BlobEntry added in v0.5.4

type BlobEntry struct {
	DType BlobDataType
	Data  []byte

	// NumElements is the logical element count. It is required for sub-byte
	// element types, where the trailing partial byte must be reported in the
	// metadata's padding_size_in_bits; it is ignored for byte-sized types.
	NumElements int
}

BlobEntry describes a single tensor to write into a MILBlob weight file.

type BlobFileValue

type BlobFileValue struct {
	FileName string // field 1
	Offset   uint64 // field 2
}

BlobFileValue references weight data in a blob file. Proto: MILSpec.BlobFileValue

type Block

type Block struct {
	Inputs     []NamedValueType // field 1
	Outputs    []string         // field 2
	Operations []*Operation     // field 3
}

Block is a sequence of operations. Proto: MILSpec.Block

type ColorSpace added in v0.6.17

type ColorSpace int32

ColorSpace identifies an image feature's pixel format. Proto: CoreML.Specification.ImageFeatureType.ColorSpace

const (
	ColorSpaceInvalid          ColorSpace = 0
	ColorSpaceGrayscale        ColorSpace = 10
	ColorSpaceRGB              ColorSpace = 20
	ColorSpaceBGR              ColorSpace = 30
	ColorSpaceGrayscaleFloat16 ColorSpace = 40
)

type CoreMLModel added in v0.5.4

type CoreMLModel struct{}

CoreMLModel wraps a loaded MLModel for inference. Only functional on darwin.

func LoadCoreMLModel added in v0.5.4

func LoadCoreMLModel(modelcPath string) (*CoreMLModel, error)

LoadCoreMLModel loads a compiled .mlmodelc from disk. Only available on darwin.

func (*CoreMLModel) Close added in v0.5.4

func (m *CoreMLModel) Close()

Close releases the CoreML model reference.

func (*CoreMLModel) Predict added in v0.5.4

func (m *CoreMLModel) Predict(inputs []PredictInput, outputName string) (*PredictOutput, error)

Predict runs inference. Only available on darwin.

type DataType

type DataType int32

DataType identifies element types in MIL. Proto: MILSpec.DataType

const (
	DataTypeFloat16  DataType = 10
	DataTypeFloat32  DataType = 11
	DataTypeFloat64  DataType = 12
	DataTypeBFloat16 DataType = 13
	DataTypeInt8     DataType = 21
	DataTypeInt16    DataType = 22
	DataTypeInt32    DataType = 23
	DataTypeInt64    DataType = 24
	DataTypeInt4     DataType = 25
	DataTypeUInt8    DataType = 31
	DataTypeUInt16   DataType = 32
	DataTypeUInt32   DataType = 33
	DataTypeUInt64   DataType = 34
	// The sub-byte block is deliberately non-monotonic in MIL.proto; these
	// numbers are the wire contract, not a sorted sequence.
	DataTypeUInt4        DataType = 35
	DataTypeUInt2        DataType = 36
	DataTypeUInt1        DataType = 37
	DataTypeUInt6        DataType = 38
	DataTypeUInt3        DataType = 39
	DataTypeFloat8E4M3FN DataType = 40
	DataTypeFloat8E5M2   DataType = 41
	DataTypeBool         DataType = 1
	DataTypeString       DataType = 2
)

func (DataType) FieldForDataType added in v0.6.17

func (dt DataType) FieldForDataType() (TensorValueField, error)

FieldForDataType reports which TensorValue field an immediate constant of this element type must use, mirroring coremltools' _tensor_field_by_type. Note the asymmetry: uint32 goes to Bytes while int32 goes to Ints, and int16/uint16 go to Ints widened to int32.

func (DataType) String

func (dt DataType) String() string

String returns the MIL text name for the data type.

type DictionaryFeatureType added in v0.6.17

type DictionaryFeatureType struct {
	KeyType string
}

DictionaryFeatureType describes a dictionary boundary feature.

type DictionaryMapEntry added in v0.6.17

type DictionaryMapEntry struct {
	Key   *Value
	Value *Value
}

DictionaryMapEntry represents a key/value pair in a dictionary constant.

type DictionaryType added in v0.6.17

type DictionaryType struct {
	KeyType   *ValueType // field 1
	ValueType *ValueType // field 2
}

DictionaryType describes a MIL dictionary type.

type DictionaryValue added in v0.6.17

type DictionaryValue struct {
	Entries []DictionaryMapEntry
}

DictionaryValue holds structured dictionary constants.

type Dimension

type Dimension struct {
	Constant uint64 // from ConstantDimension.size (field 1.1)
	Unknown  bool   // true if UnknownDimension
	Variadic bool   // true if UnknownDimension.variadic is true
}

Dimension is a tensor Dimension (constant, unknown, or variadic). Proto: MILSpec.Dimension

type FeatureDescription

type FeatureDescription struct {
	Name string       // field 1
	Type *FeatureType // field 3
	// contains filtered or unexported fields
}

FeatureDescription is a named, typed model feature. Proto: CoreML.Specification.FeatureDescription

type FeatureType

type FeatureType struct {
	MultiArrayType *ArrayFeatureType
	ImageType      *ImageFeatureType
	StringType     bool
	Int64Type      bool
	DoubleType     bool
	DictionaryType *DictionaryFeatureType
	SequenceType   *SequenceFeatureType
	StateArrayType *ArrayFeatureType
	IsOptional     bool
	// contains filtered or unexported fields
}

FeatureType describes a Core ML model feature type.

type Function

type Function struct {
	Inputs               []NamedValueType  // field 1
	OpSet                string            // field 2
	BlockSpecializations map[string]*Block // field 3
	Attributes           map[string]*Value // field 4
}

Function is an MIL Function. Proto: MILSpec.Function

type FunctionDescription added in v0.6.17

type FunctionDescription struct {
	Name    string               // field 1
	Inputs  []FeatureDescription // field 2
	Outputs []FeatureDescription // field 3
	States  []FeatureDescription // field 6
	// contains filtered or unexported fields
}

FunctionDescription describes one entry point of a multi-function model. Proto: CoreML.Specification.FunctionDescription

type ImageFeatureType added in v0.6.17

type ImageFeatureType struct {
	Width      int64      // field 1
	Height     int64      // field 2
	ColorSpace ColorSpace // field 3
	// contains filtered or unexported fields
}

ImageFeatureType describes an image boundary feature.

type ImmediateValue

type ImmediateValue struct {
	// Exactly one of these is set.
	Tensor     *TensorValue     // field 1
	Tuple      *TupleValue      // field 2
	List       *ListValue       // field 3
	Dictionary *DictionaryValue // field 4
}

ImmediateValue holds inline constant data. Proto: MILSpec.ImmediateValue

type ListType added in v0.6.17

type ListType struct {
	ElementType *ValueType // field 1
	Length      int64      // field 2
}

ListType describes a MIL list type.

type ListValue added in v0.6.17

type ListValue struct {
	Values []*Value // field 1
}

ListValue holds structured list constants.

type Model

type Model struct {
	SpecVersion int32            // field 1
	Description ModelDescription // field 2
	MLProgram   *Program         // field 502 (oneof)
	// contains filtered or unexported fields
}

Model is the top-level CoreML model container. Proto: CoreML.Specification.Model

type ModelDescription

type ModelDescription struct {
	// Functions and DefaultFunctionName describe multi-function models.
	// When Functions is non-empty the model-level Inputs/Outputs/States
	// must be empty: the proto reserves them for the single-function case.
	Functions           []FunctionDescription // field 20
	DefaultFunctionName string                // field 21

	Inputs  []FeatureDescription // field 1
	Outputs []FeatureDescription // field 10
	States  []FeatureDescription // field 13

	Metadata *ModelMetadata // field 100
	// contains filtered or unexported fields
}

ModelDescription describes model inputs, outputs, and metadata. Proto: CoreML.Specification.ModelDescription

type ModelMetadata added in v0.6.17

type ModelMetadata struct {
	ShortDescription string            // field 1
	VersionString    string            // field 2
	Author           string            // field 3
	License          string            // field 4
	UserDefined      map[string]string // field 100
}

ModelMetadata carries informational model metadata. Proto: CoreML.Specification.Metadata

type NamedValueType

type NamedValueType struct {
	Name string     // field 1
	Type *ValueType // field 2
}

NamedValueType is a (name, type) pair. Proto: MILSpec.NamedValueType

type Operation

type Operation struct {
	Type       string               // field 1
	Inputs     map[string]*Argument // field 2
	Outputs    []NamedValueType     // field 3
	Blocks     []*Block             // field 4
	Attributes map[string]*Value    // field 5
}

Operation is a single MIL Operation. Proto: MILSpec.Operation

type PredictInput added in v0.5.4

type PredictInput struct {
	Name    string
	Data    unsafe.Pointer
	Shape   []int
	Strides []int
	DType   coreml.MLMultiArrayDataType
}

PredictInput is a named tensor input for CoreML prediction.

type PredictOutput added in v0.5.4

type PredictOutput struct {
	Bytes []byte // copied from CoreML output buffer
	Shape []int
	DType coreml.MLMultiArrayDataType
}

PredictOutput holds the result of a CoreML prediction.

type Program

type Program struct {
	Version    int64                // field 1
	Functions  map[string]*Function // field 2
	Attributes map[string]*Value    // field 4
}

Program is an MIL Program. Proto: MILSpec.Program

type SequenceFeatureType added in v0.6.17

type SequenceFeatureType struct {
	ElementType *FeatureType
}

SequenceFeatureType describes a sequence boundary feature.

type StateType

type StateType struct {
	WrappedType *ValueType // field 1
}

StateType wraps a ValueType for stateful operations. Proto: MILSpec.StateType

type TensorType

type TensorType struct {
	DataType   DataType    // field 1
	Rank       int64       // field 2
	Dimensions []Dimension // field 3
}

TensorType describes a tensor's element type and shape. Proto: MILSpec.TensorType

type TensorValue

type TensorValue struct {
	// Exactly one of these is set.
	Floats  []float32 // field 1
	Ints    []int32   // field 2
	Bools   []bool    // field 3
	Strings []string  // field 4
	Longs   []int64   // field 5
	Doubles []float64 // field 6
	Bytes   []byte    // field 7
}

TensorValue holds tensor data inline. Proto: MILSpec.TensorValue

func (*TensorValue) SetField added in v0.6.17

func (tv *TensorValue) SetField() TensorValueField

SetField reports which field of tv holds data, or 0 if none does.

type TensorValueField added in v0.6.17

type TensorValueField int

TensorValueField identifies the TensorValue oneof field a MIL immediate constant of a given element type must use. Which field carries the data is fixed by the element type, not free choice: the MIL reader picks the field from the tensor's declared dtype, so a mismatch is read as an empty value.

const (
	TensorValueFloats TensorValueField = iota + 1
	TensorValueInts
	TensorValueBools
	TensorValueStrings
	TensorValueLongs
	TensorValueDoubles
	TensorValueBytes
)

type TupleType added in v0.6.17

type TupleType struct {
	Types []*ValueType // field 1
}

TupleType describes a MIL tuple type.

type TupleValue added in v0.6.17

type TupleValue struct {
	Values []*Value // field 1
}

TupleValue holds structured tuple constants.

type Value

type Value struct {
	Type *ValueType // field 2

	// Exactly one of these is set.
	Immediate *ImmediateValue // field 3
	BlobFile  *BlobFileValue  // field 5
}

value is an MIL value (immediate or blob reference). Proto: MILSpec.Value

type ValueType

type ValueType struct {
	// Exactly one of these is set.
	TensorType     *TensorType     // field 1
	ListType       *ListType       // field 2
	TupleType      *TupleType      // field 3
	DictionaryType *DictionaryType // field 4
	StateType      *StateType      // field 5
}

ValueType describes a MIL value's type. Proto: MILSpec.ValueType

Directories

Path Synopsis
internal
opschema
Package opschema holds the per-op input specifications MIL ops are declared with in coremltools.
Package opschema holds the per-op input specifications MIL ops are declared with in coremltools.
Package nnproto encodes CoreML NeuralNetwork models (specification version 1) as .mlmodel protobuf bytes.
Package nnproto encodes CoreML NeuralNetwork models (specification version 1) as .mlmodel protobuf bytes.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL