🤗 Exporters

👷 开发中 👷

这个包允许你将 🤗 Transformers 模型导出为 Core ML 格式。

对于将模型转换为 TFLite 格式，我们建议使用 Optimum。

何时使用 🤗 Exporters

🤗 Transformers 模型可以用 PyTorch、TensorFlow 或 JAX 实现。然而，在部署时，你可能希望使用不同的框架，例如 Core ML。这个库可以轻松地将 Transformers 模型转换为这种格式。

Exporters 包的目标是比使用 coremltools 编写自己的转换脚本更加方便，并且与 🤗 Transformers 库和 Hugging Face Hub 紧密集成。

为了更便捷的方式，Exporters 提供了一个 无需代码的 Transformers 到 Core ML 转换 Space。你可以无需安装任何东西就试用它，以检查你感兴趣的模型是否可以被转换。如果转换成功，转换后的 Core ML 权重将会被推送到 Hub。如需更多灵活性和关于转换过程的详细信息，请继续阅读。

注意：请记住，Transformer 模型通常非常大，并不总是适合在移动设备上使用。最好先使用 🤗 Optimum 对模型进行 推理优化。

安装

克隆这个仓库：

$ git clone https://github.com/huggingface/exporters.git

将其作为 Python 包安装：

$ cd exporters
$ pip install -e .

完成！

注意：Core ML 导出器可以在 Linux 上使用，但推荐使用 macOS。

Core ML

Core ML 是 Apple 的软件库，用于在设备上快速运行神经网络和其他类型的机器学习模型。它可以在 macOS、iOS、tvOS 和 watchOS 上使用，并针对 CPU、GPU 和 Apple Neural Engine 进行了优化。尽管 Core ML 框架是专有的，但 Core ML 文件格式是一种开放格式。

Core ML 导出器使用 coremltools 将 PyTorch 或 TensorFlow 模型转换为 Core ML 格式。

exporters.coreml 包允许你通过配置对象将模型检查点转换为 Core ML 模型。这些配置对象已经为许多模型架构准备好了，并且设计为易于扩展到其他架构。

预置的配置包括以下架构：

• BEiT
• BERT
• ConvNeXT
• CTRL
• CvT
• DistilBERT
• DistilGPT2
• GPT2
• LeViT
• MobileBERT
• MobileViT
• SegFormer
• SqueezeBERT
• Vision Transformer (ViT)
• YOLOS

在此处查看以获取支持的完整模型列表。

将模型导出为 Core ML

exporters.coreml 包可以从命令行作为 Python 模块使用。要使用预置配置导出检查点，请执行以下操作：

python -m exporters.coreml --model=distilbert-base-uncased exported/

这会导出由 --model 参数定义的检查点的 Core ML 版本。在本例中是 distilbert-base-uncased，但它可以是 Hugging Face Hub 上的任何检查点，也可以是本地存储的检查点。

生成的 Core ML 文件将保存到 exported 目录中，名为 Model.mlpackage。你也可以指定一个文件名，而不是目录，例如 DistilBERT.mlpackage。

转换过程中输出大量警告信息和其他日志信息是正常现象，可以安全地忽略。如果一切顺利，导出应该以以下日志结束：

正在验证 Core ML 模型...
	-[✓] Core ML 模型输出名称与参考模型匹配 ({'last_hidden_state'})
	- 验证 Core ML 模型输出 "last_hidden_state":
		-[✓] (1, 128, 768) 与 (1, 128, 768) 匹配
		-[✓] 所有值接近（atol: 0.0001）
一切正常，模型已保存至：exported/Model.mlpackage

注意：虽然在 Linux 上也可以将模型导出为 Core ML，但验证步骤只能在 Mac 上执行，因为它需要 Core ML 框架来运行模型。

生成的文件是 Model.mlpackage。该文件可以添加到 Xcode 项目中，并加载到 macOS 或 iOS 应用程序中。

