现已发布！阅读关于 12 月份的新功能和修复。

使用 VS Code 的 AI Toolkit 转换模型

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

先决条件

创建项目

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

  1. 打开 AI Toolkit 视图，然后选择 Models > Conversion 以启动模型转换

  2. 通过选择 New Model Project 来启动新项目

    Screenshot that shows view for creating model project, including Primary Side Bar and create project button.

  3. 选择基础模型

    • Hugging Face Model：从支持的模型列表中选择带有预定义配方的基础模型。
    • Model Template ：如果模型未包含在基础模型中，请选择一个空的模板用于自定义配方（高级场景）。

    Screenshot that shows model list, such as bert, resnet, llama and so on.

  4. 输入项目详细信息：一个唯一的 Project Folder 和一个 Project Name。

    将在您选择的用于存储项目文件的位置创建一个带有指定项目名称的新文件夹。

注意

首次创建模型项目时，设置环境可能需要一段时间。您可以不完成设置。准备好后，可以选择重新设置环境。截图显示重新设置。

每个项目都包含一个 README.md 文件。如果关闭它，可以通过工作区重新打开它。截图显示模型自述文件。

支持的模型

模型转换当前支持不断增长的模型列表，包括 PyTorch 格式的顶级 Hugging Face 模型。有关详细的模型列表，请参阅：模型列表

(可选) 将模型添加到现有项目

  1. 打开模型项目

  2. 选择 Models > Conversion，然后在右侧面板中选择 Add Models。

    Screenshot that shows how to add model. It contains a button to add models.

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

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

(可选) 创建新模型项目

  1. 打开模型项目

  2. 选择 Models > Conversion，然后在右侧面板中选择 New Project。

    Screenshot that shows how to create a new project. It contains a button to create a new project.

  3. 或者，关闭当前模型项目并从头开始创建新项目。

(可选) 删除模型项目

  1. 打开模型项目并选择 Models > Conversion。

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

    Screenshot that shows how to delete a model project. It contains a button to open mean and detele a model project.

运行工作流

在模型转换中运行工作流是将预构建的 ML 模型转换为优化的量化 ONNX 模型的核心步骤。

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

  2. 查看工作流配置

    1. 选择 Models > Conversion
    2. 选择工作流模板以查看转换配方。

    Screenshot that shows running a workflow. There is a workflow configuration section containing Conversion, Quantization and Evaluation.

    转换

    工作流将始终执行转换步骤，该步骤会将模型转换为 ONNX 格式。此步骤无法禁用。

    量化

    此部分使您能够配置量化参数。

    重要

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

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

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

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

      如果您的工作流使用需要 Hugging Face 许可协议批准的数据集（例如 ImageNet-1k），则在继续之前，您将在数据集页面上被提示接受条款。这是法律合规所必需的。

      1. 选择 HuggingFace Access Token 按钮以获取您的 Hugging Face 访问令牌。

        Screenshot that shows input token step 1: start to get Hugging Face Access Token.

      2. 选择 Open 以打开 Hugging Face 网站。

        Screenshot that shows input token step 2: open Hugging Face websites.

      3. 在 Hugging Face 门户上获取您的令牌，并将其粘贴到快速选择中。按 Enter。

        Screenshot that shows input token step 3: input token on dropdown textbox.

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

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

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

    您也可以禁用此部分。在这种情况下，工作流将仅将模型转换为 ONNX 格式，但不量化模型。

    评估

    在此部分，您需要选择要用于评估的执行提供程序 (EP)，无论模型是在哪个平台上转换的。

    • 评估对象：您要评估模型的目标设备。可能的值是
      • Qualcomm NPU：要使用此选项，您需要一个兼容的 Qualcomm 设备。
      • AMD NPU：要使用此选项，您需要一个具有受支持的 AMD NPU 的设备。
      • Intel CPU/GPU/NPU：要使用此选项，您需要一个具有受支持的 Intel CPU/GPU/NPU 的设备。
      • NVIDIA TRT for RTX：要使用此选项，您需要一个支持 TensorRT for RTX 的 Nvidia GPU 设备。
      • DirectML：要使用此选项，您需要一个支持 DirectML 的 GPU 设备。
      • CPU：任何 CPU 都可以工作。
    • 评估数据集：用于评估的数据集。
    • 评估数据集拆分：数据集可能有不同的拆分，如验证、训练和测试。
    • 评估数据集大小：用于评估模型的数据量。

    您也可以禁用此部分。在这种情况下，工作流将仅将模型转换为 ONNX 格式，但不评估模型。

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

    会自动生成一个默认的作业名称，该名称使用工作流名称和时间戳（例如，bert_qdq_2025-05-06_20-45-00）以便于跟踪。

    在作业运行时，您可以通过选择状态指示器或“历史记录”面板中的“操作”下的三点菜单并选择“停止运行”来取消作业。

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

  4. (可选) 在云端运行模型转换

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

    1. 在右上角的下拉菜单中选择 Run with Cloud。请注意，“评估”部分已被禁用，因为云环境没有目标处理器进行推理。

      Screenshot that shows Run with Cloud button.

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

      Screenshot that shows prompt for provisionning.

    3. 配置完成后，配置信息将保存在工作区根文件夹的 model_lab.workspace.provision.config 中。此信息将被缓存，以便重用 Azure 资源并加速云转换过程。如果您想使用新资源，请删除此文件并再次运行云转换。

    4. 会触发一个 Azure Container App (ACA) 作业来运行云转换。对于正在运行的作业，您可以

      • 选择状态链接导航到 Azure ACA 作业执行历史记录页面。
      • 选择 logs 导航到 Azure Log Analytics。
      • 选择刷新按钮获取当前作业状态。

      Screenshot that shows prompt for provisionning.

