💻 欢迎参加 6 月 3 日 MS Build 上的 VS Code 直播活动。

使用 Foundry Toolkit for VS Code 转换模型

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

先决条件

创建项目

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

  1. 打开 Foundry 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（Hugging Face 模型）：从支持的模型列表中选择带有预定义配方的基础模型。
    • 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.

运行工作流

在模型转换中运行工作流是将预构建的机器学习模型转换为优化且量化的 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 合规性警报：在量化过程中，我们需要校准数据集。您可能会在继续之前被提示接受许可条款。如果您错过了通知，运行过程将暂停，等待您的输入。确保已启用通知并接受了所需的许可。显示免责声明的截图。

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

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

    • Quantization Dataset（量化数据集）：用于量化的校准数据集。

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

      1. 选择 HuggingFace Access Token（Hugging Face 访问令牌）按钮以获取您的 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.

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

    • Quantization Dataset Size（量化数据集大小）：用于量化模型的数据数量。

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

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

    评估

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

    • Evaluate on（评估目标）：您想要评估模型的目标设备。可能的值为：
      • 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 均可工作。
    • Evaluation Dataset（评估数据集）：用于评估的数据集。
    • Evaluation Dataset Split（评估数据集拆分）：数据集可能具有不同的拆分，如验证集、训练集和测试集。
    • Evaluation Dataset Size（评估数据集大小）：用于评估模型的数据数量。

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

  3. 通过选择 Run（运行）来执行工作流。

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

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

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

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

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

    1. 从右上角的下拉菜单中选择 Run with Cloud（在云端运行）。请注意，Evaluation（评估）部分处于禁用状态，因为云环境没有用于推理的目标处理器。

      Screenshot that shows Run with Cloud button.

    2. Foundry 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（在云端运行）。此选项仅支持模型转换和量化。您需要将已转换的模型下载到本地机器进行评估。

在云端运行不支持使用 DirectML 或 NVIDIA TRT for RTX 工作流进行模型转换。

注意

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

LLM model quantization（LLM 模型量化）：如果您想量化 LLM 模型，则需要 Nvidia GPU。

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

重新评估提示

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

转到“历史记录”面板并找到模型运行作业。选择 Action（操作）下的三点菜单以 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 下载。安装时还请勾选 使用 C++ 的桌面开发 工作负载。

查看结果

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

  • 找到您想要审查的工作流运行。每次运行都会列出一个状态指示器（例如“已成功”、“已取消”）。

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

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

  • 模型成功转换后，您可以在“指标”下查看评估结果。精度、延迟和吞吐量等指标会显示在每次运行旁边。

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

  • 您可以选择 Action（操作）下的三点菜单，与已转换的模型进行交互。

    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（导出）以与他人共享模型项目。这将复制不包含历史记录文件夹的模型项目。如果您想与他人共享模型，请选择相应的作业。这将复制包含模型及其配置的选定历史文件夹。

您学到了什么

在本文中，您学习了如何

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

另请参阅

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