使用 VS Code 中的 AI Toolkit 转换模型

Name: Visual Studio Code
Author: Microsoft

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

先决条件

必须安装 VS Code。请按照以下步骤设置 VS Code。
必须安装 AI Toolkit 扩展。有关更多信息，请参阅安装 AI Toolkit。

创建项目

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

打开 AI Toolkit 视图，然后选择模型 > 转换以启动模型转换
通过选择 新建模型项目 来启动新项目
选择基础模型
- Hugging Face 模型：从支持的模型列表中选择带有预定义配方的基础模型。
- 模型模板：如果模型不包含在基础模型中，请选择一个空模板用于自定义配方（高级场景）。
输入项目详细信息：一个唯一的 项目文件夹 和一个 项目名称。

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

注意

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

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

支持的模型

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

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

打开模型项目
选择模型 > 转换，然后在右侧面板中选择 添加模型。
选择一个基础模型或模板，然后选择添加。

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

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

打开模型项目
选择模型 > 转换，然后在右侧面板中选择 新建项目。
或者，关闭当前模型项目并从头开始创建新项目。

（可选）删除模型项目

打开模型项目并选择模型 > 转换。
在右上角视图中，选择省略号（...），然后选择删除以删除当前选定的模型项目。

运行工作流

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

在 VS Code 中选择文件 > 打开文件夹 以打开模型项目文件夹。
查看工作流配置
1. 选择模型 > 转换
2. 选择工作流模板以查看转换配方。
转换

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

量化

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

重要
Hugging Face 合规性警报：在量化过程中，我们需要校准数据集。您可能会收到接受许可条款的提示，然后才能继续。如果您错过了通知，运行过程将暂停，等待您的输入。请确保已启用通知并接受了必要的许可。
- 激活类型：这是用于表示神经网络中每个层中间输出（激活）的数据类型。
- 权重类型：这是用于表示模型学习参数（权重）的数据类型。
- 量化数据集：用于量化的校准数据集。
  
  如果您的工作流使用需要 Hugging Face 上的许可协议批准的数据集（例如，ImageNet-1k），系统将提示您在继续之前在数据集页面上接受条款。这对于法律合规是必需的。
  1. 选择 HuggingFace 访问令牌 按钮以获取您的 Hugging Face 访问令牌。
  2. 选择打开以打开 Hugging Face 网站。
  3. 在 Hugging Face 门户网站上获取您的令牌，然后将其粘贴到快速选择中。按 Enter。
- 量化数据集拆分：数据集可以有不同的拆分，如验证、训练和测试。
- 量化数据集大小：用于量化模型的数。
有关激活和权重类型的更多信息，请参阅数据类型选择。

您也可以禁用此部分。在这种情况下，工作流将仅将模型转换为 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 格式，但不会评估模型。
通过选择运行来运行工作流

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

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

Hugging Face 合规性警报：在量化过程中，我们需要校准数据集。您可能会收到接受许可条款的提示，然后才能继续。如果您错过了通知，运行过程将暂停，等待您的输入。请确保启用通知并接受了必要的许可。
（可选）在云中运行模型转换

当您的本地计算机没有足够的计算或存储容量时，云转换使您能够在云中运行模型转换和量化。您需要 Azure 订阅才能使用云转换。
1. 从右上角的下拉菜单中选择 使用云运行。请注意，评估部分被禁用，因为云环境没有目标处理器用于推理。
2. AI Toolkit 首先检查是否已准备好用于云转换的 Azure 资源。如果需要，将提示您提供 Azure 订阅和资源组以配置 Azure 资源。
3. 配置完成后，配置将保存在工作区根文件夹的 model_lab.workspace.provision.config 中。此信息将被缓存，以便重复使用 Azure 资源并加快云转换过程。如果要使用新资源，请删除此文件并再次运行云转换。
4. 将触发 Azure 容器应用程序 (ACA) 作业来运行云转换。对于正在运行的作业，您可以：
  - 选择状态链接导航到 Azure ACA 作业执行历史页面。
  - 选择日志导航到 Azure Log Analytics。
  - 选择刷新按钮以获取当前作业状态。

提示

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

使用云运行不支持使用 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 而失败，您需要手动安装以下软件包

Microsoft Visual C++ Redistributable
（ARM64 可选）从 Microsoft C++ Build Tools 下载。安装时还请勾选 使用 C++ 进行桌面开发 工作负载。

查看结果

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

找到您想要查看的工作流运行。每次运行都会列出状态指示器（例如，成功、已取消）。
选择运行名称以查看转换配置
选择状态指示器下的日志以查看日志和详细的执行结果
模型成功转换后，您可以在“指标”下查看评估结果。指标（如准确性、延迟和吞吐量）会与每次运行一起显示。
您可以选择“操作”下的三点菜单，与转换后的模型进行交互。

复制转换后的模型路径

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

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

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

注意

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

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

提示

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

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

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

您学到了什么

在本文中，您学习了如何

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

另请参阅

07/14/2025