导出的 Core ML 模型使用 mlpackage 格式，模型类型为 ML Program。这种格式于 2021 年推出，至少需要 iOS 15、macOS 12.0 和 Xcode 13。我们更倾向于使用这种格式，因为它代表了 Core ML 的未来。Core ML 导出器也可以生成旧的 .mlmodel 格式，但不推荐使用。

对于 Hub 上的 TensorFlow 检查点，过程相同。例如，你可以从 Keras 组织导出一个纯 TensorFlow 检查点，如下所示：

python -m exporters.coreml --model=keras-io/transformers-qa exported/

要导出本地存储的模型，你需要将模型的权重和分词器文件存储在一个目录中。例如，我们可以加载并保存一个检查点，如下所示：

>>> from transformers import AutoTokenizer、AutoModelForSequenceClassification

>>> # 从 Hub 加载分词器和 PyTorch 权重
>>> tokenizer = AutoTokenizer.from_pretrained("distilbert-base-uncased")
>>> pt_model = AutoModelForSequenceClassification.from_pretrained("distilbert-base-uncased")
>>> # 保存到磁盘
>>> tokenizer.save_pretrained("local-pt-checkpoint")
>>> pt_model.save_pretrained("local-pt-checkpoint")

一旦检查点被保存，你可以通过将 --model 参数指向包含检查点文件的目录来将其导出为 Core ML：

python -m exporters.coreml --model=local-pt-checkpoint exported/

为不同模型拓扑选择功能

每个现成的配置都带有一组 功能，使您可以为不同类型的拓扑或任务导出模型。如下表所示，每种功能都与一个不同的自动类相关联：

功能	自动类
default, default-with-past	AutoModel
causal-lm, causal-lm-with-past	AutoModelForCausalLM
ctc	AutoModelForCTC
image-classification	AutoModelForImageClassification
masked-im	AutoModelForMaskedImageModeling
masked-lm	AutoModelForMaskedLM
multiple-choice	AutoModelForMultipleChoice
next-sentence-prediction	AutoModelForNextSentencePrediction
object-detection	AutoModelForObjectDetection
question-answering	AutoModelForQuestionAnswering
semantic-segmentation	AutoModelForSemanticSegmentation
seq2seq-lm, seq2seq-lm-with-past	AutoModelForSeq2SeqLM
sequence-classification	AutoModelForSequenceClassification
speech-seq2seq, speech-seq2seq-with-past	AutoModelForSpeechSeq2Seq
token-classification	AutoModelForTokenClassification

对于每种配置，您可以通过 FeaturesManager 查看支持的功能列表。例如，对于 DistilBERT，我们可以这样做：

>>> from exporters.coreml.features import FeaturesManager

>>> distilbert_features = list(FeaturesManager.get_supported_features_for_model_type("distilbert").keys())
>>> print(distilbert_features)
['default', 'masked-lm', 'multiple-choice', 'question-answering', 'sequence-classification', 'token-classification']

然后，您可以将这些功能之一传递给 exporters.coreml 包中的 --feature 参数。例如，要导出一个文本分类模型，我们可以从 Hub 中选择一个微调过的模型并运行：

python -m exporters.coreml --model=distilbert-base-uncased-finetuned-sst-2-english \
                           --feature=sequence-classification exported/

这将显示以下日志：

Validating Core ML model...
	- Core ML model is classifier, validating output
		-[✓] predicted class NEGATIVE matches NEGATIVE
		-[✓] number of classes 2 matches 2
		-[✓] all values close (atol: 0.0001)
All good, model saved at: exported/Model.mlpackage

请注意，在这种情况下，导出的模型是一个 Core ML 分类器，它除了输出概率字典外，还会预测得分最高的类别名称，而不是我们之前在 distilbert-base-uncased 检查点中看到的 last_hidden_state。这是预期的行为，因为该微调过的模型具有序列分类头。

带有 with-past 后缀的功能（例如 causal-lm-with-past）对应于具有预计算隐藏状态（注意力块中的键和值）的模型拓扑，这些状态可用于快速自回归解码。

配置导出选项

要查看所有可能的选项，请在命令行中运行以下命令：

python -m exporters.coreml --help

导出模型至少需要以下参数：

