用 AI 工具包将模型转换为 VS Code

模型转换是一个集成开发环境，旨在帮助开发者和人工智能工程师在本地 Windows 平台上转换、量化、优化和评估预构建的机器学习模型。它为从Hugging Face等源转换的模型提供了简化的端到端体验，优化模型，并支持由NPU、GPU和CPU驱动的本地设备进行推理。

前提条件

创建项目

创建模型转换项目是机器学习模型转换、优化、量化和评估的第一步。

  1. 打开 AI 工具包视图，选择“模型转换”>启动模型转换

  2. 通过选择新模型项目开始新项目

    截图显示创建模型项目的视图，包括主侧边栏和创建项目按钮。

  3. 选择基础型号

    • 拥抱面模型：从支持的模型列表中选择带有预定义配方的基础模型。
    • 模型模板：如果该模型未包含在基础模型中，请为自定义配方选择一个空模板（高级场景）。

    显示模型列表的截图，比如bert、resnet、llama等。

  4. 输入项目详情：一个独特的项目文件夹和一个项目名称。

    在你选择的存放项目文件的位置，会创建一个带有指定项目名称的新文件夹。

注释

第一次创建模型项目时，搭建环境可能需要一些时间。 你不完成设置也没关系。你可以选择在准备好时重新设置环境。显示重启的截图。

AREADME.md每个项目都包含文件。如果你关闭了它，可以通过工作区重新打开它。显示型号说明文件的截图。

支持的型号

模型转换目前支持不断增长的模型列表，包括顶级的PyTorch格式拥抱面孔模型。详细型号列表请参见：型号列表

（可选）将模型添加到现有项目中

  1. 打开模型项目

  2. 选择“转换为>模型”，然后在右侧面板选择添加模型。

    展示如何添加模型的截图。它包含一个添加模型的按钮。

  3. 选择一个基础模型或模板，然后选择添加。

    在当前项目文件夹中创建一个包含新模型文件的文件夹。

（可选）创建一个新的模型项目

  1. 打开模型项目

  2. 选择“转换为模型”>，然后在右侧面板选择“新项目”。

    展示如何创建新项目的截图。它包含一个创建新项目的按钮。

  3. 或者，关闭当前的模型项目，从头创建一个新项目。

（可选）删除模型项目

  1. 打开模型项目，选择“模型 >转换”。

  2. 在右上角视图中，选择省略号（...），然后删除以删除当前选中的模型项目。

    截图展示了如何删除模型项目。它包含一个按钮，可以打开模型项目，进行平均和去远程处理。

运行工作流程