提示

如果您没有可用的 GPU 来进行 LLM 模型转换，可以使用Run with Cloud。Run with Cloud 选项仅支持模型转换和量化。您需要将转换后的模型下载到本地机器进行评估。

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

注意

Recommended 列将显示推荐的工作流，具体取决于您的设备是否已准备好运行转换后的模型。您仍然可以选择偏好的工作流。模型转换和量化：您可以在任何设备上运行工作流，除了 LLM 模型。量化配置仅针对 NPU 进行了优化。如果目标系统不是 NPU，则建议取消选中此步骤。

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

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

重新评估提示

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

转到“历史记录”面板，找到模型运行的作业。选择“操作”下的三点菜单，然后选择“Re-evaluate”重新评估模型。

您可以为重新评估选择不同的 EP 或数据集

Screenshot that shows re-evaluation. It contains configurations such as name, system and datasets settings.

失败作业提示

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

注意

某些工作流可能需要您先登录 Hugging Face。如果您的作业因输出类似 huggingface_hub.errors.LocalTokenNotFoundError: Token is required ('token=True'), but no token found. You need to provide a token or be logged in to Hugging Face with 'hf auth login' or 'huggingface_hub.login' 而失败，请导航到 https://hugging-face.cn/settings/tokens 并按照说明完成登录过程，然后重试。

如果您的重新评估因输出警告如 Microsoft Visual C++ Redistributable is not installed 而失败，您需要手动安装以下程序包

  1. Microsoft Visual C++ Redistributable
  2. (ARM64 可选) 从 Microsoft C++ Build Tools 下载。安装期间还请勾选 Desktop development with C++ 工作负载。

查看结果

Conversion 中的“历史记录”面板是您跟踪、审查和管理所有工作流运行的中央仪表板。每次运行模型转换和评估时，都会在“历史记录”面板中创建一个新条目，确保完全的可追溯性和可重现性。

  • 找到您想审查的工作流运行。每个运行都列有状态指示器（例如，成功、已取消）

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

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

  • 模型成功转换后，您可以在“Metrics”下查看评估结果。指标，如准确率、延迟和吞吐量，会与每次运行一起显示

    Screenshot that shows history, including name, time, parameters and so on.

  • 您可以选择“操作”下的三点菜单与转换后的模型进行交互。

    Screenshot that shows actions, including inference, copy model path and re-evaluate.

复制转换后的模型路径

  • 从下拉菜单中选择 Copy model path。输出的转换模型路径（例如 c:/{workspace}/{model_project}/history/{workflow}/model/model.onnx）将复制到您的剪贴板以供参考。对于 LLM 模型，将复制输出文件夹。

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

  • 从下拉菜单中选择 Inference in Sample。
  • 选择 Python 环境
    • 系统将提示您选择一个 Python 虚拟环境。默认运行时是：C:\Users\{user_name}\.aitk\bin\model_lab_runtime\Python-WCR-win32-x64-3.12.9。
    • 请注意，默认运行时包含所有必需项，否则，请手动安装 requirements.txt
  • 示例将在 Jupyter Notebook 中启动。您可以自定义输入数据或参数来测试不同的场景。
注意

对于使用云转换的模型，在状态变为Succeeded后，选择云下载图标将输出模型下载到本地机器。截图显示操作，包括从云下载模型的图标。

为避免覆盖任何现有本地文件（如配置或历史记录相关文件），只会下载缺失的文件。如果您想下载干净的副本，请先删除本地文件夹，然后再下载。

提示

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

示例位置：推理示例与运行产物一起存储在历史记录文件夹中。

导出并与他人共享

转到“历史记录”面板。选择 Export 与他人共享模型项目。这将复制模型项目但不包括历史记录文件夹。如果您想与他人共享模型，请选择相应的作业。这将复制包含模型及其配置的选定历史记录文件夹。

您学到了什么

在本文中，您学习了如何

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

另请参阅

07/14/2025
English 한국어 中文(简体)
© . This site is unofficial and not affiliated with Microsoft.