• -m <model>：来自 Hugging Face Hub 的模型 ID，或用于加载模型的本地路径。
• --feature <task>：模型应执行的任务，例如 "image-classification"。请参阅上表以了解可能的任务名称。
• <output>：存储生成的 Core ML 模型的路径。

输出路径可以是一个文件夹，在这种情况下文件将被命名为 Model.mlpackage，或者您也可以直接指定文件名。

还可以提供以下附加参数：

• --preprocessor <value>：使用哪种类型的预处理器。auto 会尝试自动检测。可能的值有：auto（默认）、tokenizer、feature_extractor、processor。
• --atol <number>：验证模型时使用的绝对差异容差。默认值为 1e-4。
• --quantize <value>：是否对模型权重进行量化。可能的量化选项有：float32 表示不进行量化（默认），或 float16 表示 16 位浮点数。
• --compute_units <value>：是否针对 CPU、GPU 和/或神经引擎优化模型。可能的值有：all（默认）、cpu_and_gpu、cpu_only、cpu_and_ne。

使用导出的模型

在应用程序中使用导出的模型就像使用任何其他 Core ML 模型一样。将模型添加到 Xcode 后，它会自动生成一个 Swift 类，让您可以在应用程序内进行预测。

根据所选的导出选项，您可能仍然需要对输入和输出张量进行预处理或后处理。

对于图像输入，无需进行任何预处理，因为 Core ML 模型已经会对像素进行归一化处理。对于分类器模型，Core ML 模型会将预测结果输出为概率字典。而对于其他模型，您可能需要做更多的工作。

Core ML 没有分词器的概念，因此文本模型仍然需要手动对输入数据进行分词。这里有一个示例说明如何在 Swift 中进行分词。

覆盖配置对象中的默认设置

Core ML 的一个重要目标是让开发者能够轻松地在应用中使用模型。在可能的情况下，Core ML 导出器会向模型添加额外的操作，从而避免您自行进行预处理和后处理。

具体来说：

• 图像模型会自动在模型内部执行像素归一化操作，因此您无需再对图像进行预处理，除非需要调整大小或裁剪。

• 对于分类模型，会添加一个 softmax 层，并将标签包含在模型文件中。Core ML 会区分分类模型与其他类型的神经网络。对于每个输入样本仅输出单个分类预测的模型，Core ML 会使其直接输出获胜的类别标签以及概率字典，而不是原始的 logits 张量。在可行的情况下，导出器会使用这种特殊的分类模型类型。

• 其他模型虽然也会输出 logits，但并不符合 Core ML 对分类模型的定义，例如 token-classification 任务会为序列中的每个标记输出一个预测。在这种情况下，导出器同样会添加一个 softmax 层，将 logits 转换为概率。标签名称会被添加到模型的元数据中。Core ML 会忽略这些标签名称，但您可以通过编写几行 Swift 代码来获取它们。

• semantic-segmentation 模型会将输出图像上采样回原始的空间尺寸，并应用 argmax 操作以获得预测的类别标签索引。它不会自动应用 softmax。

Core ML 导出器之所以做出这些选择，是因为这些设置通常是您最常需要的。如果您想覆盖上述任何默认设置，就必须创建配置对象的子类，然后通过编写一段简短的 Python 程序将模型导出为 Core ML 格式。

示例：为了防止 MobileViT 语义分割模型对输出图像进行上采样，您可以创建 MobileViTCoreMLConfig 的子类，并重写 outputs 属性，将 do_upsample 设置为 False。此外，您还可以为该输出设置其他选项，如 do_argmax 和 do_softmax。

from collections import OrderedDict
from exporters.coreml.models import MobileViTCoreMLConfig
from exporters.coreml.config import OutputDescription

class MyCoreMLConfig(MobileViTCoreMLConfig):
    @property
    def outputs(self) -> OrderedDict[str, OutputDescription]:
        return OrderedDict(
            [
                (
                    "logits",
                    OutputDescription(
                        "classLabels",
                        "每个像素的分类得分",
                        do_softmax=True,
                        do_upsample=False,
                        do_argmax=False,
                    )
                ),
            ]
        )