在模型转换中运行工作流程是将预建机器学习模型转变为优化和量化的ONNX模型的核心步骤。

  1. 在 VS Code 中选择 File > 打开文件夹以打开模型项目文件夹。

  2. 检查工作流程配置

    1. 部分车型>改装
    2. 选择工作流程模板以查看转换配方。

    截图显示了运行工作流程。有一个工作流程配置部分，包含转换、量化和评估。

    改宗

    工作流程始终执行转换步骤，将模型转换为 ONNX 格式。这一步无法被禁用。

    量子化

    本节允许你配置量化参数。

    重要

    Hugging Face 合规警报：在量化过程中，我们需要校准数据集。在继续之前，你可能会被提示接受许可条款。如果你错过了通知，运行进程将暂停，等待你的输入。确保通知已启用，并且你接受了所需的许可证。显示免责声明的截图。

    • 激活类型：这是用于表示神经网络中每一层中间输出（激活）的数据类型。

    • 权重类型：这是用来表示模型所学参数（权重）的数据类型。

    • 量化数据集：用于量化的校准数据集。

      如果你的工作流程使用需要Hugging Face许可协议批准的数据集（例如ImageNet-1k），系统会提示你在数据集页面接受条款后再继续。这是符合法律要求的。

      1. 点击 HuggingFace 访问令牌按钮即可获得您的 Hugging Face 访问令牌。

        显示输入令牌的截图 步骤1：开始获取Hugging Face访问令牌。

      2. 选择打开以打开拥抱脸网站。

        显示输入令牌的截图 步骤2：打开Hugging Face网站。

      3. 把你的代币拿到Hugging Face门户，然后粘贴到快速选择。按下回车键。

        显示输入令牌步骤3的截图：在下拉文本框输入令牌。

    • 量化数据集拆分：数据集可以有不同的拆分，如验证、训练和测试。

    • 量子化数据集大小：用于量化模型的数据数量。

    有关激活和权重类型的更多信息，请参见数据类型选择。

    你也可以禁用这个部分。在这种情况下，工作流程只会将模型转换为ONNX格式，但不会量化模型。

    评价

    在本节中，您需要选择用于评估的执行提供者（EP），无论模型转换的平台如何。

    • 评估目标设备：你想评估该模型的目标设备。可能的数值有：
      • 高通NPU：要使用这个，你需要一个兼容的高通设备。
      • AMD NPU：要使用这个，你需要一台支持 AMD NPU 的设备。
      • Intel CPU/GPU/NPU：要使用这个功能，你需要一台支持英特尔CPU/GPU/NPU的设备。
      • NVIDIA TRT for RTX：要使用这个，你需要一台支持 TensorRT 的 Nvidia GPU 的设备。
      • DirectML：要使用这个，你需要一台支持DirectML的GPU设备。
      • CPU：任何CPU都可以用。
    • 评估数据集：用于评估的数据集。
    • 评估数据集拆分：数据集可以有不同的拆分，如验证、训练和测试。
    • 评估数据集大小：用于评估模型的数据数量。

    你也可以禁用这个部分。在这种情况下，工作流程只会将模型转换为 ONNX 格式，而不会评估模型。

  3. 通过选择运行来运行工作流程

    默认作业名称是通过工作流程名称和时间戳生成的（例如，bert_qdq_2025-05-06_20-45-00）以便于追踪。

    在作业运行过程中，你可以通过选择状态指示器或历史作板下的三点菜单，选择停止运行来取消任务。

    Hugging Face 合规警报：在量化过程中，我们需要校准数据集。在继续之前，你可能会被提示接受许可条款。如果你错过了通知，运行进程将暂停，等待你的输入。确保通知已启用，并且你接受了所需的许可证。

  4. （可选）在云端运行模型转换

    云转换使你能够在本地机器没有足够的计算或存储容量时，在云端运行模型转换和量化。你需要Azure订阅才能使用Cloud Conversion。

    1. 从右上角下拉菜单选择“与云一起跑步”。 注意，评估部分被禁用，因为云环境没有用于推理的目标处理器。

      显示“用云运行”按钮的截图。

    2. AI Toolkit首先检查Azure云转换资源是否已准备好。如果需要，系统会提示您选择Azure订阅和资源组以配置Azure资源。

      显示配置提示的截图。

    3. 配置完成后，配置会保存在model_lab.workspace.provision.config在你的工作区根文件夹里。 这些信息被缓存，用于重用Azure资源和加快云转换进程。如果你想使用新资源，删除这个文件，重新运行云转换。

    4. Azure Container App（ACA）作业被触发以执行 Cloud Conversion。对于跑步工作，你可以：

      • 点击状态链接，导航至 Azure ACA 作业执行历史页面。
      • 选择日志以导航到 Azure Log Analytics。
      • 选择刷新按钮以获取当前作业状态。

      显示配置提示的截图。

提示

如果你没有用于LLM模型转换的GPU可用，可以使用Run with Cloud。 “运行云端”选项只支持模型转换和量化。你需要把转换后的模型下载到本地机器进行评估。

Run with Cloud 不支持使用 DirectML 或 NVIDIA TRT 进行 RTX 工作流程的模型转换。

注释

推荐栏会根据你的设备是否准备好运行转换后的型号，显示推荐的工作流程。你仍然可以选择你喜欢的工作流程。模型转换和量化：除了LLM模型，你可以在任何设备上运行工作流程。量化配置仅针对NPU进行了优化。如果目标系统不是NPU，建议取消勾选此步骤。

LLM模型量化：如果你想量化LLM模型，需要Nvidia GPU。

如果你想在带GPU的设备上量化模型，可以自己搭建环境，参考ManualConversionOnGPU。注意只有“量化”步骤需要GPU。量化后，你可以在NPU或CPU上评估模型。

