coremltools 模型格式规范深度解读：LinkedModel 链接模型（LinkedModel.proto）

• AI 应用
• 机器学习
• 模型优化

导读

本文围绕 coremltools 仓库中的格式规范文档 LinkedModel.rst，完整剖析LinkedModel这一用于包装（引用）另一个已编译 Core ML 模型（如.mlmodelc）的规范类型。你将掌握LinkedModel与LinkedModelFile两个 proto 消息的字段定义、搜索路径语义（相对路径、绝对路径、$BUNDLE_MAIN、$BUNDLE_IDENTIFIER）、源码级验证规则，以及它在模型比较与系统版本特性判定中的实际作用，可直接用于理解 Core ML 模型格式（.mlmodel/.mlmodelc）的二进制布局与生成代码。

一、LinkedModel 是什么：包装外部编译模型的规范类型

在 Core ML 模型规范（Model Specification）中，一个.mlmodel/.mlmodelc文件并不总是"自包含"的——规范允许一种特殊的模型类型LinkedModel，其官方定义只有一句话：

A model which wraps another (compiled) model external to this one

即：LinkedModel 是一个包装模型，本身不携带权重与网络结构，而是通过文件系统定位并引用另一个已经编译好的模型文件。典型场景是：主模型引用一个外部的特征提取器（例如MyFeatureExtractor.mlmodelc），从而实现多模型文件的组合与复用，而无需把被引用的模型内容复制进主模型。

从仓库的源码看，LinkedModel被归类为"Custom and linked models"（自定义模型与链接模型）分组，与CustomModel并列。在 Model.proto 的Model.Typeoneof 中：

// Custom and linked models CustomModel customModel = 555; LinkedModel linkedModel = 556;

同时 Model.proto 通过import public "LinkedModel.proto";引入该类型，并在文件头部注释中将LinkedModel列入 "Other models"（其他模型）类别（见 Model.proto）。在格式文档体系里，OtherModels.rst 的目录（toctree）中也收录了LinkedModel.rst，与CustomModel、TextClassifier、VisionFeaturePrint等并列。

二、消息定义：LinkedModel 与 LinkedModelFile 完整剖析

规范文档（LinkedModel.rst）与源文件（LinkedModel.proto）内容一致，共定义两个消息。

2.1 LinkedModel：外层包装消息