config = MyCoreMLConfig(model.config, "semantic-segmentation")

在这里，您还可以将输出名称从 classLabels 更改为其他名称，或者修改输出描述（“每个像素的分类得分”）。

同样，您也可以更改模型输入的属性。例如，对于文本模型，默认的序列长度介于 1 到 128 个标记之间。如果要将 DistilBERT 模型的输入序列长度固定为 32 个标记，可以按如下方式重写配置对象：

from collections import OrderedDict
from exporters.coreml.models import DistilBertCoreMLConfig
from exporters.coreml.config import InputDescription

class MyCoreMLConfig(DistilBertCoreMLConfig):
    @property
    def inputs(self) -> OrderedDict[str, InputDescription]:
        input_descs = super().inputs
        input_descs["input_ids"].sequence_length = 32
        return input_descs

config = MyCoreMLConfig(model.config, "text-classification")

使用固定的序列长度通常会生成更简单、也可能更快的 Core ML 模型。然而，对于许多模型而言，输入需要具备灵活的长度。在这种情况下，您可以为 sequence_length 指定一个元组来设置最小和最大长度。使用 (1, -1) 表示序列长度没有上限。（注意：如果将 sequence_length 设置为固定值，则批处理大小将被固定为 1。）

要了解您感兴趣的模型有哪些可用的输入和输出选项，只需创建其 CoreMLConfig 对象，并检查 config.inputs 和 config.outputs 属性即可。

并非所有输入或输出都是必需的：例如，在文本模型中，您可以移除 attention_mask 输入。如果没有这个输入，注意力掩码将始终假定为全 1（即无填充）。然而，如果任务需要 token_type_ids 输入，则必须同时提供 attention_mask 输入。

移除输入和/或输出的操作可以通过创建 CoreMLConfig 的子类并重写 inputs 和 outputs 属性来实现。

默认情况下，模型会以 ML Program 格式生成。通过将 use_legacy_format 属性重写为返回 True，即可使用较旧的 NeuralNetwork 格式。不过，这种方法并不推荐，仅作为无法转换为 ML Program 格式的模型的临时解决方案。

一旦您获得了修改后的 config 实例，就可以按照下文“导出模型”部分的说明将其用于模型导出。

需要注意的是，配置对象并不能涵盖所有内容。转换后模型的行为还受到模型的分词器或特征提取器的影响。例如，若要使用不同的输入图像尺寸，您需要使用具有不同缩放或裁剪设置的特征提取器来进行转换，而不是使用默认的特征提取器。

导出不支持架构的模型

如果您希望导出一个其架构未被该库原生支持的模型，主要需遵循以下三个步骤：

1. 实现自定义的 Core ML 配置。
2. 将模型导出为 Core ML 格式。
3. 验证 PyTorch 模型与导出模型的输出是否一致。

在本节中，我们将以 DistilBERT 的实现为例，展示每个步骤的具体操作。

实现自定义 Core ML 配置

TODO：尚未编写此部分，因为实现尚未完成。

首先从配置对象开始。我们提供了一个抽象类 CoreMLConfig，您应从中继承。

from exporters.coreml import CoreMLConfig

TODO：此处需要涵盖的内容：

• modality 属性
• 如何实现自定义算子，并附上关于此主题的 coremltools 文档链接
• 解码器模型（use_past）和编码器-解码器模型（seq2seq）

导出模型

一旦您实现了 Core ML 配置，下一步就是导出模型。我们可以使用 exporters.coreml 包提供的 export() 函数。该函数需要 Core ML 配置、基础模型以及文本模型的分词器或视觉模型的特征提取器作为输入：

from transformers import AutoConfig, AutoModelForSequenceClassification, AutoTokenizer
from exporters.coreml import export
from exporters.coreml.models import DistilBertCoreMLConfig

model_ckpt = "distilbert-base-uncased"
base_model = AutoModelForSequenceClassification.from_pretrained(model_ckpt, torchscript=True)
preprocessor = AutoTokenizer.from_pretrained(model_ckpt)

