参加你附近的 ，了解 VS Code 中的 AI 辅助开发。

使用 AI Toolkit for VS Code 转换模型

模型转换是一个集成开发环境，旨在帮助开发人员和 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 模型：从支持的模型列表中选择具有预定义配方的基础模型。
    • 模型模板：如果模型未包含在基础模型中，请为自定义配方选择一个空模板（高级场景）。

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

  4. 输入项目详细信息：唯一的项目文件夹和项目名称。

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

注意

首次创建模型项目时，可能需要一段时间来设置环境。即使您未完成设置也没关系。准备就绪后，您可以选择重新设置环境。显示重新设置的屏幕截图。

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

支持的模型

模型转换目前支持不断增长的模型列表，包括 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 门户上获取您的令牌并将其粘贴到 Quick Pick 中。按 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）生成默认作业名称，以便于跟踪。

    在作业运行期间，您可以通过选择状态指示器或“历史记录”面板中“操作”下的三点菜单，然后选择 Stop Running 来取消作业。

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

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

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

    1. 从右上角的下拉列表中选择 Run with Cloud。请注意，Evaluation 部分已禁用，因为云环境没有用于推理的目标处理器。

      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 容器应用 (ACA) 作业以运行云转换。对于正在运行的作业，您可以

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

      Screenshot that shows prompt for provisionning.

提示

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

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

注意

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

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

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

重新评估提示

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

转到“历史记录”面板并找到模型运行作业。选择“操作”下的三点菜单以重新评估模型。

您可以选择不同的 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++ 生成工具下载。在安装过程中还要检查使用 C++ 的桌面开发工作负载。

查看结果

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

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

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

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

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

    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 中启动。您可以自定义输入数据或参数以测试不同的场景。
注意

对于使用云转换的模型，在状态变为成功后，选择云下载图标将输出模型下载到您的本地计算机。显示操作的屏幕截图，包括从云端下载模型的图标。

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

提示

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

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

导出并与他人共享

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

您学到了什么

在本文中，您学习了如何

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

另请参阅

07/14/2025
© . This site is unofficial and not affiliated with Microsoft.