重新评估的建议

模型成功转换后，你可以使用重新评估函数再次进行评估，而无需进行模型转换。

去历史板找模特运行的职位。在“动作”下选择三点菜单重新评估模型。

你可以选择不同的EP或数据集进行重新评估

显示重新评估的截图。它包含名称、系统和数据集设置等配置。

失败工作的建议

如果你的作业被取消或失败，你可以选择作业名称来调整工作流程并重新执行任务。为避免意外覆盖，每次执行都会创建一个新的历史文件夹，包含自己的配置和结果。

注释

有些工作流程可能需要你先登录 Hugging Face。如果你的任务在输出方面失败了，比如huggingface_hub.errors.LocalTokenNotFoundError： 需要 Token（'token=True'），但找不到令牌。你需要提供令牌，或者用“hf auth login”或“huggingface_hub.login'登录Hugging Face进入 https://huggingface.co/settings/tokens，按照说明完成登录流程，然后再试一次。

如果你的重新评估失败，输出警告如下未安装Microsoft Visual C++可再分发软件你需要手动安装以下软件包：

  1. Microsoft Visual C++ Redistributable
  2. （ARM64可选）从Microsoft C++构建工具下载。也请检查C++桌面开发安装时的工作量。

查看结果

转换历史板是你跟踪、审查和管理所有工作流程运行的中央仪表盘。每次运行模型转换和评估时，历史板都会创建新条目——确保完全可追溯性和可重复性。

  • 找到你想复核的工作流程运行。每个运行都会带有状态指示器（例如：成功，取消）

  • 选择运行名称以查看转换配置

  • 在状态指示器下选择日志，查看日志和详细执行结果

  • 模型转换成功后，你可以在“指标”下查看评估结果。准确性、延迟和吞吐量等指标会在每次运行中显示

    截图显示历史记录，包括姓名、时间、参数等。

  • 你可以在动作下选择三点菜单，与已转换的模型互动。

    显示动作的截图，包括推理、复制模型路径和重新评估。

复制转换后的模型路径

  • 从下拉菜单选择复制模型路径。输出的模型路径转换后，像c：/{workspace}/{model_project}/history/{workflow}/model/model.onnx会复制到你的剪贴板供参考。对于大型语言模型，输出文件夹会被复制。

使用示例笔记本进行模型推断

  • 从下拉菜单中选择“样本中的推断”。
  • 选择 Python 环境
    • 系统会提示您选择一个Python虚拟环境。默认运行时是：C：\Users\{user_name}\.aitk\bin\model_lab_runtime\Python-WCR-win32-x64-3.12.9.
    • 请注意，默认运行时包含所有需要的功能，否则请手动安装requirements.txt
  • 样本会在Jupyter笔记本中启动。你可以自定义输入数据或参数来测试不同场景。
注释

对于使用云转换的模型，当状态变成“成功”后，选择云下载图标，将输出模型下载到本地机器。显示作的截图，包括从云端下载模型的图标。

为了避免覆盖现有的本地文件，比如配置文件或历史相关文件，只下载缺失的文件。如果你想下载干净的副本，先删除本地文件夹，然后再下载。

提示

模型兼容性：确保转换后的模型支持推理样本中指定的EP

样本位置：推理样本与运行伪影一起存储在历史文件夹中。

导出并分享给他人

进入历史板。选择导出以与其他人共享模型项目。这样可以复制没有历史文件夹的模型项目。如果你想与他人共享模型，请选择对应的作业。这会复制包含模型及其配置的所选历史文件夹。

你学到了什么

在本文中，你学到了：

  • 在 AI Toolkit for VS Code 中创建一个模型转换项目。
  • 配置转换工作流程，包括量化和评估设置。
  • 运行转换流程，将预建模型转换为优化后的ONNX模型。
  • 查看转化结果，包括指标和日志。
  • 使用示例笔记本进行模型推断和测试。
  • 导出并与他人分享模型项目。
  • 使用不同的执行提供者或数据集重新评估模型。
  • 处理失败的作业并调整配置以适应重运行。
  • 了解支持的模型及其对转换和量化的要求。

参见