coreml_config = DistilBertCoreMLConfig(base_model.config, task="text-classification")
mlmodel = export(preprocessor, base_model, coreml_config)

注意：为了获得最佳效果，在加载模型时请将 torchscript=True 参数传递给 from_pretrained 方法。这会使模型为 PyTorch 跟踪做好准备，而这是 Core ML 转换所必需的。

export() 函数还可接受以下附加选项：

• quantize：使用 "float32" 表示不进行量化（默认值），使用 "float16" 则将权重量化为 16 位浮点数。
• compute_units：指定是否针对 CPU、GPU 和/或神经网络引擎优化模型。默认值为 coremltools.ComputeUnit.ALL。

若要导出带有预计算隐藏状态（注意力块中的键和值）的模型，以实现快速的自回归解码，可在创建 CoreMLConfig 对象时传入 use_past=True 参数。

Core ML 导出工具通常会打印大量警告和信息消息，例如：

TracerWarning: 将张量转换为 Python 布尔值可能会导致跟踪结果不正确。我们无法记录 Python 值的数据流，因此在未来该值将被视为常量。这意味着跟踪可能无法推广到其他输入！

这些消息是正常的，属于转换过程的一部分。如果确实存在问题，转换器会抛出错误。

如果导出成功，export() 函数的返回值将是一个 coremltools.models.MLModel 对象。您可以运行 print(mlmodel) 来查看 Core ML 模型的输入、输出及元数据。

您还可以选择填写模型的元数据：

mlmodel.short_description = "您的优秀模型"
mlmodel.author = "您的姓名"
mlmodel.license = "在此填写版权信息"
mlmodel.version = "1.0"

最后，保存模型。您可以在 Xcode 中打开生成的 .mlpackage 文件并进行检查。

mlmodel.save("DistilBert.mlpackage")

注意：如果使用的配置对象的 use_legacy_format 方法返回 True，则可以将模型保存为 ModelName.mlmodel，而非 .mlpackage。

导出解码器模型

基于解码器的模型可以使用包含预计算隐藏状态（自注意力块中的键和值）的 past_key_values 输入，从而实现更快的序列解码。此功能可通过在 Transformer 模型中设置 use_cache=True 来启用。

要在 Core ML 导出过程中启用此功能，请在创建 CoreMLConfig 对象时设置 use_past=True 参数：

coreml_config = CTRLCoreMLConfig(base_model.config，task="text-generation"，use_past=True)

# 或者：
coreml_config = CTRLCoreMLConfig.with_past(base_model.config, task="text-generation")

这会为模型添加多个新的输入和输出，名称如 past_key_values_0_key、past_key_values_0_value 等（输入）以及 present_key_values_0_key、present_key_values_0_value 等（输出）。

启用此选项会使模型使用起来不太方便，因为你需要跟踪许多额外的张量，但确实能显著加快序列推理速度。

必须以 is_decoder=True 加载 Transformers 模型，例如：

base_model = BigBirdForCausalLM.from_pretrained("google/bigbird-roberta-base", torchscript=True, is_decoder=True)

TODO：在 Core ML 中如何使用此功能的示例。past_key_values 张量会随着时间推移不断增大。attention_mask 张量的大小必须等于 past_key_values 的大小加上新的 input_ids。

导出编码器-解码器模型

TODO：正确撰写本节内容

你需要将模型导出为两个独立的 Core ML 模型：编码器和解码器。

按如下方式导出模型：

coreml_config = TODOCoreMLConfig(base_model.config, task="text2text-generation", seq2seq="encoder")
encoder_mlmodel = export(preprocessor, base_model.get_encoder(), coreml_config)

coreml_config = TODOCoreMLConfig(base_model.config, task="text2text-generation", seq2seq="decoder")
decoder_mlmodel = export(preprocessor, base_model, coreml_config)

当使用 seq2seq 选项时，Core ML 模型中的序列长度始终是无界的。配置对象中指定的 sequence_length 将被忽略。

这也可以与 use_past=True 结合使用。TODO：说明如何使用。