message LinkedModel { oneof LinkType { // A model located via a file system path LinkedModelFile linkedModelFile = 1; } }

关键点：

• oneof LinkType：proto3 的oneof语义要求这组字段中至多只能设置一个。当前规范仅定义了一种链接类型linkedModelFile（通过文件系统路径定位模型），字段编号为 1。oneof结构为未来扩展其他链接方式（如 URL、符号链接等）预留了空间，同时保证序列化时不会出现多值歧义。
• 嵌套关系：LinkedModel只包含一个LinkedModelFile子消息，本身没有直接承载任何字符串字段，所有配置都放在LinkedModelFile中。

2.2 LinkedModelFile：文件定位细节

message LinkedModelFile { // Model file name: e.g. "MyFetureExtractor.mlmodelc" StringParameter linkedModelFileName = 1; // Search path to find the linked model file // Multiple paths can be searched using the unix-style path separator ":" // Each path can be relative (to this model) or absolute // // An empty string is the same as the relative search path "." // which searches in the same location as this model file // // There are some special paths which start with $ // - $BUNDLE_MAIN - Indicates to look in the main bundle // - $BUNDLE_IDENTIFIER(identifier) - Looks in Bunde with given identifier StringParameter linkedModelSearchPath = 2; }

两个字段均为StringParameter类型（注意：StringParameter是 Core ML 规范定义的"带默认值的字符串参数"包装消息，见下文第三节），语义如下：

三、StringParameter：链接配置的默认值载体

LinkedModelFile的两个字段都不是裸的string，而是StringParameter。该包装消息定义于 Parameters.proto：

/* * String parameter, * A default string value must be provided */ message StringParameter { string defaultValue = 1; }

也就是说，LinkedModel的配置以"参数化"方式存储：实际生效的是defaultValue。这一设计在仓库的多个源码位置得到印证：

• 验证器 LinkedModelValidator.cpp 读取的就是linkedmodelfilename().defaultvalue()与linkedmodelsearchpath().defaultvalue()；
• 模型相等性比较 Comparison.cpp 同样逐字段比较两个LinkedModel的defaultvalue()。

从源码结构可以推断：StringParameter的设计使得模型规范未来可以扩展出"允许用户覆盖默认值"的能力（类似超参数），但当前LinkedModel的解析只使用其defaultValue。

四、linkedModelSearchPath 搜索路径语义全解

linkedModelSearchPath是决定"去哪里找被链接模型"的关键字段，规范注释给出了四层语义，这里结合实现逐条展开：

4.1 空字符串等价于当前目录

An empty string is the same as the relative search path "." which searches in the same location as this model file

当linkedModelSearchPath的defaultValue为空字符串时，等价于相对搜索路径"."（或"./"），即在当前模型文件所在目录中查找。这一点在验证器中得到确认： LinkedModelValidator.cpp 明确写出"这是允许的，等同于把搜索路径设为"."或"./""。

4.2 冒号分隔多路径

Multiple paths can be searched using the unix-style path separator ":"

与PATH环境变量类似，多个搜索路径用 Unix 风格的分隔符:连接。例如：

ExtractorModels:./Assets:../../SharedModels

运行时按顺序逐个目录查找linkedModelFileName指定的文件，命中即停。这个字符串整体存放在StringParameter.defaultValue中。

4.3 相对路径与绝对路径

Each path can be relative (to this model) or absolute

• 相对路径：以当前模型文件所在位置为基准解析（与"."语义一致）；
• 绝对路径：从文件系统根目录开始解析，可用于指向模型沙盒之外的共享目录（受系统权限约束）。

4.4 $ 开头的特殊路径

There are some special paths which start with $

• $BUNDLE_MAIN- Indicates to look in the main bundle
• $BUNDLE_IDENTIFIER(identifier)- Looks in Bundle with given identifier

搜索路径支持两种$前缀的"魔法值"，用于在 Apple 平台的 App Bundle 环境中定位模型：

规范注释原文在第二行将 "Bundle" 误拼为 "Bunde"，实际语义为前者。从源码结构看，这两类特殊路径的解析发生在 Core ML 框架运行时（mlmodel目录的 C++ 实现仅负责格式与验证），仓库内 LinkedModel.proto 的注释即唯一权威说明，使用时需确保目标 Bundle 已随应用正确打包。

五、源码级验证规则：LinkedModelValidator.cpp

模型规范文件在落地为.mlmodelc或加载时，会经过libmlmodelspec（mlmodel 目录下的 C++ 实现）的验证。LinkedModel的验证逻辑完整实现在 LinkedModelValidator.cpp（模板特化validate<MLModelType_linkedModel>），共五条规则：

特别值得注意的是第 5 条与第 2 条：

• 文件名是必填项：linkedModelFileName为空会直接导致验证失败，因为"链接到谁"是LinkedModel存在的唯一意义；
• 搜索路径是选填项：linkedModelSearchPath为空被显式放行（对应 4.1 节的"."等价语义）；
• 不可更新：LinkedModel只是引用外部已编译模型，本身没有可训练参数，因此规范层面直接禁止将其标记为isUpdatable。

六、模型相等性与系统版本特性：源码中的两个用途

除验证外，LinkedModel还在仓库的两处核心逻辑中被消费：

6.1 模型相等性比较

Comparison.cpp 为LinkedModel实现了operator==，比较逻辑与验证器完全对齐：

1. 先比较LinkType_case()（oneof 当前选中了哪个分支）；
2. 若为kLinkedModelFile，则依次比较linkedModelFileName.defaultValue与linkedModelSearchPath.defaultValue；
3. LINKTYPE_NOT_SET（未设置任何链接类型）视为相等。

这保证了两个内容相同的.mlmodel在规范层面可以判定为"相同模型"，是模型比对、去重等工具的基础。

6.2 iOS 13 新特性标记

Utils.cpp 中的hasIOS13Features函数将LinkedModel视为引入于 iOS 13 的模型特性之一：

case Specification::Model::kKNearestNeighborsClassifier: case Specification::Model::kLinkedModel: case Specification::Model::kItemSimilarityRecommender: case Specification::Model::kSoundAnalysisPreprocessing: return true;

从源码结构可以推断：当模型是LinkedModel时，工具链会将其识别为需要 iOS 13+ 运行环境支持的类型，从而影响部署目标的兼容性判定（相关判定逻辑可参考 Model.proto 中的linkedModel = 556字段编号，其位于 555–560 区段，属于较晚引入的模型类型）。

七、Python 侧：生成的 protobuf 代码与 coremltools 使用

coremltools 作为 Python 工具包，直接携带了由该 proto 生成的 Python 绑定代码 coremltools/proto/LinkedModel_pb2.py。该文件是LinkedModel.proto经protoc编译产物，可以从其序列化描述符字符串中确认消息结构完全对应：

LinkedModel: linkedModelFile (LinkedModelFile) = 1 → oneof LinkType LinkedModelFile: linkedModelFileName (StringParameter) = 1 linkedModelSearchPath (StringParameter) = 2

这意味着在 Python 侧可以通过 protobuf 运行时直接读取/构造LinkedModel规范，例如：

from coremltools.proto.LinkedModel_pb2 import LinkedModel, LinkedModelFile from coremltools.proto.Parameters_pb2 import StringParameter linked = LinkedModel() file_ref = LinkedModelFile() file_ref.linkedModelFileName.defaultValue = "MyFeatureExtractor.mlmodelc" file_ref.linkedModelSearchPath.defaultValue = ".::$BUNDLE_MAIN" linked.linkedModelFile.CopyFrom(file_ref)

注意：coremltools.proto下的*_pb2.py是规范生成代码，实际转换/生成LinkedModel的完整链路需要配合 Model_pb2.py 中Model.linkedModel = 556字段与编译后的.mlmodelc产物一起使用。从仓库结构看，规范侧（mlmodel/format）与 Python 绑定侧（coremltools/proto）均以 protobuf 定义为准，二者由同一份.proto生成，确保跨语言一致。

八、小结与文件索引

LinkedModel是 Core ML 规范中用于"引用外部已编译模型"的轻量包装类型：外层LinkedModel通过 oneof 承载LinkedModelFile，内层用StringParameter包装"文件名 + 搜索路径"两个配置；搜索路径支持:多路径、相对/绝对路径与$BUNDLE_MAIN/$BUNDLE_IDENTIFIER(identifier)特殊值；验证器强制要求文件名非空、禁止 updatable，并放行空搜索路径。

与之直接相关的仓库文件（均以仓库根目录为基准）：

若需要深入理解"Other models"家族中的其他类型（如CustomModel、TextClassifier、WordTagger等），可继续阅读 OtherModels.rst 所列文档；若关注模型验证框架的整体结构，可查看 mlmodel/src/Validation 目录下的其他验证器实现。

• AI 应用
• 机器学习
• 模型优化