验证模型输出

最后一步是验证基础模型和导出模型的输出在一定绝对误差范围内是否一致。你可以使用 exporters.coreml 包提供的 validate_model_outputs() 函数，具体操作如下。

首先启用日志记录：

from exporters.utils import logging
logger = logging.get_logger("exporters.coreml")
logger.setLevel(logging.INFO)

然后验证模型：

from exporters.coreml import validate_model_outputs

validate_model_outputs(
    coreml_config, preprocessor, base_model, mlmodel, coreml_config.atol_for_validation
)

注意：validate_model_outputs 只能在 Mac 计算机上运行，因为它依赖 Core ML 框架来对模型进行预测。

该函数使用 CoreMLConfig.generate_dummy_inputs() 方法为基础模型和导出模型生成输入，并且可以在配置中定义绝对误差容差。我们通常发现数值一致性在 1e-6 到 1e-4 范围内，不过只要小于 1e-3 一般都可以接受。

如果验证失败并出现类似以下错误，则并不一定意味着模型有问题：

ValueError: 参考模型和 Core ML 导出模型的输出值不匹配：最大绝对差异为：0.12345

比较是基于绝对差异值进行的，在这个例子中为 0.12345，远大于默认容差值 1e-4，因此报告了错误。然而，激活值的量级也很重要。对于激活值在 1e+3 左右的模型，最大绝对差异 0.12345 通常是可接受的。

如果验证因该错误而失败，且你不确定是否真的是问题，可以对一个随机输入张量调用 mlmodel.predict()，并查看输出张量中最大的绝对值。

向 🤗 Transformers 贡献新配置

我们正致力于扩展现成配置集，并欢迎社区贡献！如果你想为库贡献自己的新增内容，你需要：

• 在 models.py 文件中实现 Core ML 配置
• 将模型架构及相应特性纳入 [~coreml.features.FeatureManager]
• 将你的模型架构添加到 test_coreml.py 中的测试用例中

故障排除：如果 Core ML Exporters 无法用于你的模型怎么办？

你希望导出的模型可能无法通过 Core ML Exporters 转换，甚至直接使用 coremltools 也无法成功。在运行这些自动化转换工具时，转换过程很可能因难以理解的错误信息而中断。或者，转换看似成功，但导出的模型却无法正常工作或产生错误的输出。

导致转换错误的常见原因包括：

• 你为转换器提供了错误的参数。task 参数应与所选模型架构匹配。例如，“feature-extraction”任务仅适用于 AutoModel 类型的模型，而不应用于 AutoModelForXYZ。此外，seq2seq 参数用于区分编码器-解码器模型与仅编码器或仅解码器模型。如果传递了无效的参数值，可能会在转换过程中引发错误，也可能生成一个虽然能运行但执行错误操作的模型。

• 模型执行了 Core ML 或 coremltools 不支持的操作。也可能是 coremltools 存在 bug，或者无法处理特别复杂的模型。

如果 Core ML 导出因后者失败，你有几种选择：

1. 在 CoreMLConfig 的 patch_pytorch_ops() 函数中实现缺失的算子。

2. 修改原始模型。这需要对模型的工作原理有深入的理解，操作并不简单。不过有时只需将某些值硬编码，而不是让 PyTorch 或 TensorFlow 根据张量形状自动计算它们。

3. 修复 coremltools。有时可以通过修改 coremltools 来忽略该问题。

4. 放弃自动化转换，转而使用 MIL 从头构建模型（MIL 文档）。MIL 是 coremltools 内部用来表示模型的中间语言，它在很多方面类似于 PyTorch。

5. 提交一个问题，我们会尽力解决。😀

已知问题

Core ML 导出器会以 mlpackage 格式导出模型。遗憾的是，对于某些模型，生成的 ML 程序并不正确。在这种情况下，建议通过将配置对象的 use_legacy_format 属性设置为 True，将模型转换为较旧的 NeuralNetwork 格式。在某些硬件上，旧格式的运行效率也可能更高。如果您不确定该使用哪种格式，可以分别以两种格式导出模型，并对比两个版本。

已知需要使用 use_legacy_format=True 导出的模型包括：GPT2、DistilGPT2。

当使用 GPT2 或 GPT-Neo 时，如果启用灵活的输入序列长度功能，转换过程会变得极其缓慢，并且会分配超过 200 GB 的内存。这显然是 coremltools 或 Core ML 框架中的一个 bug，因为所分配的内存实际上并不会被使用（计算机不会开始进行交换）。尽管经过数分钟后转换最终会成功，但生成的模型可能并非 100% 正确。随后加载该模型同样需要很长时间，并会再次进行类似的内存分配；进行预测时也是如此。从理论上讲，只要您有足够的耐心，转换确实能够成功，但这样的模型实际上并不可用。

将模型推送到 Hugging Face Hub

Hugging Face Hub 也可以托管您的 Core ML 模型。您可以使用 huggingface_hub 包从 Python 中将转换后的模型上传到 Hub。

首先，使用以下命令登录您的 Hugging Face 账户：

huggingface-cli login

登录完成后，按照如下方式将 mlpackage 保存到 Hub：

from huggingface_hub import Repository

with Repository(
        "<model name>", clone_from="https://huggingface.co/<user>/<model name>",
        use_auth_token=True).commit(commit_message="add Core ML model"):
    mlmodel.save("<model name>.mlpackage")

请确保将 <model name> 替换为您的模型名称，将 <user> 替换为您的 Hugging Face 用户名。

🤗 Exporters 快速上手指南

🤗 Exporters 是一个用于将 Hugging Face Transformers 模型导出为 Apple Core ML 格式的工具库，方便在 macOS、iOS、tvOS 和 watchOS 设备上进行高效的本地推理。

环境准备

• 操作系统：虽然可以在 Linux 上执行导出操作，但强烈推荐使用 macOS。因为模型导出后的验证步骤需要 Core ML 框架支持，该框架仅在 Apple 设备上可用。
• 系统版本要求：导出的模型采用 .mlpackage 格式（ML Program 类型），运行环境需满足：
  • iOS 15+
  • macOS 12.0+
  • Xcode 13+
• 前置依赖：
  • Python 3.x
  • Git
  • PyTorch 或 TensorFlow（取决于源模型）

安装步骤

通过克隆仓库并以可编辑模式安装来获取最新功能：

# 1. 克隆仓库
git clone https://github.com/huggingface/exporters.git

# 2. 进入目录并安装
cd exporters
pip install -e .

提示：国内开发者若遇到网络问题，可配置 pip 使用清华或阿里镜像源加速安装： pip install -e . -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

1. 导出默认模型

最简单的用法是将 Hugging Face Hub 上的模型直接导出为 Core ML 格式。以下示例将 distilbert-base-uncased 模型导出到 exported/ 目录：

python -m exporters.coreml --model=distilbert-base-uncased exported/

执行成功后，会在 exported/ 目录下生成 Model.mlpackage 文件。该文件可直接拖入 Xcode 项目中用于开发 macOS 或 iOS 应用。

2. 指定任务特性（Feature）

对于经过微调的模型（如文本分类），需要通过 --feature 参数指定具体的任务类型，以确保导出正确的输入输出接口。

例如，导出一个英文情感分析模型：

python -m exporters.coreml --model=distilbert-base-uncased-finetuned-sst-2-english \
                           --feature=sequence-classification exported/

3. 导出本地模型

如果模型权重已保存在本地目录（包含配置文件和权重文件），可以直接指向该路径进行导出：

python -m exporters.coreml --model=./local-pt-checkpoint exported/

常用参数说明

• --model: Hugging Face 模型 ID 或本地路径。
• --feature: 模型任务类型（如 image-classification, question-answering 等）。
• --quantize: 量化选项，设为 float16 可减小模型体积（默认 float32）。
• --compute_units: 计算单元优化，可选 all (默认), cpu_and_gpu, cpu_only, cpu_and_ne。

查看完整帮助信息：

python -m exporters.coreml --help